Documentation Information-Architecture Audit — 2026-06-22

Verdict: BoB’s documentation has no information architecture, contradicts itself, ships outdated content, and the doc-keeper tooling is structurally incapable of detecting any of it. This audit grounds the documentation-overhaul capability.

Method: structural scan (file inventory, link graph, staleness) + three parallel qualitative agents (Diátaxis/overlap, contradictions/staleness, tooling gaps). Counts verified against the live repo on 2026-06-22.

1. Information architecture — absent

• 27 of 45 docs/*.md files sit flat at the top of docs/ with no categorization. Only archive/, audits/, research/ are organized dirs.
• 3 stray root docs beyond the allowed README + CLAUDE: bob-identity.md, plan.md, CHANGELOG.md.
• 6 tombstone/redirect files (“Moved”/“Archived”) clutter the main docs/ namespace: how-to-auto-loop.md, pm-cheatsheet.md, deploy-skill-prompt.md, pm-conventions.md, pm-workflows.md, project-management-reference.md.
• Orphans (reachable from nothing): tmux-cheatsheet.md; plus 2 stale dated audit artifacts (iac-audit-2026-02-19.md, doc-audit-2026-05-07.md) left flat instead of in audits/.

2. Single-source-of-truth violations (Prime Directive breach)

The same fact is maintained in multiple places, guaranteeing drift:

Duplicated fact	Copies
Architecture diagram + source→runtime model	4 (CLAUDE.md, README, handbook §1, handbook §15.1)
Component-type / universal-vs-registry table	3 (README, handbook §1, handbook §3.4a)
Product-hierarchy tree	3 (CLAUDE.md, handbook §4, warp-drive-guide)
Dev ↔ warp-drive integration table	3 (handbook §5.5, warp-drive-guide, dev-lifecycle)
Forbidden PM-file patterns	3 (CLAUDE.md, handbook §4, handbook §15.3 — twice in one doc)
make check target table	3 (handbook §3.7, verification-system, README/CLAUDE)

3. Diátaxis mode-mixing

• project-orchestration-handbook.md (1,455 lines) is all four modes at once (tutorial + how-to + reference + explanation). Split: glossaries (§10–13) + Hooks Reference (§14) → a reference/ set; Quick Start (§2) + setup (§3.1) → a Getting Started tutorial; keep the handbook as the explanation spine.
• warp-drive-guide.md (914 lines) mixes tutorial/how-to with deep internals; the transition-table dump belongs in a reference appendix.
• dev-lifecycle.md buries two self-admittedly “orthogonal” subsystems (Port Allocation #197, Docs-Site Lifecycle #153) that should be their own docs.
• Bright spots to use as templates: warp-drive-guide.md’s TL;DR-first lede and verification-system.md’s tight reference+how-to scoping.

4. Contradictions & staleness — no two docs agree

Claim	CLAUDE.md	README	Handbook	Actual
Universal skills	13	13	16 (table)	17
Registry skills	33	31	“30+”	38
Universal commands	17	16	—	18
Universal agents	4	4	—	5
Hooks	23	26	—	24

• /auto-loop ships as a live, non-deprecated command (commands/auto-loop.md has clean frontmatter) while the handbook explicitly says “stop using it” — a contradiction shipped in the repo.
• Handbook §10.1 universal-skills table omits the orchestrator skill (the one missing row that makes its count 16 not 17).
• Two stale audit artifacts quote three different “correct” numbers; the repo CLAUDE.md is byte-identical to the global ~/.claude/CLAUDE.md, so the drift is mirrored in both.

5. The doc-keeper is structurally incapable — by design

Tool	Does	Cannot do
doc-keeper agent	orchestrates audit (read-only) + sync (mechanical)	“never authors narrative”; never archives; live-code-is-truth, so blind to internally-wrong/contradictory docs
audit.js	5 checks: count-in-prose, forbidden-pattern, broken-link, required-link, filename	no semantic analysis; cross_cutting[] exists in schema but nothing populates it; no orphan/freshness/Diátaxis/readability
sync.js	fixes counts + priority labels only	advertises broken-link repair but has no handler (silent latent bug); never moves/archives
CI	runs 3 sub-targets, --fail-on-drift on high only	never runs make check, so doc-naming gate doesn’t fire in CI; count/deprecation/filename drift is non-blocking → rots freely
check-doc-links.sh	—	orphaned: referenced only in comments, wired nowhere (dead tooling itself)

Governance needs with zero coverage today: information architecture / taxonomy, dead-doc / orphan detection, contradiction / duplication (single-source-of-truth), Diátaxis mode-purity, freshness / ownership metadata, scannability / readability, root-docs-placement rule.

6. Recommended capability shape

Sequenced tooling-first: build the standard + governance tooling, then apply it to BoB’s own docs. The tooling becomes the remediation worklist (drive the auditor to zero) and the regression guard (what’s fixed stays fixed); the current messy docs are the test corpus for the new detectors. Hard dependency: R1 first, since the tooling needs a spec to enforce.

Phase 1 — build (reusable BoB capability):

1. R1 — Documentation IA standard — Diátaxis modes, directory taxonomy, the no-root-docs rule, frontmatter (type/owner/last_reviewed), writing principles (inverted pyramid, controlled vocabulary, single-source-of-truth).
2. R2 — Overhaul the doc-keeper + auditor — link-graph orphan detection, populate cross_cutting[] (duplication/contradiction), Diátaxis mode-purity, freshness metadata, a curate mode that can propose IA changes (human-confirmed).
3. R3 — CI enforcement — run make check in CI; add root-placement + required-frontmatter + orphan checks; make governance findings gate; fix the sync.js broken-link handler; delete or wire the orphaned check-doc-links.sh.

Phase 2 — apply (proof / reference implementation on BoB’s own docs):

4. R4 — Restructure BoB docs into the taxonomy — move root docs + flat docs/ pile into categories, retire tombstones, add nav/index, split mixed-mode docs. Driven and verified by the Phase-1 auditor.
5. R5 — Content remediation — archive dead/orphan docs, reconcile contradictions, fix count drift, resolve the /auto-loop deprecation, rewrite high-traffic docs to inverted-pyramid/scannable form.