Bootstrapping Docs

Bootstrapping Docs

Overview

Goal: the smallest doc set that makes the next work session productive — not comprehensive documentation. A bootstrapped repo gets just enough that a new agent or teammate stops rediscovering the same facts every session. Everything else is deferred.

Capable agents already find the build commands, gotchas, and architecture. The failure this skill prevents is completeness-chasing: cataloguing every API route, helper signature, convention, and directory into docs that are inferable from code and will drift.

REQUIRED SUB-SKILL: Use writing-docs for the quality of every doc you write here (run-or-omit example output, marked+anchored rationale, no aspirational claims). This skill governs what to create and when to stop; writing-docs governs how each doc reads.

Process: explore, then write the minimum

1. Explore the repo: read the build/test orchestration (Makefile, package.json scripts, CI config), the entry points, and the env/config surface. Run the key commands if you can.
2. Write the priority set below, in order, applying writing-docs to each as you go (run-or-omit output, marked+anchored rationale, no aspirational claims). Stop when the high-leverage facts are captured.
3. Write docs/doc-scope.md (format owned by growing-docs) listing what you deliberately did NOT document, each with the demand signal that would promote it.

Priority order (create in this order; stop early if that's enough)

1. CLAUDE.md / AGENTS.md — first, always. Highest leverage for agent performance. It holds only what an agent can't cheaply infer (see checklist). Agent rendering — max signal-per-token, pointers over inline copies; the writing-docs skill carries this bar (dispatch the llm-doc-writer agent for a whole-doc job). Calibration: a bootstrap agent file that lands much past ~40 lines has almost always stopped cutting. The aggregate budget binds even when every individual line is true, verified, and anchored — each line here is re-read at the start of every future session, so overflow content doesn't get cheaper by being good. When good material overflows, move it to a referenced doc or defer it in the scope record; keep the pointer.
2. README skeleton — human front door: one-line what-and-why, setup, the run/test commands. A skeleton, not a manual (~30–40 lines): the front door is for orientation, and a section that outgrows it is reference material — link it, or defer it in the scope record.
3. Operational stubs — only if real operational knowledge surfaced during exploration; otherwise defer it in the scope record (- runbook: … — promote when: <signal>) and move on.

Larger repo (many independently-comprehensible units)? See repo-shape.md — it scales this same minimal-high-leverage rule per unit.

The high-leverage checklist (what the agent file MUST capture)

Only things an agent burns tokens rediscovering:

• Commands it can't guess — build, test, run, lint — especially where they differ from defaults (e.g. make test, not npm test).
• Ordering & setup gotchas — steps that must happen first (migrations, codegen), and the symptom if skipped.
• Required env / config — what must be set, and what breaks without it.
• Architecture as pointers — the major components and where they live (services/api, packages/shared), NOT descriptions of them.
• Runtime version / toolchain — if non-obvious.

STOP — do not document these (the completeness traps)

These are inferable from the repo and will drift. Cutting them is the whole point.

• ❌ API route catalogs (endpoints, status codes, request-field tables) — readable in the handler.
• ❌ Function/helper signatures — readable in the source.
• ❌ Convention lists a formatter/linter already enforces (quotes, semicolons, indentation).
• ❌ Directory trees that just mirror ls.
• ❌ Invented sections: contributing guides, changelogs, badges, API references nobody asked for.

Test each line: would an agent make a mistake without it? If the agent could get it by reading one obvious file, leave it for them to read — link, don't transcribe.

End the bootstrap with a scope record

When you finish bootstrapping, write docs/doc-scope.md — format owned by growing-docs; follow it — so scope is a decision that survives the session, not a chat-only note. List what you intentionally left undocumented, each item with the demand signal that would promote it. Deferral is deferred until a signal, not permanent; when a signal fires, growing-docs owns the promotion.

The record is a file, read on demand — don't keep a standing ## Not yet documented section in an always-loaded agent file (CLAUDE.md/AGENTS.md), where it becomes maintained residue re-read every session. A pointer line to docs/doc-scope.md is fine.

Then write the registry, so the docs you just created are classified rather than merely present:

ENGINE="$CLAUDE_PLUGIN_ROOT/engine/doc-lifecycle.py"
mkdir -p .doc-lifecycle
python3 "$ENGINE" migration-draft --repo . --registry-only > .doc-lifecycle/registry.json
python3 "$ENGINE" migration-dry-run --repo .

Review the globs in the first file; the dry run exits 1 and names any document under a declared root that no rule claims. The full sequence, including what a blocked dry run means, is scheduling-doc-sync's "Migration to the registry contract" — one owner, and it is the same door an existing install uses.

Red flags — STOP

• Writing a table of API routes / status codes → cut; link to the handler.
• Listing every helper's signature → cut; link to the module.
• A directory tree mirroring the filesystem → cut.
• Adding contributing/changelog/badges nobody asked for → cut.
• Aiming for "comprehensive" or "complete" → wrong target; aim for minimal-high-leverage.
• The agent file or README sliding past ~40 lines of individually-good content → the aggregate budget binds too; the overflow is exactly what referenced docs and docs/doc-scope.md deferrals are for.
• Finishing the bootstrap with no scope record (docs/doc-scope.md) → you haven't decided scope, you've just stopped — and the decision dies with the session. (A bootstrap-time check — don't lint established docs for a standing section.)