Doc Audit

Called automatically by wrapup — do not invoke directly.

Audit user-facing documentation for accuracy. Append to doc-findings.md (project root) only after explicit confirmation.

Run only when a user-facing doc changed (the Scope list below). Otherwise record the skip and stop.

Mechanical checks first, no model: run tools/doc-check <changed docs> (resolve it with command -v sprint's directory in a consumer project where tools/ isn't symlinked in). It checks that relative links resolve, that every sprint/tkt subcommand in a code span or fence exists, and that every tools/, skills/, docs/ file path in a code span exists. Fix each finding it prints (exit 1) before the model pass; do not re-check these by hand. The checks below are the ones a script cannot judge.

Scope

• README.md
• docs/*.md
• tools/*.md
• Skill frontmatter: description and summary fields across skills/*/SKILL.md and standards/*.md — only if those paths exist in the current project

Steps

1. Read doc-findings.md if it exists; skip logged issues.
2. Read the changed docs in scope (plus README.md when a command or flow changed). Note claims about features, behavior, and requirements.
3. If skills/ exists, read description and summary frontmatter in skills/*/SKILL.md and standards/*.md; compare to each skill body.

4. Run these checks. Flag only high-confidence issues:

   Overstated automation — phrases like "automatically", "no setup needed", "just run", or "that's it" where a hidden step exists.

   Missing prerequisites — required tool, config, fork, or file structure not stated.

   Absolute claims — "always", "never", "zero", "every", "any" with likely exceptions.

   Scope inflation — frontmatter claims behavior not present in the body, or counts that do not match.

   Internal consistency — conflicting descriptions across README, guides, and skill files. Quote both.

   Affected doc coverage — when code, workflow, UI, command behavior, or screenshots change, search every doc surface that could describe it: README, guides, examples, tool docs, skill docs, standards, and catalog text. Do not stop at the first visible doc.

   Skill-name accuracy — if ./tools/skills.sh exists, run ./tools/skills.sh list; compare to the skill names in README/guide command examples (tools/doc-check only judges sprint/tkt subcommands and paths).

   Workflow gate accuracy — distinguish UI state changes from workflow commands. Board actions such as creating tickets or moving cards update local ticket state only; do not imply they run agent workflows, wrapup, validation, or close pipelines unless the tool actually does.

   Heading style — user-facing README headings should be Title Case. Keep intentional brand casing, command names, and code-block comments unchanged.

   Private content — real names, emails, usernames, home paths, private ticket prefixes, company references, secrets. Flag; do not redact automatically.

5. When competitor docs, adjacent tools, or inspiration repos are part of the task, translate the useful input into canon's own intent:

   • Identify what works in their UX, docs, install flow, command model, and positioning.
   • Decide whether the learning belongs in README positioning, a guide, a skill, a standard, or tool behavior.
   • If the pattern should affect future agent behavior, recommend the specific skill or standard update before wrapup.
   • Preserve canon's constraints: local-first state, minimal command surface, live-reference skills, no SaaS dependency, no bloated methodology.
6. Report new findings by check type. Quote the claim and explain the issue. If none: say so and stop.
7. Ask: Append these to doc-findings.md? (y to confirm). Do not write without y. Write to doc-findings.md at the project root.

doc-findings.md entry format

### YYYY-MM-DD — Short title
**File:** path
**Claim:** exact quote
**Issue:** why it's inaccurate or overstated
**Action:** what was done (or "Open — no action yet")

Keep entries concise. When the file exceeds 60 lines, archive entries older than 6 months before appending.