agentleFS
tstraub89tstraub89/canon-ai/.claude/skills/docs-audit/SKILL.md

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

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-agentsSkill

    docs-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-agentsSkill

    docs-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

  • VercelSkill

    docs-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

  • GoogleSkill

    docs-writer

    Also in 3 projects that use this

  • MicrosoftSkill

    writing-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

  • GoogleSkill

    domain-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

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
  1. Very specific:

    Run git branch --show-current and git status --porcelain.

    line 12
  2. Very specific:

    Run npm run docs-refs-check and npm run sync-templates:check first.

    line 13
  3. Very specific:

    Add a group for any new long-lived doc that doesn't fit.

    line 27
  4. Distinctive:

    verify each finding against source before editing.

    line 50
  5. Very specific:

    if a heading is renamed, grep for §"Old Heading" citations and update them.

    line 55
  6. Very specific:

    don't stage or commit; finish with npm run -s docs-refs-check.

    line 56
  7. Distinctive:

    If an agent stops on a rate limit, resume it with SendMessage rather than starting a new one.

    line 58
  8. Distinctive:

    Leave it uncommitted and ask Tim to commit (git consent is per action).

    line 65

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-current and git status --porcelain. Audit main (the release ships from it), or a fresh branch off origin/main.
  • Run npm run docs-refs-check and npm run sync-templates:check first; 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".

GroupDocs
Core agent docsAGENTS.md, CLAUDE.md, docs/architecture.md, docs/codebase-map.md
Pipelinedocs/pipeline-orchestrator.md (flags, env vars, reroute, recovery, PR/ship: check each against src/orchestrator/ and canon --help)
Patterns + decisionsdocs/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 + releasedocs/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

  1. npm run sync-templates, then npm run sync-templates:check and npm run docs-refs-check both clean. If a skill or .canon/templates/ file changed, also run npm test (some tests pin their content).
  2. Spot-check every edit an agent reported as unverified.
  3. /canon-inline-review on the uncommitted tree, steered at factual accuracy and adopter scope. Fix real findings.
  4. Leave it uncommitted and ask Tim to commit (git consent is per action). Commit message notes the reviewer.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.