Skip to content
BoB — Big ol' Brain

Documentation Audit — 2026-05-07

Scope: Reconcile every doc in ./docs, root README.md / CLAUDE.md, and nested READMEs against docs/PROJECT-ORCHESTRATION-HANDBOOK.md (rewritten in 35ee16a) and the current state of the code.

Reference: Part of #144.

Method

Section titled “Method”
  1. Read handbook end-to-end (1126 lines) — treat as source of truth.
  2. Inventory actual code: skills/ (13), commands/ (16), agents/ (4), registry/skills/ (31), registry/commands/ (18), registry/agents/ (17), hooks/ (26), bin/ (5), profiles/ (3), schemas/ (3), Makefile, root claude-*.sh (4).
  3. Read each doc and root file; classify: aligned (matches handbook + code), needs-update (drift, but content still valid), archive (superseded, leave a redirect).
  4. Note specific drifts so chunk 3 can act without re-reading every file.

Classification

Section titled “Classification”

Root files

Section titled “Root files”
File Verdict Drift
README.md needs-update Bad component counts (“12 universal skills, 28 registry / 8 commands / 3 universal agents, 12 registry agents / 12 hooks” — actual: 13/31, 16, 4/17, 26). Mentions cdr reprovision (legacy alias). Missing cdfork, cdg, cds, claude shell wrapper, warp CLI, make check. Doesn’t mention GitHub-Issues hierarchy or the handbook itself as the entry point.
CLAUDE.md needs-update Inaccurate counts (~10 skills, ~8 commands, ~4 agents, ~27 registry skills / ~16 commands / ~16 agents). Priority labels listed as p1/p2/p3/p4 but actual GitHub labels are p1-critical/p2-high/p3-medium/p4-low. Missing claude shell wrapper section. Mentions cdfork/cdfork-pair only — drops warp CLI, bin/dev-up, make check.

./docs/ files

Section titled “./docs/ files”
File Verdict Drift / Notes
PROJECT-ORCHESTRATION-HANDBOOK.md aligned Source of truth. Improvements in chunk 4.
prime-directive.md aligned Matches handbook §1 verbatim. State ownership map correct. No changes.
vision.md aligned Living vision doc; handbook §1 references it. Last updated 2026-04-11; vision content current.
cdfork-guide.md aligned Matches handbook §8. Cross-links to vision and research dir. No drift.
dev-lifecycle.md aligned Matches handbook §5. dev.json schema, adapter table, warp-drive integration table all current.
warp-drive-guide.md aligned Matches handbook §7. Phase table, warp CLI, hook table, config table all current. Cross-links to token-monitoring.md and dev-lifecycle.md.
token-monitoring.md aligned Internal reference for token capture pipeline. Correctly describes state-machine.js, token-snapshot.js, token-report.js, JSONL persistence.
branch-config.md needs-update (small) One reference to /auto-loop (“Same as warp-drive”) in the Consumer Commands table. Auto-loop is being removed; either drop the row or move it under a “(legacy)” note. Otherwise correct.
verification-system.md needs-update (small) Refers to “30 projects” (current projects.json is unknown). Test counts (34 / 75 / 13) drift if state machine grows. Otherwise mechanically correct. Re-verify counts against Makefile.
backup-recovery.md needs-update (small) Mentions cdr (claude disaster recovery) alias as if first-class. Handbook §13.1 lists cdr as (Legacy) sync requirements index. The two purposes have collided — cdr is also the disaster-recovery alias per bob-install.sh. Either pick one, or document both clearly. Recovery procedure itself is correct.
automation-behavior.md needs-update Decision-classification table is accurate but doesn’t mention warp-drive specific behaviors (already added in handbook §7). Consider rolling this file into the handbook as the canonical reference, leaving a redirect — its content is now duplicated by handbook §7.1 and the table in §12.8.
new-machine-setup.md needs-update Step 5 manually creates ~/bin symlinks — handbook §3.1 says bob-install.sh handles aliases (cdprov, cdr, cdfork). The ~/bin symlink dance for cdi/cdb/cdp/cdl/cdg/cds is NOT done by bob-install.sh — verify which script provisions these. Step 8 mentions cdr reprovision (legacy). PATH instruction export PATH="$HOME/bin:$PATH" is sensible but should also mention ~/.claude/bin for warp/dev-up.
project-setup-guide.md needs-update Only mentions cdi / cdl / cdb / cdp. Missing cdprov (manifest provisioning is now the canonical path per handbook §3.4). Section 9 Product Planning Workflow correctly mentions /vision /capability /requirement /warp-drive. Symlink direction explanation correct (project → BOB_SOURCE).
NATURAL-LANGUAGE-GUIDE.md aligned Pure terminology reference. No drift.
how-to-auto-loop.md aligned Already a redirect stub pointing to handbook. Keep.
PM-CHEATSHEET.md aligned Already a redirect stub pointing to handbook. Keep.
PROJECT-MANAGEMENT-REFERENCE.md archive Massive drift. Describes the deprecated REQ-NNNN/SOL-NNNN markdown PM system, auto-loop (not warp-drive), and forbidden directory patterns (.claude/project-management/, .claude/requirements/, .claude/journal/decisions/). Status enums, file layouts, entity glossaries — all superseded by GitHub Issues hierarchy. Handbook explicitly notes “(predates GitHub Issues migration; due for its own audit)” in §17. Action: move to docs/archive/2026-05-pm/ with a redirect stub left in place.
pm-conventions.md archive Same kind as PROJECT-MANAGEMENT-REFERENCE.md — defines the forbidden file/directory patterns as if they were the convention. Action: archive with redirect.
PM-WORKFLOWS.md archive Mermaid diagrams of /spec, /risk assess, /release plan, /change create, /backlog add, /standup, /retrospective workflows. Most of these commands are deprecated registry commands per handbook §12.9. Action: archive with redirect.
iac-audit-2026-02-19.md aligned Historical audit snapshot, dated. Keep as historical reference (does not claim to be current).
automation-workflow.txt archive Pre-BoB brain-dump narrative (“Create requirements for this functionality.” — the user is asking themselves what to build). Predates the framework’s existence in current form. Action: move to docs/archive/.
deploy-skill-prompt.md archive One-shot prompt that was used to generate the deploy-cloudflare registry skill. The skill exists at registry/skills/deploy-cloudflare/. The prompt is no longer load-bearing. Action: move to docs/archive/.

Nested READMEs

Section titled “Nested READMEs”
File Verdict Drift
templates/seed/README.md aligned Documents seed file naming, idempotency, lifecycle states, test users. Matches handbook §5.3 + dev-lifecycle.md. No changes.

Existing archive

Section titled “Existing archive”

docs/archive/2026-02-pm/ already contains old backlog.md, bugs/, product-spec.md, rebob-log.md, releases/, traceability-matrix.md. Use the same date-stamped subdir convention for the new archive: docs/archive/2026-05-pm/.

Summary counts

Section titled “Summary counts”
  • Aligned (no change): 9 docs (handbook, prime-directive, vision, cdfork-guide, dev-lifecycle, warp-drive-guide, token-monitoring, NATURAL-LANGUAGE-GUIDE, iac-audit-2026-02-19, how-to-auto-loop, PM-CHEATSHEET, templates/seed/README)
  • Needs-update: 6 docs (README, CLAUDE, branch-config, verification-system, backup-recovery, automation-behavior, new-machine-setup, project-setup-guide)
  • Archive (with redirect): 5 docs (PROJECT-MANAGEMENT-REFERENCE, pm-conventions, PM-WORKFLOWS, automation-workflow.txt, deploy-skill-prompt)

Cross-cutting fixes

Section titled “Cross-cutting fixes”

These appear in multiple docs and should be normalized when chunk 3 runs:

  1. Priority labels: Use p1-critical / p2-high / p3-medium / p4-low (the actual labels), not the abbreviated p1/p2/p3/p4 form. Handbook §4 has it right; CLAUDE.md needs the fix.
  2. Component counts: README and CLAUDE.md both quote outdated counts. Pull live numbers when updating: 13 universal skills, 16 universal commands, 4 universal agents, 31 registry skills, 18 registry commands, 17 registry agents, 26 hooks.
  3. cdr ambiguity: cdr shows up as both “claude disaster recovery” (backup-recovery.md) and “(legacy) sync requirements index” (handbook §13.1). The bob-install.sh wrapper aliases cdr to scripts/lib/cdr.sh — confirm which it actually is and remove the other usage.
  4. /auto-loop references: Handbook deprecates /auto-loop. Sweep branch-config.md and any other doc that lists it as a current command — mark legacy or remove.

Improvements to fold back into the handbook (chunk 4)

Section titled “Improvements to fold back into the handbook (chunk 4)”

Findings during this audit that warrant edits to the handbook itself:

  1. §3.1 / §13.1 — disambiguate cdr. The handbook lists cdr as legacy in §13.1 but bob-install.sh adds it as an alias and backup-recovery.md treats it as the recovery CLI. Pick one canonical meaning and document.
  2. §3.7 — Makefile target counts. Handbook lists targets but the test-count specifics in verification-system.md (34 schemas / 75 warp-drive / 13 checks) aren’t surfaced. Adding a one-line “current test counts” pointer or a make help example would close the loop.
  3. §13.4 — bin/ count. Handbook lists 5 entrypoints (warp, cdfork, cdfork-pair, dev-up, dev-health). Verified — all 5 exist on disk. No fix needed; just confirming.
  4. §14 — hook count. Handbook lists ~26 hooks across events. Verified — hooks/ has exactly 26. README’s “12” is the gap.
  5. §17 — note the audit. Add this audit doc to See Also so the methodology is discoverable for the next audit cycle.

These get implemented in chunk 4 alongside the link sweep and user-global drift check.