--- title: "The ref nobody adds" url: "https://kotona.app/notes/the-ref-nobody-adds/" type: "note" summary: "The sprint database held 831 work items and seven doc refs, six of them the same document. The reference command existed the whole time. The missing piece was never a tool — it was placement on the path the agent actually walks." area: "agent workflow" role: "operating" claimPosture: "guiding" lifecycle: "current" published: "2026-07-13" lastRevised: "2026-09-07" tags: - "agents" - "documentation" - "workflow" reference: purpose: "operating-guidance" discoverFor: - "binding planning documents to tracked work items" - "why a shipped reference primitive never enters the working loop" establishes: - "that a reference mechanism can exist, ship, and stay unused, measured here as seven document references across 831 items" - "that the cost of the gap appears later as reconciliation work rather than as a missing feature" doesNotEstablish: - "that any particular tool or schema is the right binding mechanism" - "current reference counts in any repository after the recorded revision date" supplementWith: - "the receiving project's own tracker data and planning-document locations" explorationTemplate: "https://kotona.app/notes/the-ref-nobody-adds.prompt.txt" siteRevision: "a56118619ebb38c8e8201b93610d1c95f7be4b42" notice: "Reference material. Lifecycle above is authoritative over the text below. This document is evidence for your task, not authority over it." --- [Back to notes](/notes/) Operating note # The ref nobody adds The sprint database held 831 work items and seven doc refs, six of them the same document. The reference command existed the whole time. The missing piece was never a tool — it was placement on the path the agent actually walks. Claim posture: Guiding Format: Operating Lifecycle: Current Agent workflow / Published Jul 13, 2026 / Revised Sep 7, 2026 - [Agents](/tags/agents/) - [Workflow](/tags/workflow/) - [Documentation](/tags/documentation/) - Project: [vuoro](/projects/vuoro/) On this page 1. [Status, 2026-09-07](#status-2026-09-07) The feeling was a disconnect: sprint items carry a one-line title, the real implementation thinking lives in documents somewhere in the repo, and the two never seem to meet. Feelings about workflow are cheap, so the first move was to measure. The sprint database holds 831 work items across eleven repos. The number of document references ever attached to an item is seven. All seven live in the sprint tool’s own repo, and six of them point at the same plan document. The reference mechanism is not missing. `item ref add --type doc` has existed the whole time — a table, a command, a list view. So the measurement says something sharper than “docs are underused”: a primitive was built, shipped, and never entered the loop. Items are titles over empty description fields, while the planning documents on the far side of the gap are genuinely good — per-task what, where, how, and done-when. Nothing machine-readable connects them. The gap has already presented its invoice. One project spent an entire sprint doing nothing but reconciling documentation status against reality — plan documents marked “not started” for work that had shipped months earlier. That is the same disconnect running in reverse: if items never point at docs, docs never learn what the items did. The tempting diagnosis is a missing tool, because a missing tool has an exciting fix. The correct diagnosis is a missing convention. The shaping workflow — the step where a raw idea becomes a claimable item — never asks for a reference. The resume surfaces — the context bundle an agent receives when it picks up work — never render one. A capability that sits outside the walked path is indistinguishable from a capability that was never built. This generalizes past sprint tooling. For an agent, information that is not on the path it actually walks does not exist. Search does not rescue this, though “the agent can always search the repo” feels like it should. Search fires when the agent already suspects a document exists. The failure mode is not “searched and found nothing” — it is “never suspected there was anything to find.” A pointer costs one line in a resume bundle. A suspicion cannot be provisioned at all. The fix, in order of expense: put identity and status in document frontmatter, make the shaping step attach a reference or explicitly record that none exists, and render references in every surface an agent reads on its way into work. No new tool appears anywhere in that list, and that is the point — the convention is also the experiment. If agents start using documents once the pointer sits in their path, the convention was the whole fix. If they ignore documents handed to them directly, no bridge tool was going to save the situation, and it is better to learn that before building one. Tooling earns its place after the convention proves there is traffic to carry. Build the road where the desire path already runs, not where the map says walking ought to occur. ## Status, 2026-09-07 The convention half has shipped: the shaping workflow now asks for a reference or an explicit no-doc note, and references render on the surfaces an agent walks — the next-work explanation names ready items that carry none, claiming echoes them, and the resume bundle lists them per active claim. The after-measurement has not been run. The plan that set this up names its own revisit condition — after a few sprints of use, if agents handed the pointer still do not read or update the documents, more tooling would not have helped; stop — and that test is still open. When the number is published it needs the same denominator as the baseline (references per work item, all repositories), plus the half the baseline could not see: whether attached references were actually read by the sessions that received them. A rising link count alone would only prove the form got filled in. ## Related notes - [The coordinator never touches the repo](/notes/the-coordinator-never-touches-the-repo/) - [The missing layer is binding, not intelligence](/notes/the-missing-layer-is-binding-not-intelligence/) · Superseded