docs-audit
Skill2 starsChanged 8 days agoMITView on GitHub
Audit canon-ai's active docs claim-by-claim against the code, triage the findings with Tim, apply the approved fixes, and leave the result validated and uncommitted. Use before cutting a minor release (docs/release-process.md "Cutting a release"), or when Tim asks to "audit the docs", "do a docs pass", "check the docs are accurate", or runs /docs-audit. canon-ai-local: not in CANON_OWNED, not shipped to adopters.
16 other projects use a version of this.
Adopted by
Most recently taken up by
- fullstackhouse/skillstheir own version, first seen Nov 15, 2026
- willdady/platypustheir own version, first seen Nov 15, 2026
- home-screens/home-screenstheir own version, first seen Nov 8, 2026
- colonyops/hivetheir own version, first seen Nov 7, 2026
- lifekit-hq/devclawtheir own version, first seen Oct 21, 2026
- strands-agents/harness-sdktheir own version, first seen Oct 14, 2026
Used with
Projects with it also use docs-planner, docs-reviewer and 5 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
strands-agentsSkilldocs-planner
Find the gaps in the Box documentation and produce a prioritized backlog for docs/user/ and docs/design/. Use when planning documentation work, after a feature or a binary ships without a page, for a periodic health check of the docs, or when asked "what docs need writing", "plan the docs work", "prioritize the docs backlog", or "what should we document next".
Also in 3 projects that use this
strands-agentsSkilldocs-reviewer
Review Box drafts in docs/user/ or docs/design/, and wording-only rewrites in docs/dev/. Use after docs-writer, before a docs pull request, or for a requested doc review. Check style and preservation of meaning, then give a Ship it, Tighten, or Rethink verdict. Read-only.
Also in 3 projects that use this
VercelSkilldocs-diagrams
Draw diagrams for the Next.js docs in the style of the ones already published there: the light/dark PNGs an mdx references with `<Image srcLight="/docs/light/<name>.png" srcDark="/docs/dark/<name>.png">`. Use when a guide or API reference needs a new diagram or an existing one needs a change. Hand-written SVG from a primitives library, rendered by headless Chrome at 2x. No AI image generation.
Also in 3 projects that use this
GoogleSkilldocs-writer
Also in 3 projects that use this
MicrosoftSkillwriting-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
Also in 3 projects that use this
GoogleSkilldomain-modeling
Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
Also in 3 projects that use this
Other versions16 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 16
- mastra-ai/mastra★ 30ksame name
- strands-agents/sdk-python★ 9.2ksame name
- strands-agents/harness-sdk★ 8.9ksame name
- hiroppy/tmux-agent-sidebar★ 568same name
- strands-agents/box★ 547same name
- me2resh/apexyard★ 542same name
- Seekers2001/docs-governance★ 320same name
- qshanx/docs-governance★ 253same name
- willdady/platypus★ 130same name
- home-screens/home-screens★ 104same name
6 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- canon-changelogSkill
- canon-initSkill
- canon-inline-reviewSkill
- canon-pipelineSkill
- canon-spec-reviewSkill
- canon-specSkill
- canon-statusSkill
- canon-sweepSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 3 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 13 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Run git branch --show-current and git status --porcelain.
- Very specific: line 13
Run npm run docs-refs-check and npm run sync-templates:check first.
- Very specific: line 27
Add a group for any new long-lived doc that doesn't fit.
- Distinctive: line 50
verify each finding against source before editing.
- Very specific: line 55
if a heading is renamed, grep for §"Old Heading" citations and update them.
- Very specific: line 56
don't stage or commit; finish with npm run -s docs-refs-check.
- Distinctive: line 58
If an agent stops on a rate limit, resume it with SendMessage rather than starting a new one.
- Distinctive: line 65
Leave it uncommitted and ask Tim to commit (git consent is per action).
“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
docs-audit
A claim-level audit: parallel read-only agents check what each doc says against what the code does. npm run docs-refs-check and npm run sync-templates:check already catch broken paths and mirror drift; this skill covers the prose those checks can't see.
0. Before starting
- Run
git branch --show-currentandgit status --porcelain. Auditmain(the release ships from it), or a fresh branch offorigin/main. - Run
npm run docs-refs-checkandnpm run sync-templates:checkfirst; fix what they report so agents aren't re-finding it.
1. Audit (read-only, parallel)
Launch one Sonnet agent per group, in the background, in one message. Every brief says: the repo path and branch; READ-ONLY (no edits, no commits, never cd into .canon/worktrees); verify each factual claim against src/, scripts/, .github/workflows/, package.json, and CHANGELOG.md (newest entries are current behavior), and tasks/_archive/<id>/ when needed; flag omissions an agent starting work would need; flag terminology collisions (a term used in a sense that differs from docs/product-context.md §"Core Concepts & Terminology" or from another doc, or two terms naming one concept) because ambiguous terms send agents down competing paths; don't flag style, wording, or claims it couldn't check; for any doc with a templates/ mirror, also flag adopter-facing text that breaks AGENTS.md §"Adopter Scope".
| Group | Docs |
| Core agent docs | AGENTS.md, CLAUDE.md, docs/architecture.md, docs/codebase-map.md |
| Pipeline | docs/pipeline-orchestrator.md (flags, env vars, reroute, recovery, PR/ship: check each against src/orchestrator/ and canon --help) |
| Patterns + decisions | docs/patterns.md (Trigger Table rows point at real sections and paths), docs/decisions.md (code still follows it? superseded without saying so? contradictions?), docs/lessons-learned.md (entries already promoted elsewhere or now false). Decisions are binding: judge only whether the doc matches reality |
| Product + release | docs/product-context.md, docs/release-process.md (against .github/workflows/auto-release.yml and ci.yml), root README.md (commands, flags, install steps, the recommended-permissions block against src/) |
| Skills + templates | .claude/skills/canon-*/ and .canon/templates/ (commands, flags, verdict names, headings, and paths they cite still exist and mean what they say) |
Add a group for any new long-lived doc that doesn't fit. docs/BACKLOG.md, CHANGELOG.md, docs/task-quality-log.md, and the dated reports (docs/harness-audit-*.md, docs/canon-*-report.md) are records: report stale lines in them, never propose edits as findings. Skip docs/pipeline-invocations.md (auto-logged metrics).
Required return format, most important first, under ~1200 words:
- doc file:line — the claim (short quote)
- verdict: WRONG | STALE | MISSING | OBSOLETE | DUPLICATE <doc:line> | CONTRADICTS <doc:line> | CODE DIVERGES | ADOPTER SCOPE | TERM <doc:line or glossary entry>
- evidence: source file + symbol (or command output)
- proposed fix: exact replacement text, or "delete"…ending with one line: claims checked, and what couldn't be verified.
Save each report to the Claude session's scratchpad directory (never tasks/) as findings-<group>.md, and pass the absolute paths to the editing agents as it arrives (terse, one line per finding, with ids like K1, P1) — the editing agents read these.
2. Triage with Tim
Present one table (group, count, most serious items), recommend applying every WRONG / STALE / MISSING / DUPLICATE / ADOPTER SCOPE finding (TERM findings too, unless which meaning wins is a product call), and raise only real judgment calls (typically: archiving a superseded doc, a code-vs-doc conflict where the code may be the bug, removing dead code a doc describes). Code changes are never part of this pass: note them as follow-ups (an issue, or a /canon-spec task).
3. Apply (parallel, file-disjoint)
One Sonnet editing agent per group, each with an explicit list of files it alone may edit (no two agents share a file; anything shared, such as a patterns.md Trigger Table row, you do yourself afterward). Every brief says:
- verify each finding against source before editing; skip and report any that turn out wrong;
- cite files and symbol names, never line numbers;
- minimal, voice-matching edits; AGENTS.md/CLAUDE.md additions are one terse line;
- edit root copies only, never
templates/; text in a mirrored file must make sense in an adopter's repo (AGENTS.md §"Adopter Scope"); - strict terminology (
docs/product-context.md); punctuation outside quoted §"Heading" citations; - if a heading is renamed, grep for
§"Old Heading"citations and update them; - don't stage or commit; finish with
npm run -s docs-refs-check.
If an agent stops on a rate limit, resume it with SendMessage rather than starting a new one.
4. Validate and review
npm run sync-templates, thennpm run sync-templates:checkandnpm run docs-refs-checkboth clean. If a skill or.canon/templates/file changed, also runnpm test(some tests pin their content).- Spot-check every edit an agent reported as unverified.
/canon-inline-reviewon the uncommitted tree, steered at factual accuracy and adopter scope. Fix real findings.- Leave it uncommitted and ask Tim to commit (git consent is per action). Commit message notes the reviewer.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

