Insights10 April 2026Updated 26 October 20264 min read

The Repo Matrix: A Living Document for Agent Grounding

A grid of glowing blue and purple nodes connected by lines, representing Agent Grounding in Dendro Logic.

An agent's proposed endpoint should be checked against a contract, not accepted because its name sounds right. OpenAPI defines a structured description of HTTP APIs, including paths and operations that people and tools can inspect. We recommend making that kind of evidence the starting point for repository work, rather than asking an agent to reconstruct the system from a feature request.

We use the term repo matrix for a proposed index of repository facts, with links back to the evidence behind each entry. The design recommendation is to extract what can be observed mechanically, keep interpretation separate and require the agent to inspect the relevant contract before suggesting a change. This is a grounding method to evaluate, not a promise that a scanner eliminates hallucinations or proves an implementation correct.

Start with a contract the agent can inspect

A luminous grid of cells each holding a small shape of light, with an agent node reading one row

For an API inventory, OpenAPI's Path Item and Operation objects provide a useful reference structure for paths, methods, parameters and responses. The specification also provides security requirements at API and operation level. These are descriptions of the contract, not evidence that a running service enforces every declared rule.

Our recommendation is to give each matrix entry a repository identifier, revision, source location and extraction time alongside the technical fields. For an endpoint, include the method and path, then point to the request definition, response definition and relevant authorisation code. Mark fields as unknown when the extraction cannot establish them, instead of filling gaps with an agent's likely answer.

Consider a hypothetical request to add an endpoint for exporting inspection records. We would require the agent to search the existing operations, inspect any apparent match and compare its authorisation and response contract with the requested behaviour. If the existing operation differs, we recommend recording that difference explicitly before deciding whether to extend it or introduce another route.

Separate extracted facts from explanations

For an initial matrix, we recommend a narrow scope that covers the interface the team is actively changing. Use a framework-aware parser or a generated contract where possible, and make unsupported routing patterns visible in the output. Treat text searches as leads for inspection, rather than proof that every match is a reachable endpoint.

We would extend the same evidence discipline to schema declarations, migrations, dependency manifests and configuration references. For dependencies, distinguish a requested version from the resolved version rather than presenting them as interchangeable. For environment variables, record names and references without copying credentials or assuming that a declaration proves a value exists in production.

Keep extracted structure separate from explanations of why the team chose it. The publisher's contents for Software Architecture in Practice, by Bass, Clements and Kazman, identify chapter 22 as documenting architecture. We recommend keeping the matrix in version control while linking design reasoning to separately reviewed decision records.

Make freshness part of the answer

A single grid cell lifted out and glowing, with a small timing ring attached to its corner

We recommend defining who maintains the matrix and when its entries must be checked again. For the matrix, our recommendation is to regenerate the affected entries when relevant code changes and retain the revision used for every scan. Before using an entry to justify a change, compare that revision with the working tree and inspect any changes affecting the contract.

We recommend publishing extraction failures and excluded areas alongside successful results, so an empty answer is not mistaken for complete coverage. A lookup should distinguish an operation absent from the inspected snapshot from an operation the scanner could not classify. We would test that distinction with a deliberately unsupported route and require the lookup to report the gap.

Session capture should contribute proposed explanations and follow-up checks, not silently replace code evidence. If a conversation says that a route was renamed, we recommend finding the resulting change before updating the matrix's statement of what exists. Keep an unimplemented decision labelled as proposed, with its source conversation and review status attached.

Put the lookup inside the work

Anthropic's guidance on effective agents recommends obtaining evidence from the environment during execution, including tool results and code execution, to assess progress. Our recommendation is to turn that principle into an explicit repository workflow rather than relying on an instruction to be careful. Ask the agent to retrieve the relevant matrix entry, open the cited source and state the contract it intends to preserve or change.

For review, we recommend requiring the patch to identify the existing implementation it examined and the tests that exercise the changed behaviour. A matrix lookup should be an input to those checks, never their replacement. For a new operation, include a negative test for an unauthorised caller and a contract test for the expected request and response.

We would evaluate the approach on a fixed set of representative repository tasks before expanding it across a portfolio. Record incorrect endpoint suggestions, missed existing implementations, stale entries and the review effort needed to correct them. Compare those observations with the team's previous workflow instead of claiming an onboarding or delivery improvement from the presence of an index alone.

Our recommended starting point is a versioned API inventory with explicit gaps and a repeatable source-checking step. Add schema and decision context only when a real task shows what information is missing. The acceptance criterion should be that a reviewer can trace a proposed change back to the inspected contract and its tests, not that the agent produced a confident explanation.

Update, October 2026

Our later engineering account of team-context infrastructure describes a mechanical repo matrix alongside session capture and decision history. We recommend reading that broader design and our related failure-mode overview alongside this narrower contract-checking workflow, while validating implementation status and any performance claims separately.

Sources

Want this in your team?

Tell us what you're building and where you want to get to, and we'll think it through with you.

Let's have a chat Follow by RSS →

All insights →