Growing Docs

Growing Docs

Overview

A demand signal — not a sense of completeness — is what earns a new doc. bootstrapping-docs creates the smallest high-leverage doc set and deliberately stops; this skill is the other half of that bargain. When reality asks for more — the same fact re-derived, an incident with no runbook — the doc set grows by exactly the artifact that absorbs the signal, and no further.

Route first: gap or drift?

Drift tooling audits claims that exist; a pure gap has nothing to flag. Do not wait for a drift report to legitimize growth — it never will.

The second-rediscovery rule

The first time a fact is asked for or derived the hard way, answering is fine — but the exemption costs one logged line: add - seen: <date> <one-line occurrence> under the matching ## Deferred item in docs/doc-scope.md (create the item if absent). The second rediscovery is usually a different session or a different person — without the log, nobody can recognize a second occurrence as the second, and this rule never fires. The second time, it has earned a doc — write it where the reader would have looked first (the doc they opened, the section they scanned, the file they read). This is the positive twin of writing-docs Rule 5: "cheaply inferable" is an empirical claim, and a second hard derivation falsifies it.

Name the signal before writing ("second teammate this week hit exit 3", "third session re-deriving the migrate order"). If you cannot name one, you are completeness-chasing — stop.

Signal → smallest artifact

One signal → one smallest artifact. bootstrapping-docs' STOP list (route catalogs, signature lists, directory trees) still binds — a demand signal is not a license to catalogue.

The scope record: docs/doc-scope.md (this skill owns the format)

• On entry: if docs/doc-scope.md exists, read it alongside the live signal — the item may already carry a promotion condition that just fired. A Deferred item already carrying a seen: line means the live signal is the second rediscovery: promote it.
• On exit: update it — create it if absent. Log what you wrote in Done with the signal that fired (moving the item from Deferred if it was listed there); add any new deliberate deferrals, each with a promote when: signal; log any first occurrence you exempted as a seen: line (the second-rediscovery rule above).

# Doc scope record
<!-- format: doc-lifecycle growing-docs -->

## Deferred
- <artifact>: <what> — promote when: <signal>
  - seen: <date> <one-line occurrence>   <!-- first-rediscovery tally -->

## Done
- <date> <artifact> ← <signal that fired>

Read on demand; never a standing section in an always-loaded agent file (CLAUDE.md/AGENTS.md) — a pointer line is fine.

Quality routing

• Repo-tracking doc (README, runbook, CLAUDE.md/AGENTS.md, reference) → writing-docs, the one door — exactly as bootstrapping-docs routes.
• Narrative doc (walkthrough, tutorial, ADR) → writing-docs scopes these out by design; the template below is carried here and is REQUIRED.

Where narrative docs live

A narrative doc is a durable doc — it tracks the current repo, and must never be mistaken for a retire-on-landing planning artifact. Its home:

• Repo with a docs/reference/ tree: inside it, domain-grouped like everything else (a unit's walkthrough beside its overview.md; cross-unit narrative beside architecture.md). One containment subtree holds the whole agent doc set, claim-style and narrative alike.
• Repo without one: under docs/ beside the team's docs; it moves into docs/reference/ if that tree later exists.
• Never in docs/plans/ — that is where planning artifacts go to be distilled once their implementation lands; a narrative doc placed there will read as one.

Narrative doc template (REQUIRED)

1. First line under the title, always: > As of <YYYY-MM-DD> (<commit or file:line anchors current at writing>) — the staleness anchor readers can check against, and drift-audit checks it too: the engine parses this line deterministically and emits ANCHOR-MISSING, ANCHOR-MALFORMED, ANCHOR-STALE, ANCHOR-FUTURE-DATED, or ANCHOR-UNRESOLVABLE-REFERENCE findings against it. This line is also the doc's durable-narrative marker: bloat tooling classifies an anchored doc as narrative — never as a planning artifact to distill — wherever it sits. Every backticked path anchor is repository-relative and written in full, each one, including siblings of the one before it: an abbreviation is indistinguishable from a target that has moved, so the audit refuses it rather than guess which same-named file was meant.
2. Every command, path, symbol, and output inside the narrative is true of the repo now and was actually run. Narrative structure is exempt from the claim bar; fabrication is not.
3. Still the smallest doc that absorbs the signal.
4. Rationale gets one owner. If the "why" you are landing already lives as a code comment, trim that comment to a pointer at the new doc in the same change — duplicated rationale drifts apart; the pointer keeps the breadcrumb where the reader trips on it.

Rationalizations

Red flags — STOP

• Answering the same question a second time and moving on → it has earned a doc; write it.
• Answering a first-time question and moving on without a seen: line in docs/doc-scope.md → the second rediscovery becomes unrecognizable across sessions; the exemption costs the log line.
• Growing docs with no nameable signal (a milestone, a release, "while I'm here") → wrong trigger; demand grows docs, calendars don't.
• One signal producing a catalogue (routes, signatures, trees) → one smallest artifact; bootstrapping-docs' STOP list still binds.
• A walkthrough/tutorial/ADR without the > As of … first line → the anchor is REQUIRED.
• Finishing without updating docs/doc-scope.md (creating it if absent) → the scope decision evaporates with the session.
• Pasting doc-scope.md contents into CLAUDE.md/AGENTS.md → read on demand; a pointer line at most.