--- id: educacao/assistente-ia-coordenadores industry: Education usage: widely used effort: medium grain: One document per domain, one response protocol and one playbook per deliverable --- # AI assistant for coordinators Coordinators and educators ask in plain language and get auditable numbers, with a stated date range, no personal data exposed and no invented causes. ## Executive summary **For:** Schools, colleges and digital product creators who want coordinators and educators to query the data without going through the BI team. **What it solves** - Each coordinator asks their assistant and gets the same number a colleague got for the same question. - The assistant says how current the data is and what the dataset cannot answer, instead of filling the gap with a guess. - Student, guardian and buyer data stays inside the query: the answer comes out aggregated. **Why it matters:** When the assistant invents a number or a cause, the coordinator takes it to the meeting and trust in all the data drops with it. Writing the protocol and the right documents costs little and pays off for every future question, from anyone. It is also what lets you open access to more people without opening up personal data. **Business questions it answers** - How were this month's sales compared with last month and with the same month last year? - How many new enrollments did we make in this period, and how many are still active? - How many prospects for a given level are in progress in the CRM? - How current are these numbers? - What weighed more in this month's drop: volume or ticket? - What can the current dataset not tell me about this result? **What you need** - Curated tables in Nekt for each domain (enrollment, sales, media, scheduling), with stable column names - An owner who writes and maintains the context documents and the check numbers - A decision on who can see what: which tables each agent profile reads **What you get** - A response protocol that applies to every question - Domain documents with definitions, measured check numbers and limits - Playbooks that fix the structure of recurring reports - An entry index that tells the agent which documents to read ## Detailed ### The problem Coordinators and educators ask the assistant about enrollments, sales and the funnel, and the assistant answers with the first number the query returns. It adds up rows from different snapshots, calls a prospect a student, fills in incomplete series and explains a drop with a cause that is not in any table. Two people ask the same question and get different numbers. ### Business rules 1. **Context before SQL.** Fixed working order: fetch the semantic context using the user's original question, read the returned documents, check the table's last load, and only then generate and run the query. At the end, check the order of magnitude against the reference numbers in the domain document before delivering. (Avoid: Going straight to SQL with the table name that looks right.) 2. **Three document types, each with its own role.** The protocol says how to answer (number rules, what not to invent, format). The domain document says how to calculate each metric. The playbook says what to build and in what order. In a conflict, the domain document wins on calculation and the protocol wins on form. Also separate operational rules (which table, which date, how to count) from semantics (what each column means), and never carry the meaning of one table over to another without a written rule. (Avoid: A single document mixing column definitions, counting rules and report format.) 3. **An entry index with Read when.** Keep a root document that lists each document with a Read when line (topic and words in the request). The agent reads every one that matches; chained metrics are read together (a ROAS question also reads media and revenue). If no document covers the request, the agent says so instead of improvising. Every new or renamed document updates the index in the same task. (Avoid: Letting the agent pick documents through semantic search alone.) 4. **Numbers only from the query, always with a date range.** Never fill in a number that did not come from the query, and never complete or round a series. Null means absence and is reported as absence. Every time-based answer states the start date, end date and last load date (MAX of the date column). The current day is partial: compare only closed days and say so. (Avoid: Estimating the current month or comparing today against the dashboard.) 5. **A small base invalidates percentages.** When the comparison period is zero, negative or less than a quarter of the current value, write low base and show the change in reais. Every relevant change carries the amount in reais alongside the percentage. Changes in rates are given in percentage points. Do not add percentages or averages across rows: recompute the ratio from the totals. (Avoid: Reporting +1,775% on a base of R$ 20 thousand.) 6. **Point to the fact, never the cause.** Breaking down is analysis: volume versus ticket, which group or campus explains the change in reais. Explaining why it dropped or recommending action, with no productivity, target or budget data in the dataset, is invention. Close with the list of what the current dataset does not answer. When the month drops against the previous one and rises against last year, show both comparisons and do not pick one. (Avoid: The drop came from lower team productivity.) 7. **An event is a cohort that does not shrink.** An event question (how many new enrollments between A and B) uses the event date and the whole end date, not midnight. The historical cohort does not change afterward: if 20 joined and 2 canceled, there were 20 new enrollments; the current status (18 active, 2 canceled) comes separately, from the most recent status of the same enrollment. A position question (how many were enrolled on D) uses a single snapshot. (Avoid: Answering 18 new enrollments because 2 have already canceled.) 8. **People only on request, and capped.** By default, answer with counts and sums. List people only when the person asking requests it, with the columns the question needs and up to 50 rows. In coordinator and media agents, email, name, phone and ID number stay inside the query only (to match sources) and never appear in the answer. A CRM contact may be a guardian, a prospect or a family member. (Avoid: Returning the list of buyers with email when the question was how many bought.) 9. **Curated access and refusal with a pointer.** Coordinator agents read only a curated set of tables, cited by full name in the document. An access error outside that set is the scope working: the agent replies that it is outside its access and says where it lives (dashboard, spreadsheet, another owner), without requesting new permissions. Each document includes a What this source does not answer and where to look table. (Avoid: Trying another raw table when the curated one does not have the answer.) 10. **Same criteria for every user.** The same question uses the same calculation for any person, conversation or dashboard. Filters follow this priority: those explicit in the current question, those clearly carried over in the conversation, those active on the dashboard, the document's default rules. A recurring report follows the playbook: an executive summary of up to five lines before any table, the month compared with the previous month and the same month last year always together, year to date, breakdowns and a methodology footer. The medium changes (page, document, markdown), not the structure. (Avoid: Each coordinator gets a different date range for How were sales.) ### Which document handles what Every question goes through all three, in this order of precedence. - **Entry index** → Which documents to read (`Read when: `) - **Response protocol** → How to answer (`wins on form`) - **Domain document** → How to calculate (`wins on calculation`) - **Playbook** → What to build and in what order (`governs structure`) - **Table semantics** → What each column means (`never becomes a counting rule`) - **Allowed tables list** → What the agent can read (`full name`) ### Definitions | Metric | Definition | |---|---| | Last load | the latest date in the date column of the queried table, run before the answer and written into it | | Date range | start date and end date, inclusive, plus the last load date; closed days by default | | Report windows | Month = last closed month; MoM = previous month; YoY = same month last year; YTD = January 1 through the end of the month against the same span last year | | Low base | a comparison period that is zero, negative or less than a quarter of the current value; the change in reais is shown instead of the percentage | | Rate change | the difference in percentage points between the two rates, recomputed from the totals | | Entry cohort | distinct people with the event (enrollment, sale, sign-up) within the period; does not change with later status | | Current cohort status | the most recent available status of each item in the cohort, shown separately from the historical total | | Check number | a value measured with date and time for a closed month, written in the document, that the agent must reproduce | ### Pitfalls - **Invented cause.** The assistant explained a drop in sales by lower team productivity and suggested prioritizing conversion, on a dataset that only had sales, cancellations and sign-ups. How to avoid: Write in the protocol what the dataset does not have and require the list of what the data does not answer. - **Percentage on almost nothing.** Campus and consultant rankings showed four-digit changes on tiny bases, and those names went to the top of the summary. How to avoid: Low base rule and sorting by absolute change in reais. - **The cohort shrank.** The question was how many new enrollments there were, and the agent filtered on today's active status, leaving out those who canceled later. How to avoid: Cohort by event in the period; current status in a separate block. - **Last day cut off.** The period up to the 31st became the 31st at 00:00, and every enrollment from that day was left out. How to avoid: Compare by date, with the end date inclusive. - **A lead that is not a lead.** In the scheduling tool, a lead was someone who booked a call. The agent presented that number as Leads and MQL, which in that company came from another source outside the database. How to avoid: Name each concept after its source and write in the document what it is not. - **Old address in the document.** After restricting coordinators' access to a curated set, documents still cited the old tables and the agent hit an access error on every question. How to avoid: Update the full names on the same day as the change and treat access errors as out of scope. ### Acceptance test - [ ] The same question, asked by two users in different conversations, returns the same number, the same date range and the same last load date. - [ ] For the reference closed month, the agent reproduces the document's check numbers (for example, revenue to the cent and the exact number of sales). - [ ] Every answer with a time range states the start date, end date and last load. - [ ] Asking a coordinator agent for the list of buyers returns a refusal and the aggregated total; in an agent with permission, the list comes back with at most 50 rows. - [ ] Asking why a number dropped returns the breakdown in reais and the limits statement, with no cause or recommendation. ### Context document ```text Assistant response protocol - Always: fetch the semantic context using the original question before any SQL; read the returned documents; if there is a playbook for the deliverable, it governs the structure. - Run MAX() and state the last load in every answer with a time range. The current day is partial: compare only closed days. - Check the order of magnitude against the reference numbers in the domain document before delivering. - Precedence: the domain document wins on calculation; this protocol wins on form. Explicit user question > operational rules > table semantics. - Never fill in a number that did not come from the query. Null means absence, not zero. - Comparison base zero, negative or less than a quarter of the current value: write low base and show the change in reais. Rate changes in percentage points. Do not add percentages or averages across rows. - Point to the fact, never the cause. Do not recommend action. Close with what the dataset does not answer. If MoM and YoY disagree, show both. - Events use the event date, with the end date inclusive. The historical cohort does not shrink with later cancellations; current status comes separately. - Answer with counts and sums. List people only when asked, with the necessary columns and up to 50 rows. In coordinator agents, never list email, name, phone or ID number. - Read only the tables listed by full name. An access error outside them = out of scope: say where the answer lives, without requesting access. - Filters: current question > conversation context > dashboard filters > document default. - Sales report with no specified content: follow the playbook (executive summary, month with MoM and YoY, YTD, year trajectory, breakdowns, rankings by change in reais, interpretation and methodology). - Values in pt-BR format, no emoji, footer with source and last load. Client-specific exceptions: - : the coordinators' agent reads only ; targets live in the and are not in the database. - : is not ; the official metric comes from and is not in the database. - : check number for the reference month: = in . ``` ### Variations - **Handoff by source:** One document per source (sales, media, scheduling) and one that crosses sources, each with a section for the agent. - **Scope by profile:** Different agents for coordination, paid traffic and leadership, with different table lists. - **Educators and CRM:** Questions about prospects and stages answered as CRM analysis, never as enrollment.