Documentation agent guide

Documentation orients; executable code owns implementation truth. Write the smallest page that lets a reader answer:

1. What good looks like.
2. Where the canonical implementation lives.
3. Why it has this shape.
4. How responsibility and data cross important boundaries.
5. What executable evidence tests the claim.

Improve the smallest missing layer: intent, visual shape, canonical code link, local code comment, proof link, or durable decision. Do not compensate for a missing implementation or test with more prose.

Keep five things

• Intent: State the protected outcome or invariant in one sentence.
• Shape: Show one compact diagram only when flow, ownership, or dependency direction is otherwise hard to understand.
• Implementation: Name one best current executable example and the shortest useful reading order across its roles.
• Proof: Link the nearest relevant test, contract, integration check, or deterministic control. A link is evidence location, not proof it passed.
• Decisions: Retain only durable constraints, trade-offs, ownership, and explicitly unresolved questions.

A pattern page should normally fit on one screen. Long form needs a reason such as an irreversible decision, external contract, operational runbook, safety or compliance obligation, or onboarding need that code cannot carry.

Put truth in its strongest owner

Prefer, in order:

1. an executable constraint such as a type, test, lint rule, dependency rule, or CI gate;
2. a generator, template, or safe default;
3. one canonical implementation with local comments and proof;
4. concise orientation and durable decisions; then
5. human convention only when stronger controls are not viable.

Improve code comments only where responsibility or an adjacent boundary is not obvious. Explain why the file exists, what it owns, the constraint it protects, and the next canonical code or proof. Do not narrate syntax or repeat types.

Review seven gates

• GATE — Orient. One sentence states the intent and protected outcome.
• GATE — Show shape. A compact visual clarifies a non-trivial flow or is deliberately omitted because prose is clearer.
• GATE — Name one implementation. Current repository-relative paths and reading order identify the canonical example without an IDE-local dependency.
• GATE — Link proof. The page names executable evidence appropriate to the claim and does not imply it passed without a current receipt.
• GATE — Preserve ownership. Code, docs, decisions, and open questions have distinct owners; prose does not restate implementation logic.
• GATE — Prefer enforcement. A durable invariant uses the strongest practical executable or generated control.
• GATE — Minimise. Every remaining paragraph changes orientation, judgment, action, proof, or maintenance.

Stop publication on a failed, skipped, blank, stale, or unproved applicable gate. Correct the earliest rightful code, test, tool, decision, or documentation owner. Reopen the page when its canonical implementation or proof changes.