doc-audit
Skill61 starsChanged 6 months agoApache-2.0View on GitHub
Audit documentation surface placement (book vs. rustdoc) and refine the policy
12 other projects use a version of this.
Adopted by
Most recently taken up by
- blueclover22/mw_agent_kittheir own version, first seen Nov 4, 2026
- florian101010/awesome-agentic-AI-coding-templatetheir own version, first seen Nov 1, 2026
- sunitghub/canon-skillstheir own version, first seen Oct 22, 2026
- Sprintlaw/legal-skillstheir own version, first seen Oct 17, 2026
- jrittelmeyer/ai-dev-kittheir own version, first seen Oct 15, 2026
- bekalpaslan/promptlinetheir own version, first seen Oct 13, 2026
Other versions12 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 12
- PackmindHub/packmind★ 323same name
- bekalpaslan/promptline★ 13same name
- sunitghub/canon-skills★ 9same name
- florian101010/awesome-agentic-AI-coding-template★ 4same name
- Wubabalala/claude-skills★ 4same name
- ApurvBazari/claude-plugins★ 3same name
- blueclover22/mw_agent_kit★ 1same name
- jarosser06/drift★ 1same name
- jrittelmeyer/ai-dev-kit★ 1same name
- s-frantz/agent-memory-trellis★ 1same name
2 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 repository15 other files it gives its agents.
- alex-reviewSkill
- book-fixmeSkill
- book-refineSkill
- book-reviewSkill
- clean-circuitsSkill
- code-refineSkill
- code-reviewSkill
- fv-docsSkill
- fv-preflightSkill
- fv-reviewSkill
- help-book-reviewSkill
- master-fvSkill
- sean-reviewSkill
- spec-fidelity-auditSkill
- tal-reviewSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. 0 are common, 12 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 12 edited versions we read keep these.
12
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
If you're unsure what the user means, ask before launching agents.
- Very specific: line 31
Read .claude/review-shared/surface-placement.md (the policy).
- Distinctive: line 32
Read the target content identified in Step 1 — both the rustdoc side and the book side.
- Very specific: line 35
If the target is a concept, use Grep to find all occurrences in both book/src/ and Rust source files.
- Very specific: line 37
Read book/FIXME.md and extract the ###-level headings under ## Deferred Issues.
- Distinctive: line 222
If either fails to run, note the failure but do not block the review.
- Distinctive: line 238
After synthesizing findings, but before presenting them to the user:
- Distinctive: line 292
If the validator provides a compliant alternative, replace the original suggestion with the corrected version.
- Distinctive: line 294
If the conflict has no clear resolution, annotate the finding with the conflict so the user can decide during triage.
- Distinctive: line 297
If any suggestions were corrected, briefly note it in the synthesis output.
- Distinctive: line 305
Use AskUserQuestion to let the user decide the disposition of each finding (or group of related findings).
- Distinctive: line 314
If there are many findings, batch them into logical groups.
- Very specific: line 318
Use AskUserQuestion to let the user decide whether to post a synthesis comment on the PR via gh pr comment.
- Distinctive: line 326
Read the target file(s) to get the current content.
- Distinctive: line 332
After all fixes, run relevant checks:
- Very specific: line 342
Check whether a substantially similar issue is already listed.
- Very specific: line 346
If the issue is new, append it as a new ###-level subsection under ## Deferred Issues, following the existing format: a short descriptive …
- Distinctive: line 349
Write the updated file.
- Very specific: line 361
Do NOT modify .claude/review-shared/surface-placement.md directly.
“Common” is measured: kept by at least 6 in 10 of the 12 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
Doc Audit
Audit documentation for surface placement violations — content that lives in the wrong place (book vs. rustdoc) per the project's surface placement policy. For each violation, the user decides whether to fix the content, refine the policy, or defer.
Step 1: Figure Out What to Audit
The user's $ARGUMENTS determine scope. Interpret them:
| Arguments | What to do |
| (empty) | Run git diff -- '*.rs' book/src/ and git diff --cached -- '*.rs' book/src/. Audit uncommitted documentation changes. If no changes, say so and stop. |
| A Rust file or module path | Read the rustdoc for that file/module. Find the corresponding book chapter(s) by following links or searching book/src/. Audit both sides. |
| A book chapter path | Read that chapter. Find the corresponding rustdoc by following links or searching for referenced types/traits. Audit both sides. |
| A concept or trait name (e.g., "Driver", "Gadget") | Search both rustdoc and book for all mentions. Audit the full documentation surface for that concept. |
| Multiple paths or concepts | Handle each, then audit for cross-cutting consistency. |
| A PR number or URL | Fetch the PR diff with gh pr diff. Audit documentation changes in the diff. |
If you're unsure what the user means, ask before launching agents.
Step 2: Gather Context
- Read
.claude/review-shared/surface-placement.md(the policy). - Read the target content identified in Step 1 — both the rustdoc side and the book side. For each piece of documentation being audited, you need visibility into the other surface to detect misplacements.
- If the target is a concept, use Grep to find all occurrences in both
book/src/and Rust source files. - Read
book/FIXME.mdand extract the###-level headings under## Deferred Issues. These will be injected into agent prompts to prevent re-raising known issues.
Step 3: Launch Auditors
Launch three general-purpose Task agents in parallel (model sonnet), each
with a different focus. Also run automated checks in parallel (see below).
Agent 1: Rustdoc Audit
You are auditing rustdoc (Rust doc comments) in the ragu project against its surface placement policy.
Read these files:
.claude/review-shared/surface-placement.md(the placement policy).claude/code-review/standards.md(master code review standards — for severity calibration and reviewer restraint)What to audit: {describe the rustdoc content — file paths, the diff, specific items}
{If the scope is a diff or a narrow range, add: "Focus on the specified content. Flag issues in surrounding text ONLY if the specified content introduced an inconsistency with it."}
{If the scope spans multiple files or a concept, add: "Pay attention to consistency across the files. Flag contradictions, redundancies, or inconsistencies as they span these locations."}
Look for:
- Content in rustdoc that belongs in the book per the policy (math-heavy exposition, design rationale, cross-cutting composition guidance)
- Missing content that the policy requires in rustdoc (preconditions, postconditions, invariants, safety contracts, feature behavior)
- Missing links to book chapters where the policy requires them
Do NOT flag:
- Pre-existing issues on unmodified lines (unless the change introduced an inconsistency)
- Things that linters or compilers already catch
- Pedantic nitpicks not backed by the surface placement policy
- Code-local algorithm docs with math — the policy explicitly allows these
The following issues are already tracked and deferred. Do NOT raise findings that duplicate or overlap with these items: {bullet list of ### headings from book/FIXME.md}
For each finding:
- Location: file path and line number (or item name)
- Rule: which policy rule is violated (quote it)
- Issue: what's wrong, specifically
- Suggestion: a concrete fix — what to move, add, or remove
- Severity:
must-fixorsuggestionTool usage rules:
- Use the Grep tool for searching — do NOT run
greporrgvia Bash.- Use the Read tool to read files — do NOT use
cat,head, ortail.- Use the Glob tool to find files — do NOT use
findorls.- When you do use Bash, the command must be a clean shell command with NO comment lines (
#) prepended. Put your reasoning in thedescriptionparameter, not in the command itself.If you find no violations, say so — don't manufacture problems.
Agent 2: Book Audit
You are auditing book content in the ragu project against its surface placement policy.
Read these files:
.claude/review-shared/surface-placement.md(the placement policy).claude/book-review/standards.md(master book review standards — for severity calibration and reviewer restraint)What to audit: {describe the book content — file paths, the diff, specific sections}
{If the scope is a diff or a narrow range, add: "Focus on the specified content. Flag issues in surrounding text ONLY if the specified content introduced an inconsistency with it."}
{If the scope spans multiple files or a concept, add: "Pay attention to consistency across the passages. Flag contradictions, redundancies, or gaps as they span these locations."}
Look for:
- Content in the book that belongs in rustdoc per the policy (precise API constraints stated only in the book, safety contracts, exact pre/postconditions)
- Content that duplicates rustdoc at the same register (same-register duplication, not informal restatement)
- Missing links to rustdoc items where the policy requires them
- Volatile, implementation-coupled details that belong in code docs
Do NOT flag:
- Pre-existing issues on unmodified lines (unless the change introduced an inconsistency)
- Informal restatements of API requirements that aid understanding — the policy explicitly allows these
- Pedantic nitpicks not backed by the surface placement policy
The following issues are already tracked and deferred. Do NOT raise findings that duplicate or overlap with these items: {bullet list of ### headings from book/FIXME.md}
For each finding:
- Location: file path and line number (or quoted text)
- Rule: which policy rule is violated (quote it)
- Issue: what's wrong, specifically
- Suggestion: a concrete fix — what to move, add, or remove
- Severity:
must-fixorsuggestionTool usage rules:
- Use the Grep tool for searching — do NOT run
greporrgvia Bash.- Use the Read tool to read files — do NOT use
cat,head, ortail.- Use the Glob tool to find files — do NOT use
findorls.- When you do use Bash, the command must be a clean shell command with NO comment lines (
#) prepended. Put your reasoning in thedescriptionparameter, not in the command itself.If you find no violations, say so — don't manufacture problems.
Agent 3: Cross-Reference Audit
You are auditing cross-references between the book and rustdoc in the ragu project against its surface placement policy.
Read these files:
.claude/review-shared/surface-placement.md(the placement policy).claude/book-review/standards.md(for link integrity rules).claude/code-review/standards.md(for severity calibration)What to audit: {describe the scope — which files/concepts on both sides}
{If the scope is a diff or a narrow range, add: "Focus on the specified content. Flag issues in surrounding text ONLY if the specified content introduced an inconsistency with it."}
Look for:
- Non-trivial claims with parallel full descriptions on both surfaces instead of canonical home + summary + link
- Duplicated fragments that are NOT tiny/drift-resistant
- Inconsistent notation or terminology between book and rustdoc for the same concept
- Rustdoc-to-book links that lack resilient summaries (the fragile direction — broken links should degrade gracefully)
Do NOT flag:
- Pre-existing issues on unmodified lines (unless the change introduced an inconsistency)
- Tiny, drift-resistant duplications (one-line definitions, single formulas, short warnings) — the policy explicitly allows these
The following issues are already tracked and deferred. Do NOT raise findings that duplicate or overlap with these items: {bullet list of ### headings from book/FIXME.md}
For each finding:
- Location: both sides — the book location and the rustdoc location
- Rule: which policy rule is violated (quote it)
- Issue: what's wrong, specifically
- Suggestion: a concrete fix
- Severity:
must-fixorsuggestionTool usage rules:
- Use the Grep tool for searching — do NOT run
greporrgvia Bash.- Use the Read tool to read files — do NOT use
cat,head, ortail.- Use the Glob tool to find files — do NOT use
findorls.- When you do use Bash, the command must be a clean shell command with NO comment lines (
#) prepended. Put your reasoning in thedescriptionparameter, not in the command itself.If you find no violations, say so — don't manufacture problems.
Launch ALL three agents in parallel.
Automated Checks
In parallel with the agents, run:
python3 qa/book/broken_links.py— catches broken cross-surface linksRUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all --document-private-items— catches broken intra-doc links
If either fails to run, note the failure but do not block the review. Include any findings alongside agent results in synthesis.
Step 4: Synthesize
Once all agents return, organize findings by location. If multiple agents
flagged overlapping concerns, merge them. Before presenting, read
book/FIXME.md and remove any finding that substantially overlaps with an
already-deferred issue. Present:
- Must-fix issues first
- Suggestions second
- For each finding, note which agent identified it
Step 5: Validate Proposed Changes
After synthesizing findings, but before presenting them to the user:
- Collect all proposed changes (the "suggestion" field from each finding) into a single numbered list — the proposed plan.
Launch validation agents. Fixes may touch rustdoc or book content, so validate against both review systems:
- For EACH
.claude/code-review/*.mdfile exceptstandards.md, launch ageneral-purposeTask agent (modelsonnet). - For EACH
.claude/book-review/*.mdfile exceptstandards.md, launch ageneral-purposeTask agent (modelsonnet).
Give each agent this prompt:
You are validating a set of proposed documentation changes against review policies.
Read these files:
.claude/{code-review or book-review}/standards.md(master standards).claude/{code-review or book-review}/{focus}.md(your policy).claude/review-shared/surface-placement.md(placement policy) {if focus is "documentation" (code-review) or any book-review policy, also include:}.claude/review-shared/writing.md(shared writing rules).claude/review-shared/math.md(shared math rules)
Here is the proposed plan of changes: {numbered list of proposed changes with locations and suggested rewrites}
For each proposed change, check whether applying it would introduce a violation of any rule in your policy, the master standards, or the surface placement policy. Only flag real conflicts — do not restate rules that are already satisfied.
For each conflict found:
- Change #: which proposed change
- Rule violated: quote the relevant policy text
- Conflict: explain specifically how the suggestion violates the rule
- Resolution: suggest how to fix the suggestion to comply
Tool usage rules:
- Use the Grep tool for searching file contents — do NOT run
greporrgas a Bash command. - Use the Read tool to read files — do NOT use
cat,head, ortail. - Use the Glob tool to find files — do NOT use
findorls. - When you do use Bash, the command must be a clean shell command with NO
comment lines (
#) prepended. Put your reasoning in thedescriptionparameter, not in the command itself.
If no proposed changes conflict with your policy, say so.
Launch ALL agents in parallel.
- For EACH
- Merge validation feedback into the findings. For each conflict:
- If the validator provides a compliant alternative, replace the original suggestion with the corrected version.
- If the conflict has no clear resolution, annotate the finding with the conflict so the user can decide during triage.
- If any suggestions were corrected, briefly note it in the synthesis output.
Step 6: Triage
Two modes based on how the audit was invoked:
Local Mode (file paths, diff, concept)
Use AskUserQuestion to let the user decide the disposition of each finding (or group of related findings). For each, offer:
- Fix — move/add/remove documentation as suggested
- Refine — the policy rule is wrong or too strict; note this for a
follow-up
/book-refineor/code-refinepass - Defer — record this finding in
book/FIXME.mdfor future attention - Skip — drop this finding
If there are many findings, batch them into logical groups.
PR Mode (#123 or PR URL)
Use AskUserQuestion to let the user decide whether to post a synthesis comment
on the PR via gh pr comment. Format findings as a numbered list with code
links using the full commit SHA and line ranges (L[start]-L[end]).
Step 7: Apply Fixes
For each finding the user chose to fix:
- Read the target file(s) to get the current content.
- Apply the suggested change using the Edit tool. This may involve:
- Moving content from one surface to the other
- Replacing a full description with summary + link
- Adding a missing link or anchor
- Adding missing preconditions/invariants to rustdoc
- After all fixes, run relevant checks:
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all --document-private-items(if rustdoc was modified)python3 qa/book/broken_links.py(if book was modified)
Step 8: Record Deferred Issues
For each finding the user chose to defer:
- Read
book/FIXME.md. - Check whether a substantially similar issue is already listed. First scan
the
###headings for a potential match; if a heading looks similar, read the paragraph beneath it to confirm it describes the same issue. Only skip if both the heading and description match. - If the issue is new, append it as a new
###-level subsection under## Deferred Issues, following the existing format: a short descriptive heading, then a concise paragraph explaining the issue and its location. - Write the updated file.
Step 9: Handle Refine Requests
For each finding the user chose to refine:
Collect the findings and the user's reasoning (why the rule is wrong or too
strict). Then tell the user to run /book-refine or /code-refine with that
context — surface-placement.md lives in review-shared/, so either refine
skill can update it. Provide the specific findings and reasoning so the user
can paste them as arguments.
Do NOT modify .claude/review-shared/surface-placement.md directly. Policy
changes have wide blast radius (both review systems read the file) and require
the plan-mode, generalization, and system-wide audit steps that the dedicated
refine skills provide.
The goal is to iteratively tighten the policy: each audit round either fixes violations or trims rules that don't hold up, converging toward a small, enforceable set.
Step 10: Report
Tell the user:
- Fixes applied — what was moved/added/removed and where
- Deferred — what was recorded in
book/FIXME.md - Refine needed — findings marked for policy refinement, with the
suggested
/book-refineor/code-refineinvocation - Check results — any issues from rustdoc build or link checks
- Remaining scope — if the audit was narrow, suggest what to audit next
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.

