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.