Behavior over history: document what the product DOES, not what changed. A bug fix
updates the affected section to describe correct behavior; it never appends a "Fixed:"
entry (worked examples in reference.md, "Bug Fix Documentation").
Conciseness over completeness: a focused doc that gets read beats an exhaustive
doc that gets skipped.
Plain words over clever words: everyday English, short sentences, one idea per
sentence. Write for a fresh graduate whose first language may not be English — a
doc that needs a dictionary fails even when it is true (R9's plain-English/empathy
test; applies to godocs and feature docs alike).
Comments stand alone: a reader must understand the comment BEFORE reading the
code. If reading the code is required to understand the comment, the comment adds
negative value — no decoder-ring IDs, no forward references to other comments
(R9's empathy test, second half).
Artifacts:
- /.md (created/updated)
- godoc: <symbols touched, grouped by package>
- testable examples: <Example_* functions>
- index.md: <line added/refreshed>
Network edges added:
- code→docs: → /.md
- docs→code: → <symbols/packages cited>
- root: @/index.md in CLAUDE.md (verified/added)
R9 self-check: Q1–Q3, Q7 clean · Q4–Q6 clean over diff
(or per hit: : — fixed by )
Comment critic: reviewed — deleted · trimmed · rewritten ·
clean on re-critique (or: <remaining verdicts, reported as-is>)
R3 leads (in-body extraction candidates, for the caller): <file:line, ...> (omit when none)
Expand recommendations (optional — omit the section when none):
- — consider expanding its godoc inline beyond the doc reference:
BOOTSTRAP mode:
BOOTSTRAP COMPLETE
Doc root(s): <discovered/created; per sub-project if monorepo>
Index: /index.md built — docs, groups; map of maps: <yes/no>
Frontmatter: verified, added
Root wiring: CLAUDE.md @import <added/verified> · AGENTS.md routing block <added/verified>
Conventions: /conventions.md <created/verified>
Check script: scripts/check-repo-brain.sh <installed/verified> — suggest CI: bash scripts/check-repo-brain.sh
Upward edges: wired — ← (), ...
Advisory findings (reported, not fixed — FEATURE mode writes content):
- unwired: — indexed, but no confident front-door anchor; needs a human call
- broken edge: → (unresolved)
- gap: — <dangling code→docs edge | entry points with no citing doc>
- stale: — indexed with ⚠️ flag; cites unresolved ; not edge-wired
- type?: — class not inferable; needs a human call
- diverged script: scripts/check-repo-brain.sh differs from the plugin's — not overwritten
</output_format>
<success_criteria>
- Every fact sits at its lowest viable rung of the documentation ladder; nothing
duplicated across rungs (R9 placement rule).
- New/updated docs joined the network: indexed, root-wired, edges in both directions.
- FEATURE: the R9 self-check ran and every hit was fixed before reporting.
- FEATURE: the comment-critic ran over the full diff, every non-KEEP verdict was
applied (R3 routes reported, not fixed), and the one re-critique confirmed clean
— or the remainder is reported as-is.
- BOOTSTRAP: root(s) + index + root wiring + conventions.md + check
script exist; frontmatter verified-or-added on every content doc; every
confidently-anchorable doc has an upward edge; gaps reported; zero content docs
generated (conventions.md and the copied script are the two sanctioned
artifacts).
- All prose passes the 5-year reader test; zero changelog-style entries.
</success_criteria>
<constraints>
This skill MUST NOT:
- Restate R9 content — the documentation ladder, invariants, and policies are cited,
never copied.
- Append change history to docs — current behavior only, always.
- Mass-generate content docs in BOOTSTRAP mode — advisory gap report only
(conventions.md and the copied check script are the two sanctioned artifacts).
- Fill templates for their own sake — reference.md's templates are menus; R9's
comment policy decides what earns its place.
- Spawn anything other than `comment-critic`, loop the critique more than one
fix-and-recheck round, or fix `DELETE → route R3` verdicts itself (extraction
belongs to @refactoring).
</constraints>
1---2name: documentation3description: The repo-brain author/maintainer: writes behavior-focused documentation and wires it into the documentation network defined by rules/R9-repo-brain.md. FEATURE mode (default): after feature implementation or bug fixes — invoked by @linter-driven-development (Phase 5) — to document HOW THE PRODUCT BEHAVES and wire it into the network. BOOTSTRAP mode: on request ("set up docs", "create an index", "make this repo AI-navigable", /wire-repo-brain) or when FEATURE mode finds no doc root — discovers the doc root, verifies-or-adds OKF frontmatter, builds index.md, wires CLAUDE.md/AGENTS.md, wires missing code→docs edges, installs conventions.md and the conformance check script, reports gaps. NOT a changelog - documents current behavior, not change history.4---56<objective>7Author and maintain the repo brain: a documentation network where any entry point — a8grep hit on a symbol, a file open, CLAUDE.md at session start — reaches full context9within two hops. Everything normative (the documentation ladder, both network10invariants, the comment policy, the edge policy, the index policy, the OKF11frontmatter/bundle policy, root wiring, doc-root discovery) lives ONCE in12`../../rules/R9-repo-brain.md`; this skill is the13actor that applies it. Templates live in `reference.md` — they are menus, never forms.14</objective>1516<philosophy>17**The 5-Year Reader Test**: someone reading this in 5 years doesn't care that "we18fixed a bug where X happened" — they want to know how X works NOW. This holds for19comments as much as docs: a PR number, review item, or "the previous behavior"20narration in a godoc is provenance, not behavior (R9's floor names it a failure21mode).2223**Behavior over history**: document what the product DOES, not what changed. A bug fix24updates the affected section to describe correct behavior; it never appends a "Fixed:"25entry (worked examples in reference.md, "Bug Fix Documentation").2627**Conciseness over completeness**: a focused doc that gets read beats an exhaustive28doc that gets skipped.2930**Plain words over clever words**: everyday English, short sentences, one idea per31sentence. Write for a fresh graduate whose first language may not be English — a32doc that needs a dictionary fails even when it is true (R9's plain-English/empathy33test; applies to godocs and feature docs alike).3435**Comments stand alone**: a reader must understand the comment BEFORE reading the36code. If reading the code is required to understand the comment, the comment adds37negative value — no decoder-ring IDs, no forward references to other comments38(R9's empathy test, second half).39</philosophy>4041<mode_selection>42**FEATURE** is the default: run it after a feature or bug fix lands (ldd Phase 5).43Switch to **BOOTSTRAP** when the user asks to wire a repo ("set up docs", "create an44index", "make this repo AI-navigable") or when FEATURE step 1 finds no doc root.45Skip entirely for individual commits and internal refactors that change no behavior —46unless an R9 Q6 check shows a doc citing the reshaped code.47</mode_selection>4849<feature_mode>501. **Scope**: establish what shipped — the feature's commits/diff, which packages and51 entry points it touches.522. **Place each fact on the documentation ladder**: apply R9's rung table and53 placement rule (`../../rules/R9-repo-brain.md`, Design guidance). Before writing54 any comment, first check whether a rename or extraction makes it unnecessary.553. **Rung 1 — godoc**: write/refresh doc comments per R9's comment policy —56 **exported symbols only by default**: an unexported symbol gets NO comment57 (R9's visibility default) unless one line carries a very high-value toolbox58 item the code cannot show; never more than that one line. Every comment59 must pass R9's three-test standard BEFORE it is written (toolbox-value,60 tier budget, plain English), with content picked FROM the Comment Value Toolbox61 (catalog in reference.md) for the symbol's tier: 1–5 prose lines, helper /62 contract / crossroads; overflow moves to the feature doc. Keep the63 `See docs/<feature>.md` edge wherever a feature doc exists. A package that64 earns more moves its godoc to `doc.go` (R9's ~20–30 line bound). A crossroads65 that deserves richer inline godoc stays within budget and gets an expand66 recommendation in the report — never extra lines. Add testable examples67 (`Example_*`) for complex/core types.684. **Rung 2 — feature doc**: create/update `<docroot>/<feature>.md` from the69 reference.md template, with OKF frontmatter (required keys — R9's bundle70 policy); lateral doc links inline, each in a sentence stating the71 relationship (R9 edge policy — no `Related` section);72 key players as `Symbol | Role | Package`; entry points cite symbols — never73 file paths or line numbers (R9 edge policy). Bug fix → update the existing74 doc's affected section; do not create a new doc.755. **Rung 3 — the map**: add/refresh the doc's one line in `index.md` — copied76 from the doc's `description` (R9 drift-check rule); verify root wiring77 (`@<docroot>/index.md` import in CLAUDE.md, AGENTS.md routing block).786. **Self-check**: run R9's falsifying-question detections on the touched scope —79 Q1–Q3 and Q7 mechanically (orphans, broken edges in both directions, unwired80 root, bundle contract — the repo's `scripts/check-repo-brain.sh` runs all four81 in one pass when installed), Q4–Q6 over the diff (WHAT-comments, naked exported82 API, silently-changed doc). The detection commands live in R9; never restate83 them. Fix every hit before reporting.847. **Comment critique**: spawn the `comment-critic` agent (Agent tool) on the full diff —85 not just the comments this run wrote; in-body comments left by earlier phases86 are in scope too. Its spawn prompt MUST contain: (a) R9's comment-policy87 section pasted verbatim (toolbox kinds, three-test standard, tiers, budget88 accounting, visibility default); (b) reference.md's Comment Value Toolbox89 catalog pasted verbatim; (c) the absolute path to90 `../../examples/private-comment-noise.md`; (d) the diff scope. Apply every non-KEEP verdict (this skill is the rung-191 fixer): DELETE and TRIM as returned; REWRITE using the critic's proposal;92 `DELETE → route R3` verdicts are deleted here and reported as R3 leads for the93 caller — never fixed here (extraction is @refactoring's move). Then re-spawn94 the critic ONCE to confirm clean; a still-dirty re-critique is reported as-is,95 never looped further.968. **Report** in the FEATURE output format below.97</feature_mode>9899<bootstrap_mode>1001. **Discover doc root(s)** per R9's discovery order (`.ai/` → `.ainav/` → `docs/`;101 create `docs/` if none exists). Monorepo → one doc root + index per sub-project.1022. **Inventory existing docs**, classify each (feature / architecture / guide /103 stale — classification table in reference.md), and **verify-or-add frontmatter**104 (migration guidance in reference.md): a doc already conformant is left alone; an105 un-inferable `type` goes to the advisory report, never guessed.1063. **Build or rebuild `index.md`**: bare except the root's `okf_version`, grouped107 by topic, one line per doc — each line copied from the doc's `description`108 (R9 drift-check rule); past ~300 lines it becomes a directory-shaped map of109 maps, and the split lands in the same commit as the `See docs/...` path110 rewrite (R9 index policy; templates in reference.md).1114. **Wire the root**: author the routing block once, in AGENTS.md — repo root112 and, in a monorepo, nested per sub-project — then wire CLAUDE.md with the113 `@AGENTS.md` embed plus the `@<docroot>/index.md` import (create a minimal114 CLAUDE.md section if none exists; never restate the routing prose there).115 Add or verify; snippets in reference.md.1165. **Teach and enforce**: create-or-verify `<docroot>/conventions.md` (template in117 reference.md) — the ONE content file bootstrap generates (network118 infrastructure, not a content doc) — listed FIRST in the index; copy the119 plugin's `scripts/check-repo-brain.sh` into the target repo's `scripts/`120 (verify-or-copy — a diverged copy is reported, never overwritten). The report121 suggests CI wiring as plain `bash scripts/check-repo-brain.sh`; never add a122 workflow file.1236. **Wire missing upward edges**: for each indexed (non-stale) doc with no code-side124 edge, add ONE line — `// See <docroot>/<file>.md ...` — to the front-door anchor's125 existing doc comment (anchor heuristic in reference.md), then confirm the package126 still vets. Go files only — the gate verifies edges in `.go` files alone, so an127 edge in another language is unverifiable; report such docs as unwired instead of128 improvising. Wiring only: never rewrite the comment around it, never wire a stale129 doc (its ⚠️ index flag is the finding), and skip — as a reported gap — any doc130 whose anchor you cannot identify with confidence.1317. **Confirm and report**: re-run R9 Q1–Q3 and Q7 as confirmation — via the132 installed script — a Q1 hit (a doc with no index line) means step 3 didn't land,133 a Q3 hit means step 4 didn't, a Q7 hit means step 2 or 5 didn't; repair any134 before reporting, and verify every edge added in step 6 resolves. The ADVISORY135 findings list carries Q2 hits plus rung-2 gaps (two-signal criterion in136 reference.md), any doc left unwired in step 6, and any `type` needing a human137 call. Bootstrap wires and maps; it NEVER mass-generates content docs — those are138 written incrementally by FEATURE mode.139</bootstrap_mode>140141<output_format>142FEATURE mode:143```144DOCUMENTATION COMPLETE — FEATURE mode145Feature: <name>146147Artifacts:148- <docroot>/<feature>.md (created/updated)149- godoc: <symbols touched, grouped by package>150- testable examples: <Example_* functions>151- index.md: <line added/refreshed>152153Network edges added:154- code→docs: <symbol> → <docroot>/<feature>.md155- docs→code: <doc> → <symbols/packages cited>156- root: @<docroot>/index.md in CLAUDE.md (verified/added)157158R9 self-check: Q1–Q3, Q7 clean · Q4–Q6 clean over diff159 (or per hit: <Qn>: <evidence> — fixed by <R9 fix-pattern move>)160161Comment critic: <N> reviewed — <D> deleted · <T> trimmed · <R> rewritten ·162 clean on re-critique (or: <remaining verdicts, reported as-is>)163 R3 leads (in-body extraction candidates, for the caller): <file:line, ...> (omit when none)164165Expand recommendations (optional — omit the section when none):166- <Symbol> — consider expanding its godoc inline beyond the doc reference:167 <one-line rationale>168```169170BOOTSTRAP mode:171```172BOOTSTRAP COMPLETE173Doc root(s): <discovered/created; per sub-project if monorepo>174Index: <docroot>/index.md built — <N> docs, <M> groups; map of maps: <yes/no>175Frontmatter: <N> verified, <M> added176Root wiring: CLAUDE.md @import <added/verified> · AGENTS.md routing block <added/verified>177Conventions: <docroot>/conventions.md <created/verified>178Check script: scripts/check-repo-brain.sh <installed/verified> — suggest CI: bash scripts/check-repo-brain.sh179Upward edges: <K> wired — <doc> ← <anchor symbol> (<package>), ...180181Advisory findings (reported, not fixed — FEATURE mode writes content):182- unwired: <doc> — indexed, but no confident front-door anchor; needs a human call183- broken edge: <source> → <target> (unresolved)184- gap: <package> — <dangling code→docs edge | entry points with no citing doc>185- stale: <doc> — indexed with ⚠️ flag; cites unresolved <symbol>; not edge-wired186- type?: <doc> — class not inferable; needs a human call187- diverged script: scripts/check-repo-brain.sh differs from the plugin's — not overwritten188```189</output_format>190191<success_criteria>192- Every fact sits at its lowest viable rung of the documentation ladder; nothing193 duplicated across rungs (R9 placement rule).194- New/updated docs joined the network: indexed, root-wired, edges in both directions.195- FEATURE: the R9 self-check ran and every hit was fixed before reporting.196- FEATURE: the comment-critic ran over the full diff, every non-KEEP verdict was197 applied (R3 routes reported, not fixed), and the one re-critique confirmed clean198 — or the remainder is reported as-is.199- BOOTSTRAP: root(s) + index + root wiring + conventions.md + check200 script exist; frontmatter verified-or-added on every content doc; every201 confidently-anchorable doc has an upward edge; gaps reported; zero content docs202 generated (conventions.md and the copied script are the two sanctioned203 artifacts).204- All prose passes the 5-year reader test; zero changelog-style entries.205</success_criteria>206207<constraints>208This skill MUST NOT:209- Restate R9 content — the documentation ladder, invariants, and policies are cited,210 never copied.211- Append change history to docs — current behavior only, always.212- Mass-generate content docs in BOOTSTRAP mode — advisory gap report only213 (conventions.md and the copied check script are the two sanctioned artifacts).214- Fill templates for their own sake — reference.md's templates are menus; R9's215 comment policy decides what earns its place.216- Spawn anything other than `comment-critic`, loop the critique more than one217 fix-and-recheck round, or fix `DELETE → route R3` verdicts itself (extraction218 belongs to @refactoring).219</constraints>
buzzdan