The AI-Readiness Repair Matrix

Simple questions make AI analysts look ready. Count users. Filter one segment. Pull one metric.

Real business questions are different. They combine several primitives. Each primitive is another place where the analyst can be right or wrong.

That is why reliability does not degrade slowly. It compounds. A system that is excellent on one-primitive questions can become unreliable once the question asks for four or five things to be resolved at once.

The standard response is a shopping question: a semantic layer? A better model? After 1,488 graded runs against eight versions of one warehouse, I think readiness is more specific than that. It is a property of each question you ask, and repairing it is a routine, not a purchase:

1. Find the primitive that failed. Decompose the question into the primitives it forces; one of them broke.
2. Find where its grounding lives. The fact that settles that primitive is stored somewhere, or nowhere.
3. Move it to the cheapest place the agent cannot skip.

Earlier in this series I measured how much structure buys, what the agent does when there is no answer, and how to make single claims inspectable. All three treated the question as a unit. This piece takes it apart: the routine above, with the measured evidence behind each step.

The short version#

A question is a list of primitives#

Take one ordinary business question and read it the way the agent has to.

Each highlighted piece is a primitive: one irreducible choice that must be resolved before the query means anything. (The test harness uses the same word, so this piece matches the repo.) The gloss shows what makes such questions dangerous: some primitives have no words. "Billed revenue" does not announce that annual plans bill once, as a full year's cash. Nothing says whether staff accounts count. The agent resolves the silent primitives anyway, with defaults nobody chose.

To resolve a primitive correctly, the agent needs grounding for it: the piece of business knowledge that settles the primitive. Staff accounts are not customers settles the segment. Annual amounts enter monthly recurring revenue as one twelfth settles additivity. The data ends on 12 July settles coverage. A primitive with no grounding available does not go unanswered; it gets resolved by a guess that looks like a default. My first experiment measured grounding in bulk, one warehouse against another. This piece assigns it per primitive, because the agent does not need a well-grounded warehouse in general. It needs one specific fact, for one specific primitive, at the moment it writes the clause.

Two consequences carry the whole method.

Errors compound. At 90% per primitive, a five-primitive question comes out right 59% of the time (0.9⁵). A system that looks excellent on simple questions can become unreliable on real business questions without anything visibly breaking.

And a failure has an address. When the answer is wrong, some specific primitive failed. The useful question is which primitive failed and where its grounding lives.

Grounding lives in one of five places#

The homes are concrete: a column, a table's grain, a comment, a wiki page, a metric definition, a lookup table that cleans raw values, or a runtime check. Stack them the way a real warehouse does, and write the same grounding, staff accounts are not customers, at every layer.

before serving: the number must be thegoverned metric result — otherwise refuseactive_customers includes user_type = 'customer'

metric: active_customers  filter: user_type = 'customer'

dim_users.user_type  →  'staff' | 'customer'

comment on column users.internal:  'true for staff and test accounts'

The chip on each layer says whether the agent can ignore that fact and still answer. A comment can go unread. An optional metric can be bypassed. A runtime check can stop the answer. I will call that property skippable, and it explains much of the matrix later in the article.

The repair algorithm#

That is all the vocabulary the routine needs. Here it is on one page, built to be scanned; the three sections after it walk each step with the tools, the traps, and the measured evidence.

Step one: find the primitive that failed#

When a number comes back wrong, you have three instruments, ordered by how much of the agent's work you can see.

Calculate the wrong answers#

Do not only calculate the correct answer. For the failed question, also calculate the answers you would get if one primitive were missing.

The reason is simple: a wrong number is often the right answer to a broken version of the same question. Match the agent's wrong number to that broken version, and you know which primitive to inspect first.

For example, take: How much MRR came from Paid Search customers in June? Suppose the correct answer is $12k, but the agent returns $48k.

In this example, the agent's $48k is not random. It is exactly the number you get when annual plan cash is summed as if it were monthly recurring revenue. That tells you where to look next: the additivity grounding. Does the model expose a customer-month snapshot? Is the MRR metric enforced? Or is the rule only written in prose where the agent can skip it?

This is triage, not final proof. It narrows the repair from "the answer is wrong" to "inspect this primitive first".

Confirm it in the SQL trace#

The wrong-answer test gives you a suspect. The SQL trace confirms whether that suspect actually failed.

Continue the example above. The agent returned $48k, and $48k is what you get when annual cash is summed directly. Open the SQL trace and ask one question: did the query use the monthly MRR snapshot or governed MRR metric, or did it sum raw billing cash?

If the trace says sum(r.amount) from fct_billing, additivity failed in the aggregate expression and the fact table. If the trace uses fct_customer_month_snapshot and mrr_amount, additivity is probably not the first failure; go back to segment, join path, or coverage.

Use the same check for every primitive:

where raw_channel = 'Paid Search'

select count(*) as customers

join dim_customer c
  on u.current_customer_id = c.customer_id

select count(*) as active_customers
from events

select sum(r.amount) as mrr
from fct_billing r

where month = '2026-08'
-- no coverage check

The result is not just "the SQL is wrong". It is more precise: now you know whether additivity actually failed, and where it failed.

The peel: remove one primitive and ask again#

If you only have the chat answer, simplify the question and ask again. Remove the segment. Remove the join. Remove the date window. When the answer starts working, the primitive you just removed is where to inspect.

In the same example, peel the question into a shorter version each time:

The peel does not prove the repair. It gives you a fast next move when all you have is the chat window.

This is the manual version of what the evidence graph automates: every claim is tied back to the query result that supports it.

Step two: find where the grounding lives#

Once you know which primitive failed, the usual advice turns vague: improve the model, add more context. Three tools make it mechanical.

Name the grounding fact#

Before you can repair the failure, name the fact the agent needed but did not use. Keep it concrete.

• Staff accounts are not customers.
• ppc, paid-search, and Paid Search are the same channel.
• Annual amounts enter monthly recurring revenue as one twelfth.
• The data ends on 12 July.

Find where it lives#

Now look for that fact in the system. Is it in the raw values? In a comment or wiki? In the data model? In a metric definition? In a runtime check?

Sometimes it is not in the system at all. It only lives in someone's head. Then the agent cannot use it reliably.

The common failure is not missing knowledge. It is knowledge in the wrong place. In my test, the additivity rule was written above the revenue column, and the agent still summed annual cash as if it were monthly revenue. The fact existed, but it lived somewhere the agent could skip.

The skip test: can it answer without using the fact?#

By skip, I mean this: the agent can produce and serve an answer without using the grounding fact you found. It may not read the comment. It may choose raw SQL instead of the metric. It may join through another path. The fact exists, but it is not on the route the answer must travel.

Ask one practical question: can the agent still answer if this fact is ignored?

Step two ends with a verdict, and there are only three:

Step three implements the verbs.

Step three: move the fact where it cannot be skipped#

Do not fix this with another prompt note. Use the result of step two:

• If the fact is missing, define it.
• If the fact is in a skippable place, move it.
• If the fact is incomplete, add the missing piece.

The type of fact usually tells you where it should go. These are the repair patterns this study measured.

The six recipes below are reference material, not stages: read the one your fact matched. Each follows the same pattern: the situation, the move, and what it measured on the bench.

The decode: put the vocabulary in the data#

The situation: the same business value appears in several forms. ppc, paid-search, and Paid Search all mean the same channel. FR means France.

The repair is a small data modelling exercise with exactly two moves:

1. Normalise the code. Store one machine value: paid_search.
2. Store the name beside it. Store one human label: "Paid Search". This is Kimball's thirty-year-old rule: keep the decode beside the code.

Both columns live on the dimension the agent already queries. Nothing is renamed, nothing breaks; the repair is pure addition.

Why two columns, and not just clean values? Because I built the one-column version, and it is a trap.

What it measured. A vocabulary written only in a comment did not work. A vocabulary built into the data model did. Synonym questions went from 3% with prose to 75–100% with modelled values. Code questions, such as FR meaning France, showed the same pattern.

The declared grain: people are not rows#

The situation: the fact says what one row of a table means. "One row is a subscription term, not a customer".

The repair is a modelling exercise with two moves:

1. Name the grain in the table itself. A table where one row is one subscription term is called subscription_terms, not subscriptions. The name is grounding the agent cannot avoid reading; declaring the grain is a core Kimball dimensional modelling rule.
2. Expose both counts as separate metrics. Where "how many" has two honest readings, define both: one metric counts rows, one counts people.

What it measured. Grain failures look like this: you ask for people, and the agent counts rows. Naming the table grain and exposing both counts moved grain accuracy from 56% on raw tables to 86% on the star and 94% with star + docs. This is still basic modelling: no new rule, no semantic layer, just a clear grain and the right metrics.

The label on the dimension: keep the attribute on the route#

The situation: the question filters by an attribute, but the readable label lives one join away. For example, users have a platform key, and the platform name sits in a lookup table.

The repair is a modelling exercise with two moves:

1. Put common labels on the dimension the query already reads. If most questions start from users, platform_name belongs on dim_users.
2. Keep lookup tables for real vocabularies. A channel can have its own dim_channel. A small platform lookup can still exist, but the agent should not need an extra join just to read the label.

This is the Kimball avoid-snowflaking guidance applied to an AI analyst: if it describes the user, put it on dim_users. If it is its own business thing, give it its own dimension.

dim_users(user_id, plan, platform_key)dim_platform(platform_key, platform_name)

dim_users(user_id, plan,  platform, platform_name)

What it measured. I tested two versions of the same star: one with the platform label on dim_users, and one with the label one join away. The label-on-dimension version did better (89% vs 75%). The gap is close to the noise floor, so I would not over-read the exact numbers. The lesson is simpler: put common labels where the agent already looks.

The stated default: document what to do, not just what it means#

The situation: the question leaves something unsaid. Should staff accounts count? Should test accounts count? The agent will still pick a default.

The repair is simple:

1. Describe the column. Keep the normal definition.
2. State the default. Say what to do when the question is silent.

What it measured. A comment that only describes the column was not enough. The missing piece was the default: what to do when the question says nothing. Adding that sentence fixed the failing questions; removing it brought the failures back. Document the action, not only the meaning.

The snapshot and the rule: additivity cannot live in prose#

The situation: the sentence says an amount must be transformed before it may be summed. A stock, a unit, an annual amount.

This repair has three parts:

1. Build the snapshot. Put MRR on a periodic snapshot fact: one row per customer per month. The annual amount is already converted into a monthly value.
2. Define the metric there. Put mrr on that snapshot in the semantic layer. MetricFlow's non_additive_dimension is the relevant dbt field: MRR can be summed across customers, but not blindly across time.
3. Enforce the metric route. If the agent can ignore the metric, it will. The guardrail makes the policy explicit: no governed metric result, no answer.

What it measured. Additivity was the cleanest failure in the study. Raw tables and raw + docs got every MRR question wrong: 0 of 12 in both cases. The comment explained the rule, but the agent still summed annual amounts as if they were monthly revenue.

The fix was structural:

Practitioner conclusion: prose does not fix additivity. Put the monthly value in the model, define the metric on that model, and require the agent to use it. A metric the agent can ignore is still advice; an enforced metric is policy.

The published window: answerability needs fact and restraint#

The situation: some questions are outside the data. The period may not exist yet. The term may not be defined. The agent needs to know the boundary, and it needs a rule for what to do when the question crosses it.

There are two repairs:

1. Publish the boundary as data. Compute the min and max dates for each dataset and expose them as a lookup the agent can check. Recompute it with each load. This is metadata, not a wiki sentence someone maintains by hand.
2. Enforce refusal. If the requested period, term, metric, or path is outside the governed contract, the agent should refuse. This is a runtime check inside the agent: no governed path, no answer.

What it measured. In the mini matrix, data modelling made answerable questions much stronger. It did not make the agent good at saying no. On the no-answer questions, most warehouse versions stayed weak: 36–47% correct. The provenance guardrail reached 78%.

The lesson is simple: accuracy and honesty are different controls. A better data model helps the agent answer. A runtime check defines when it must stop.

The Repair Matrix#

The matrix is built from four repair areas: data modelling, documentation, semantic layer design, and agent guardrails. Each area has a different owner and a different reference point.

Some repairs stay in one area. Decode values, name the grain, or state the default. Those are cheap. Other repairs cross areas. Measure/aggregation needs a clear fact table and an enforced metric; additivity also needs a snapshot. Answerability needs computed coverage and refusal. This is the repair matrix: for each measured primitive family or subcase, find the cheapest location that worked.

Read it as a budget. Most rows are fixed by ordinary data modelling. The right edge is needed for three rows: measure/aggregation, additivity, and answerability. The left side, where many facts live today, is usually too easy for the agent to skip.

The same four areas define ownership. A failed primitive should land in the backlog of the layer that can actually fix it.

Run it as an AI-readiness audit#

The same anatomy that repairs a broken answer tells you, in advance, which answers will break. That audit is what I would ship.

Start from the questions, not the schema. Collect what people really ask: board, growth, finance, support questions. Decompose each one the way the gloss at the top does, and ask which primitive would fail first on your stack.

Build ladders, not a question list. Add one primitive per rung, the way the SQL figure climbs. The first rung should be almost boring; the fourth should read like a line from a board memo. The rung where answers start failing names the primitive, and the wrong answers confirm it.

Put in questions that have no answer. A period you do not hold, a term nobody defined, a false premise. Without them you can only measure whether the analyst is right, never whether it answers when it should not, and that second failure is the one that reaches a board deck.

Ask everything three times, and score by primitive, not by average. Errors compound as primitives stack. Here is why the ladder matters more than the question count:

On one-primitive questions, every warehouse looked perfect. The failures appeared only when questions combined multiple primitives. That is why a demo suite built from simple questions can look safe while real business questions still fail.

The audit should return a repair backlog, not just a score. Each failed primitive should point to one kind of work:

• Data cleaning: raw values need normalising.
• Data modelling: grain, joins, or snapshots need to move into the model.
• Documentation: defaults and edge cases need to be stated clearly.
• Semantic layer: governed metrics and aggregations need to be declared.
• Agent guardrails: the agent needs a runtime rule for refusal or provenance.

The bench behind the numbers#

The numbers come from one test warehouse, rebuilt eight ways. The data stayed the same. Only what the agent could see changed. Six versions carry the argument and appear in every figure below. The other two are structural probes of the star that move one label between a dimension and a lookup table; they are in the totals and in no chart.

Main run: 62 questions × 3 repetitions × 8 warehouse versions, using gpt-5-mini: 1,488 graded runs. Most questions combine one to four primitives. Twelve have no honest answer. The LLM-judge arm is a separate probe.

I also reran the headline scorecard once on gpt-5.6-terra. Read it for direction, not exact cell values.

Two caveats: the warehouse is synthetic, and repeated gpt-5-mini runs disagree in about 25% of question-version cells. The method and data are on GitHub.

The scoreboard#

Every arm, on the three metrics this series always reports.

Two things to notice in the mini run. First, coverage stays high until the judge, where refusals increase. Second, silent error changes much more than balanced accuracy. Two arms can look close on accuracy while one serves many more confident wrong answers.

What each improvement bought#

The same numbers, read as investments. Each row is one step up the ladder, and the chips are what that step changed.

On the mini run, the largest structural gain came from raw tables to a star model. Documentation helped on the star and hurt on raw tables. The optional semantic route did not improve this run. The largest overall gain came when the governed route was enforced.

Per primitive family: the matrix itself#

The third perspective explains everything the scoreboard averages: every measured primitive family against every version of the warehouse.

And the same grid on the other dial, how often each cell misled instead of answering:

Read the matrix by row. The segment rows, grain and join path mostly need modelling. Additivity needs a snapshot. Answerability needs refusal handling. A single score hides this; the matrix shows which repair to make.

What a stronger model changes#

After the main run, I reran the headline scorecard on a stronger model: gpt-5.6-terra. I would not put the full primitive-by-primitive Terra table in the article. It is useful audit detail, but it asks the reader to compare too many cells. The top-line comparison is enough.

Three things changed.

Terra raises the floor. The raw warehouse got much better, and silent error fell sharply. A stronger model can extract more from weak structure.

Clean structure still matters. The best unguarded result is not raw plus a stronger model. It is the clean star, documented, with governed metric definitions available.

Governance is a product choice, not just an accuracy trick. With the semantic layer optional, Terra scored well, but used the governed route less often. When the route was enforced, governed use stayed at 100%, but coverage fell. So the choice is explicit: allow more answers, or require every served number to have a governed trace.

There is no AI-ready warehouse#

There is no single switch that makes a warehouse AI-ready. A question can be ready for one primitive and fragile for another. Segment can be fine while additivity is broken. A metric can be defined while the agent is still allowed to ignore it.

The practical work is concrete: clean the values, name the grain, state the defaults, publish the coverage window, model stocks on snapshots, and enforce governed metric routes where silent errors are costly.

The cleanest definition I can now give: AI-ready data means every question primitive people rely on has a governed path, and the agent refuses when that path does not exist. The repair matrix is the checklist for finding which path is missing.