kadence
Proof

What a link to a document is worth

Five real questions, answered by grep and by a link — 1.3 MB of candidates against 39 KB.

This probe exists because an argument I had made was wrong, and the fastest way to find out was to measure it.

The original recommendation was: do not build documents, because git already versions files and the event model adds nothing to a document. The objection was about linkage, not storage — and git genuinely does not have it. Git versions a file; it does not know that this file explains this task.

The hypothesis

If we let documents be linked to tasks and decisions so they come back with the work in one call, for a developer or an AI agent picking up unfamiliar work, then they get the context they need without guessing which of dozens of files is the relevant one.

What would make it false: if ordinary search already finds the right document cheaply, the link adds nothing and is not worth building.

The experiment

Five real questions someone faces when picking up work in the kadence repository, and the document that answers each. Two paths measured for every one:

  • Today — an agent greps docs/, SPEC.md and README.md for the natural term, then has to open the candidates to see which is relevant. The cost is the sum of their bytes.
  • With a link — one document, opened directly.

Results

QuestionTermCandidatesBytes in candidatesWith a linkDifference
What must not break in the --json contract?json27327,8707,24145×
May we add a folder to the user's repository?git35407,7966,52062×
Why is board --json a problem at scale?board18250,9436,65638×
Which invariants govern folding?state14180,8798,96620×
Why is conflict-freedom not the headline?conflict10154,0499,31817×
Total1,321,53738,70134×

What it actually showed

Search finds the answer in all five cases. The problem is not that the document cannot be found — it is that it sits among 10–35 candidates, and knowing which one is needed means opening them.

So the link does not save the search. It saves the sifting, and sifting is what costs a context window.

The stronger argument needs none of these numbers: grep requires knowing the term. The whole product bet is that an agent does not know what it does not know. A link works without a search word, because it arrives with the task.

Limits that make this weaker than it looks

  1. This is a document-heavy repository — 37 documents against 4 tasks. In a typical project the ratio is different and the gap is smaller.
  2. "The agent opens every candidate" is an upper bound. A capable agent discards some by filename, and the filenames here are descriptive (probe-c-agent-cost.md). How many it would really discard could not be modelled honestly, so the true figure is below 34× — by an unknown amount.
  3. The questions were chosen by someone who knew the answers. That is the most serious bias in the experiment.

Even allowing for all three, the gap between 154 KB of candidates and 9 KB of answer in the worst of the five cases is not explained by error.

What was built, and what was not

Not kadence doc — not a command that creates and stores documents. That argument stood: git already versions files.

Links. A task or a decision points at a document, and the document comes back with it in --json. The document is written in ordinary markdown, as before. kadence takes on the one thing git does not do: knowing that this file belongs to this work. See Recording why and ADR-010.

Raw data

The full write-up is in the product repository: probe-d-docs-linkage.md.

What an answer costs an AI agent

Four repositories built through the real CLI at 10, 50, 200 and 1,000 tasks — and what each path costs to read.

Decisions

Every architectural decision, what was measured to reach it, and what would make us revisit it.

On this page

The hypothesisThe experimentResultsWhat it actually showedLimits that make this weaker than it looksWhat was built, and what was notRaw data