TattvaDocs
Core concepts

Skills & Reasoning

How Tattva turns a question into a checked answer, and the reusable skills it draws on.

When you ask a question, Tattva does not just pass it to a language model. A model reads what you mean. Code then checks the request, computes the figures and builds the answer's tables, notes and chart. A model writes the prose, a second model lists every claim it makes, and code checks each claim against the figures. Skills are your team's playbooks: guidance on how to analyse a kind of question, such as why a figure changed, that a planned answer follows.

How a question is answered

Answering a question: a model reads it, code checks the request, computes the figures and builds the answer, and a model writes the prose whose every claim code checks

Most questions take one path: a model reads the question, code checks and computes it, and code lays out the answer. A question that needs several separate results, such as different periods for different products or the difference between two changes, is planned: a model works through it step by step over your stored definitions, and code checks every step. See Planned answers.

You can watch the work in the Trace rail on the right of the Reasoning page, and read it afterwards on the Trail tab. For most answers about your metrics the rail shows two phases, Analyze and Reflect; Select and Execute appear only when a model has to fetch something code's figures don't cover. A planned answer shows its steps instead (below).

1. Read the question (Analyze)

A model reads the question into a structured reading: what kind of question it is (a lookup, a trend, a comparison, a "why"), which metrics and things you mean, the kind of period (code works out its dates), any day, week or month grain, a breakdown, filters and a comparison. It is given your team's glossary and conventions, and the date rules: "past week" is the 7 complete days to yesterday, and "last week" is Monday to Sunday.

2. Check the request (Analyze card)

Code checks that reading against what your team has defined:

  • Each name is matched to a stored definition, or to a line of a statement such as the P&L. Only the metrics you named are run.
  • A breakdown is kept only when the definition returns it. A value you name ("Store", a product) is checked against the data. A value that is the project's whole scope goes on the Scope line.
  • A kind of question your team switched off stays off. When part of the question is allowed, that part is answered with a note.
  • Short dates ("Feb 26") and the question's language are read in code, and code picks the answer's layout: one figure, a statement, a comparison, a ranking, a series or a breakdown.
  • If a word covers several metric variants, the metric's family decides: show all variants, ask you which one, use a default and give each other variant's figure in one "Also defined" line, or use a default and not mention the others.
  • Each input a metric needs gets a value: the period from your question, dates worked out from that period, or values you named ("from Warehouse 1").

If something is still unclear, you get a Needs clarification card with choices, one question at a time. If the question could not be read at all, you are asked to ask again: Tattva never guesses.

3. Compute (Analyze card)

Code finds the latest time BigQuery holds data for. A period such as "last 7 days" ends at the last complete day, and the answer says so. Then code computes every covered metric: for each metric with a stored definition it runs the stored query, or compiles the formula with its filters and approved joins, in BigQuery or on your uploaded files. Comparisons between periods, and figures by day, week or month, are computed in code too.

4. What one run cannot answer is planned

When one run of the stored definitions does not cover the question, or code cannot lay out its rows, the question is planned (see Planned answers): a model works through it with checked tools over your stored definitions. No model writes an answer of its own.

Some rules keep figures honest:

  • Two fact tables are never joined row by row, which would double-count.
  • A BigQuery table is never joined to an uploaded file.

5. Lay out the answer (code)

Code builds the answer from its figures, in a fixed layout for the kind of question: the tables with their totals, shares and changes, the notes, the period line, settle dates and a chart drawn from code's rows. The same question gets the same layout however it is worded. The parts come in one order on every answer: the verdict sentence, the rest of the prose, the tables, the notes, the period line, the Source line and the "What X counts" lines. See How an answer is laid out.

6. The prose, checked claim by claim

A model writes the prose from code's figures, in its own words and numbers. A second model reads every sentence and lists every claim it makes: each number and the figure it is, a rise or fall, better or worse, a size word, a rank, "all", a comparison, a share or a cause. Code checks each claim against the figures. A sentence that fails is revised once; one that still fails is dropped, and when the first sentence goes, code's own verdict line takes its place. See The claim check.

Answers that follow a playbook

An uploaded skill is a playbook: it says how to analyse, for example "split the change by channel, then by product; report the largest contribution". A question a playbook takes (it names the skill, or it is an analysis question, such as why a figure changed, of a kind the skill declares) is planned with the playbook's text: the planner follows it with its own checked tools, so every figure comes from a stored definition or code's arithmetic, and the answer's prose goes through the same claim check. A figure, ranking, comparison or trend question follows a skill only when it names it, and otherwise stays on the fast path. When several playbooks fit the question, the planner is offered them all and chooses one, or combines several (one for revenue, another for RTO); code checks that each covers the metric it is used for. A step needing a figure no stored definition gives is answered "Not available", naming the definition that would give it, and listed in Maintain › Feedback. A skill's own SQL or Python is never run. See Answers that follow a playbook.

Planned answers

A planned answer is worked out in steps, each one a tool code checks: look something up in the ontology, run a stored definition, do arithmetic on figures already computed (a difference between two percentages is in percentage points, "+10.86 pp"), ask you, or answer. The answer step names the figures and tables to show, and writes no prose: code lays the answer out, and the same writer as a one-request answer writes the prose from that layout (each figure shown with its name, period and direction, the notes, and whether the question's own assumption held). The model never writes its own SQL, so every figure comes from a stored definition or from code's arithmetic on them. Planning stops after 10 tool calls or 3 minutes (40 calls and 8 minutes when it follows a playbook), and the answer then says what is missing. A planned answer costs more than a one-request answer and takes longer: on prod before the claim check, a median of 31¢ and 55 seconds, or 84¢ and 131 seconds when it follows a playbook; the claim check's read, revision and re-read add about 13¢ and 39 seconds (measured on 16 recorded questions). Each question also stops at a hard limit against a run that keeps going ($2 and 3 minutes planned, $3 and 5 minutes with a playbook, 80¢ and 1 minute otherwise), and the answer then shows the figures it had under code's verdict line saying which limit it reached and what was done. See Questions that need a plan.

The Reasoning page

Sidebar → Reasoning. "Ask a question. The agent analyses, plans, executes, and audits its own answer."

  • Composer: "Ask anything against the current project…". Enter sends, Shift + Enter adds a line. Sessions opens past conversations; Sources narrows what the question may use.
  • Trace (right rail): the phases as they run, with time and tokens; for a planned answer, its steps under one Plan header.
  • Answer card: two tabs, Answer and Trail · N, and a toolbar under the answer. The answer ends with how long it took, what it cost and how much data it read, for example "Answered in 1 min 1 s · ≈ ₹19 model cost · 19.3 MB scanned". The time runs from when you asked to when the answer was ready. Model cost is the AI model spend for this answer: every model call it made, including retries, corrections and planning steps, priced at the providers' published per-token rates in US dollars, with prompt-cache reads and writes at their own rates. It is approximate because it is converted at a fixed rupee rate your operator sets and shown in whole rupees; it does not include BigQuery charges or the very small cost of matching your question against the ontology. Scanned is the data the answer's calculations read from BigQuery. A part is left out when there is nothing to report, for example an answer that ran no calculation. Everyone sees this line, also on answers reopened later.

Answer tab

The Trail tab

The Trail opens with How this was answered: only what changed against what you asked, each with a status such as Adjusted, Assumed or Not applied, or "Answered as asked." when nothing did. A follow-up opens with Read as: and your question written out whole, so you can see what was carried over. Details (for data analysts) lists every part of the question; Debug is shown only to superadmins and to owners, admins and ontology admins.

What follows depends on how the answer was made.

  • A one-request answer lists one card per phase that ran. On the Analyze card:
    • Metric family: which family applied, and which variant was chosen.
    • Parameters for this question: each input, its value, and its source.
    • Compute: for each metric run, the metric, the period and whether it used the stored definition; the value or table; Provisional or Incomplete notes; filters, inputs and joins; the SQL that ran; and Comparisons (computed in code).
  • A planned answer shows Steps in place of the phase cards: one numbered line per step in plain words with its result, a "↳ corrected" line where code rejected a call and the model corrected it, and "✓ Answered" at the end. How each figure was derived traces each computed figure back to its steps. Click a figure in the answer to jump to its steps. In the Trace rail, the steps are grouped under one header, "Plan · N steps · time · cost".

Compute block

A metric family shows up like this:

Metric family in the Trail

Kinds of skill

Tattva answers why a metric moved, where it is heading, how much an initiative moved it and how to shift a budget with a planned answer from your stored definitions. The skills that shipped for these (Root Cause Analysis, Forecast, Attribution, Optimize allocation and Foresight, all seeded) are deprecated: they stay in the catalogue, greyed, with Deprecated: and the reason, and older runs still name them, but they are never offered for a question and cannot be run. Upload your own playbook to guide how a kind of question is answered (see Custom skills).

Creative Concepts (seeded) is used only by Ontology › Make, which runs it to draft concepts from an analysis; it is never offered for a question.

Forward-looking research is separate; see Foresight.

Skills

A skill is a named, versioned playbook: guidance on how to analyse a kind of question, with the question kinds it answers and, optionally, the definitions and keys it works on.

Sidebar → Skills opens the Skill catalogue.

Skill catalogue

  • Search by slug, name or description, and filter by category.
  • List shows cards; Graph shows how skills call each other.
  • Each card shows the name, slug, a seeded / uploaded / forked badge, category, version, and how many upload warnings it has.
  • Upload .skill adds a new skill from a .skill archive, without a deploy. The upload checks the playbook's text against your ontology: a definition or key it names that does not exist is listed as a warning with the closest stored names, and a skill that writes its own SQL or Python is told that code is no longer run, with the figures it computed that will need definitions.

Click a skill to open it. Tabs include Overview, Playbook (its text, kept as written for you to read) and Runs.

  • Overview lists Trigger examples (questions that should use this skill), its warnings, and Try in Reasoning, which opens Reasoning with a question naming the skill. A deprecated or Make-only skill has no Try in Reasoning.
  • Delete removes an uploaded or forked skill. Seeded skills cannot be deleted.

See Custom skills to add your own.

Why it works this way

  • Numbers come from code. For defined metrics, code computes the figures and lays out the tables and chart itself. The prose a model writes is checked number by number against code's figures.
  • What a model writes is checked before you see it. A second model lists every claim the prose makes and code checks each against the figures; a sentence that fails is revised once, then dropped.
  • Nothing is hidden. Every step, input and query is on the Trail, with what changed against your question said first.
  • Ambiguity becomes a question, not a guess.
Skills & Reasoning — Tattva Docs