docs-manager

Quick Summary

Goal: Detect docs impacted by code changes, update the right docs (project + business-feature) accurately and surgically, then report checked/updated/skipped — so docs stay synchronized with code without fabrication or scratch-creation.

Summary:

• Triage from git diff → map changed files to impacted doc types via node .claude/scripts/doc-impact-map.cjs + the section-impact mapping; fast-exit ONLY when that map routes nothing (a .claude/**-only diff still rots glob-derived inventory counts, so it is NOT a fast exit).
• Never create business-feature docs from scratch (recommend /spec); update only the impacted sections, surgically.
• Verify the code change before fixing any stale doc; map downstream references before removing a section.
• No meta-log in AI-facing docs — write current actionable state only; history goes to git / CHANGELOG.md / docs/adr/**.

Workflow:

1. Triage — git diff --name-only → categorize changed files → determine impacted doc types
2. Project Context Sync — Verify the routed docs/project-reference/** docs and docs/project-config.json sections against the diff (see Reference-Doc Freshness Contract), then update project-structure-reference.md / README.md when architecture, scope, or setup changed
3. Business Feature Docs — Auto-detect affected modules, check existing docs, update only impacted sections per section-impact mapping
4. Summary Report — Report checked, updated, skipped

Key Rules:

• NEVER create business feature docs from scratch — recommend /spec skill for new docs
• NEVER auto-fix stale docs before verifying the code change — verify first, then edit
• NEVER remove doc sections before checking downstream references — map referencing files first
• No meta-log in AI-facing docs — CLAUDE.md, AGENTS.md, agent .md, SKILL.md, .claude/docs/** read as live instruction; write only current actionable state. NEVER narrate change-history, migration rationale, or provenance ("formerly", "removed in the … refactor", "now embedded / now lives here"). History → git / CHANGELOG.md / docs/adr/** / plans/reports/**
• Fast Exit: ONLY when node .claude/scripts/doc-impact-map.cjs routes zero docs, zero config sections, and zero unrouted files → report "No documentation impacted" and exit. A .claude/**- or tooling-only diff is NOT a fast exit — it rots the skill/hook/agent/workflow counts and catalogs that CLAUDE.md, docs-index-reference.md, and project-structure-reference.md derive by globbing
• Freshness verdicts are evidence, not impressions — every routed doc gets FRESH | PATCHED | RESCAN REQUIRED | UNVERIFIED; a doc you did not check is UNVERIFIED, NEVER FRESH
• NEVER write <!-- Last scanned: --> — only a full /scan --target=X may move that stamp; an impact-scoped patch writes <!-- Last verified: YYYY-MM-DD (docs-update, impact-scoped) --> on the line after it — but ONLY in a doc that already carries a Last scanned stamp. A doc with NO such stamp (CLAUDE.md, .claude/docs/**, any AI-facing instruction file) gets NO stamp at all; record its verdict in the run report instead — the no-meta-log rule above WINS, it is never overridden by this one
• Section-Impact Mapping: entity change → sections 3,5,6; new endpoint → sections 8,11,12; new functionality → section 15 (mandatory)

[IMPORTANT] Goal: Detect docs impacted by code changes, update the right docs (project + business-feature) accurately and surgically, then report checked/updated/skipped — so docs stay synchronized with code without fabrication or scratch-creation. [IMPORTANT] NEVER create business feature docs from scratch — use /spec skill. NEVER fabricate paths or behavior — investigate first. Evidence Gate: Every claim requires file:line proof. Confidence >80% to act, <80% verify first. NEVER fabricate paths, names, or behavior. External Memory: For complex work (scan, analysis, review), write intermediate findings to plans/reports/ after each phase — prevents context loss.