Skip to Content
📖 Guide DocumentsEvidence GraphAdoption

Adoption

Nothing here requires a new process. If your team already keeps requirements in the repository and hands them to an agent, the graph turns those documents into a denominator.

Keeping the versioned specification as the single source of truth is Spec-Driven Development, the practice GitHub Spec Kit named and AWS built Kiro around. SDD uses the specification as an input and does not count whether it was implemented. That is the gap this fills, which is why adopting it costs a configuration block rather than a workflow.

Start with one claim

{
  type: "typescript",
  files: ["src/components/**/*.tsx"],
  symbol: "function",
  reference: {
    type: "markdown",
    files: ["docs/requirements/**/*.md"],
    symbol: ["h2", "h3"],
  },
}

Read as one sentence: the components under src claim to implement the requirements, so every H2 and H3 under docs/requirements must be cited by a component.

Turn on that single block, and the moment someone adds a section the build says nobody has built it yet.

Chain the documents to each other

Code citing documents is the obvious direction. Documents citing documents is the one that changes how planning works.

A document hierarchy usually flows the same way: a decision comes out of a meeting, becomes a clause in the requirements, becomes a screen flow in the feature specification, and becomes code and tests. Wire each step to cite the one before it and the whole chain is compiler-checked.

// 1. Requirements reflect what the meetings decided.
{
  type: "markdown",
  files: ["docs/requirements/**/*.md"],
  reference: {
    type: "markdown",
    files: ["docs/meetings/**/*.md"],
    symbol: ["h2", "h3"],
  },
},
// 2. Feature specifications are built on the requirements.
{
  type: "markdown",
  files: ["docs/features/**/*.md"],
  reference: {
    type: "markdown",
    files: ["docs/requirements/**/*.md"],
    symbol: ["h2", "h3"],
  },
}

Citations are HTML comments, so the rendered document is unchanged for whoever reads it:

docs/features/checkout.md
# Checkout Feature Specification
 
## Coupon Application Flow
 
<!-- @evidence docs/requirements/pricing.md#coupon-stacking This section turns the coupon stacking rule into a screen flow. -->

Three failures become build failures: a decision made in a meeting that never reached the requirements, a requirement clause no feature specification covers, and a feature flow no screen implements.

The reverse direction closes too. Delete a requirement clause and every feature specification that leaned on it breaks immediately, so a ghost specification with no basis cannot survive in the tree. A gap discovered while writing code becomes a citation that demands the document be written.

One thing changes for the person writing the specification. You stop asking whether what you wrote was reflected. The build answers.

Put the upstream in too

Anything with headings can be an evidence source. Meeting notes are the common one, and they are not the only one: idea notes, user research and interview records, competitor analysis, data analysis results, support tickets and customer feedback.

Idea notes are the most useful of these, precisely because most ideas never become products. An adopted idea leaves a citation naming the requirement it became, a rejected idea leaves an exclusion naming why and what would make the team revisit it, and an idea nobody judged blocks the build.

<!-- @evidenceExclude docs/ideas/2026-q1.md#social-login
     Deferred out of this release; the identity provider contract is unsigned. Reject this exclusion once legal confirms the contract. -->

Where an idea note used to be quietly forgotten, the history of what was taken and what was declined stays in the repository.

Consume an external API specification

If another team hands you an OpenAPI document to implement or to consume, cite it directly:

{
  type: "typescript",
  files: ["src/controllers/**/*.ts"],
  reference: {
    type: "swagger",
    file: "https://api.partner.com/openapi.json",
  },
}

Every operation under paths becomes a unit. When the other team adds an operation, your next build reports that you have not implemented it yet.

A remote document is fetched once per process, so a running watch session keeps the document it started with, while a one-shot ttsc check in CI always fetches. Pin the document locally when you need the boundary to be reviewable in a diff.

Roll it out on an existing codebase

Do not enable everything at once. Staged enabling is the adoption strategy.

  1. Declare the whole graph, with every claim disabled: true. The shape is validated, nothing is enforced, and the target picture is in the repository where the team can argue about it.
  2. Pick the boundary that hurts most. Usually requirements to screens, or API to tests.
  3. Enable that one claim and settle the flood. Build what was never built. For everything the team decides not to build, write the reason into the exclusion ledger.
  4. Go green, then enable the next claim.
{
  name: "screens",
  type: "typescript",
  files: ["src/components/**/*.tsx"],
  symbol: "function",
  reference: {
    type: "markdown",
    files: ["docs/requirements/**/*.md"],
    symbol: ["h2", "h3"],
  },
  // Remove once every required screen and its evidence mapping is complete.
  disabled: true,
}

Step 3 is where the value shows up before any enforcement does. What accumulates in the exclusion ledger is the debt list the team had never written down.

Declare evidenceExcludeCarriers from the start, so that ledger is one file rather than a grep. Reviewing it is the one review that cannot be skipped: an exclusion is the only acknowledgement that reports an obligation discharged with nothing built.

What it costs

Clearing an obligation is work an agent has to do, so the honest question is what that does to a run. The benchmark measured both arms on four subjects of ascending size.

Loading the measurement.

On the three smaller subjects the arm with the graph finished on between a quarter and a half of the tokens. On the largest it spent about 9% more. Four subjects and one engine do not establish where the crossover sits, so treat the saving as measured on these four rather than as one you can assume.

The full benchmark has the phase split, the reconciled prices, and the raw counters.

What review looks like afterwards

The tags are written by the agent as it implements. What reaches a human changes shape.

  • Read the reasons, not the diff. Each citation sits beside the section it claims to honor, so a misreading is visible without reconstructing the change.
  • Read the exclusion ledger in full. Every entry is a decision to build nothing. “Not applicable” is a conclusion; send it back for the owner, the alternative, and the condition that reverses it.
  • Stop checking for omissions. That is the one thing the build now does better than a reviewer, because it counts.

evidence/todo is the companion habit. Keep it "off" while stubs are the plan of record, then turn it to "error" when the work is meant to be finished, and every remaining stub names itself.

Last updated on
Full-Stack WiringOverview