Capstone: The Self-Documenting Repository

The Test for a Self-Documenting Repository

Imagine a brand-new agent session. No prior context. No shared history with the repository. The task: implement a non-trivial feature in a codebase the agent has never seen before.

In a self-documenting repository, this is fine. The agent reads the README in sixty seconds, loads the context file, checks the ADRs before making any architectural decisions, reviews the lessons file for known gotchas, and verifies the interface contracts against the drift tests. Then it works. Zero questions to a human. Zero research sessions. Zero re-discovered mistakes from two months ago.

In most repositories, the agent asks four questions in the first five minutes, violates two architectural constraints that were never written down, and repeats a mistake that a previous agent made and never recorded.

The difference is not agent quality. The difference is the documentation kit.

The five zones of the self-documenting repository each answer a different need a new agent (or human) has on day zero:

ORIENT — the README. What is this, how do I run it, where are the key files, what will bite me. Sixty-second orientation test. Written for the impatient senior engineer and for the agent that reads it before every session.

OPERATE — the context file and runbook. Operating instructions for every session. Step-by-step runbook for the critical operations that cannot be done wrong. The context file is what an agent loads automatically; the runbook is what an on-call human reads at 3am.

RESPECT — ADRs. Decision history. The WHY behind architectural choices that would otherwise look like arbitrary constraints. An agent that reads the ADR for "why SQLite instead of Postgres" will not helpfully refactor the persistence layer to use a hosted database. Without the ADR, it will.

IMPROVE — the lessons file. The mistake → root cause → rule learning loop. The compounding mechanism that makes each agent session smarter than the last. Not a diary — a rulebook that grows with every correction.

TRUST — the schema and drift test. Interface truth. Consumers pinned to a contract that CI enforces. The enforcement mechanism that makes "the docs say X" reliable rather than hopeful.

The Maturity Model

Not every repository needs to be at L4 on day one. The maturity model gives you a roadmap.

L0 (Tribal) is where most codebases start. Knowledge lives in Slack threads, individual memory, and institutional folklore. Onboarding a new human takes days. Onboarding a new agent session is effectively impossible — every session starts from zero.

L1 (Written) is the first meaningful improvement. A README exists. Maybe a wiki page. The doc is often marketing-flavored and stale, but at least it is findable. An agent can learn the repo's purpose but will miss conventions and gotchas.

L2 (Structured) is where deliberate documentation begins. The full stack is present: README with a key-files table, context file with hard rules and conventions, at least one ADR per significant architectural decision, a runbook for the most critical operation. An agent can orient in one session. Humans can follow the runbook without asking the author.

L3 (Maintained) adds enforcement. CI link gates catch broken references. Count integrity tests make incomplete registrations unshippable. Drift tests pin interface contracts. Docs are reviewed like code — the git diff includes the markdown. A wrong doc gets deleted, not archived. At L3, the decay curve is broken. Docs stay reasonably current because the infrastructure enforces it.

L4 (Compounding) is the destination. The learning loop is active: lessons are read at session start, post-mortems produce rules, corrections update the lessons file in the same session. Knowledge compounds instead of resetting. An agent that worked in this repository three months ago left it smarter than it found it. The documentation is not just maintained — it improves with every correction cycle.

The honest advice: L0 to L2 in one focused session. L2 to L3 in one sprint. L3 to L4 over the lifetime of the project. Most teams stall at L2 because L3 requires building the CI infrastructure, which feels like overhead. The overhead pays back on the first incident where a link gate catches a deleted runbook step before on-call reads it.

What This Track Built

This track started with a thesis: in agent-driven development, documentation is not a chore. It is the operating interface between human intent and AI execution. The quality of your docs determines the quality of your agent's output — session after session, permanently.

You have now built the complete documentation stack:

• The “Documentation is King” lesson: Why docs flipped from chore to interface when agents started reading them at session start.
• The “The Documentation Stack” lesson: The seven doc types, seven jobs taxonomy — one doc, one job.
• The “The README is the Front Door” lesson: The README as the sixty-second orientation test. The key-files table pattern.
• The “Agent Context Files” lesson: Agent context files — persistent operating instructions. Context budget economics.
• The “ADRs” lesson: ADRs — writing decisions down before they become folklore.
• The “Runbooks” lesson: Runbooks written for 3am-you or an on-call agent — preconditions, numbered steps, expected output, explicit rollback.
• The “The Learning Loop” lesson: The learning loop — lessons files and post-mortems as the compounding mechanism.
• The “Docs as Contracts” lesson: Docs as contracts — single-source generation and drift tests that pin interfaces.
• The previous lesson: Keeping docs alive — freshness signals, CI gates, deletion discipline.

Each lesson added one zone to the self-documenting repository. This lesson assembles the whole kit.

The Capstone Challenge

The capstone is not a tutorial exercise. It is production work on a real repository.

Pick one of your own repositories — ideally one that an agent session touches regularly. Apply the full documentation kit:

1. Write or audit the README (sixty-second orientation test, key-files table, what-will-bite-you section)
2. Write or audit the context file (commands, hard rules, known gotchas — earn every line)
3. Write at least one ADR for a real architectural decision that was made
4. Write a runbook for the most critical operation that must not go wrong
5. Seed the lessons file with one real mistake, its root cause, and the rule that prevents recurrence
6. Write a drift test that pins one interface or path claim the docs make

The documentation kit for a real repository takes 2-4 hours the first time. The second repository takes 45 minutes, because the patterns are internalized. By the third, it is reflexive — the kit is the first thing you build, before a single line of feature code, because you know it determines the quality of everything that follows.

The Foresight trading bot at Tesseract Intelligence, Mission Control, Claude Code — all of them become dramatically more effective when the documentation kit is in place. An agent that reads the context file for the Foresight bot will not accidentally place test orders against the live API. An agent that reads the ADRs for Mission Control will not helpfully refactor the architecture away from the design that was deliberately chosen.

This is the payoff: documentation as a force multiplier. Not a chore that slows you down. Not a bureaucratic requirement. An investment that compounds with every agent session, every on-call rotation, and every new team member who does not need to be hand-held through an orientation.

Build the kit. Then use it to prove it works.