doc-audit
Skill13 starsChanged 6 days agoMITView on GitHub
Audit Promptline's documentation against the code and fix the drift. Use this whenever the user asks to audit, check, sweep, refresh or true up the docs, says the docs may be stale or "out of date", asks whether BEHAVIOR.md, README.md, CLAUDE.md, BACKLOG.md, the site or a skill still matches the code, or wants a pass before a release or after a big merge, even without the word audit. It checks every claim a doc makes that the code can confirm, fixes the doc (never the code) on a branch, one commit per doc, and reports what it changed and what it left for the human.
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
- tachyon-zcash/ragutheir own version, first seen Oct 8, 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
- tachyon-zcash/ragu★ 61same 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 repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- dependabotSkill
- fresh-eyesSkill
- maintenanceSkill
- monthly-themeSkill
- releaseSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 1 is distinctive, and 5 are very specific to this project.
0
Common
Most of the 12 edited versions we read keep these.
1
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 53
Don't correct them to today's code.
- Very specific: line 70
every path in backticks exists: extract
[\w./-]+\.(rs|ts|tsx|js|mjs|json|md|css|html)and test each. - Very specific: line 71
every command named is in generate_handler!
- Very specific: line 72
every npm script named is in package.json.
- Very specific: line 73
every file:line reference still lands on the thing named.
- Distinctive: line 82
Don't add docs for things the doc never meant to cover.
“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
The docs here are dense with checkable facts: file names, command names,
event names, settings keys, check counts, script flags, ports, default
hotkeys, release steps. Each one drifts the moment code moves and the doc
doesn't. This audit finds those claims, checks each against the code at
HEAD, and fixes the doc so it is true again.
The code is the source of truth. A doc that disagrees with the code is the thing to fix. When the code looks wrong instead (the doc describes a deliberate decision, with a why, that the code no longer honours), don't change either: report it under For the human as a possible regression.
Scope
$ARGUMENTS narrows it: a file (BEHAVIOR.md), an area (site,
skills), or a range (since v0.2.20: only claims touched by
git diff v0.2.20..HEAD --stat code changes, which is the fast pass before
a release). Empty means the whole inventory below.
The inventory
What each doc claims, and what to check it against. Work down this list; the hotspots are where drift has actually turned up.
| Doc | Claims to check | Against | Hotspots |
CLAUDE.md | file layout and what each file holds; the checks and their count; npm scripts; ports; skills list; release steps, script names and flags; mock behaviour | src-tauri/src/, .github/workflows/ci.yml, package.json scripts, .gitignore (!.claude/skills/…), scripts/*.mjs arg parsing, src/lib/dev-mock.ts | check count said in more than one place; "the N project skills"; flags a script renamed |
BEHAVIOR.md | per section: what a surface does, which command / event / setting / file carries it, the tests named | the code the section names; generate_handler! in lib.rs; emit(/listen( names; settings structs in Rust and src/lib/prefs.ts; test names in tests/, e2e/, #[test] | renamed commands and events; a why whose trap was since removed; test names cited that no longer exist |
README.md | what the user sees and presses: hotkey, menus, labels, settings, install ids (winget AlpaslanBek.Promptline, Scoop bucket), data folder, known limitations, dev commands | UI strings in src/manager/, src/popup/; tauri.conf.json; package.json; BEHAVIOR.md | a limitation that's been fixed; a label renamed in the UI; tests/readme-content.test.js pins some lines, so read it before rewording the top |
BACKLOG.md | which items are open, which shipped and in which version | git log --oneline, release notes (gh release view vX.Y.Z), the code | open items that already shipped; struck items without a version |
CONTRIBUTING.md, SECURITY.md | commands to run, supported versions, how to report | package.json, latest tag | supported version line behind the latest release |
THIRD-PARTY-NOTICES.md | the bundled dependencies and licences | package.json deps, src-tauri/Cargo.toml, fonts in src/ | a dependency added or dropped since; the release skill asks for the entry before the bump, so check package.json and Cargo.toml deps against the file |
packs/TEMPLATE.md | the pack file format | the pack parser in ui/core.js and src-tauri/src/packs.rs | fields the parser now accepts or rejects |
design/components/*/README.md | props, variants, tokens | the component in src/components/ui/, design/tokens.json | variants added or removed |
site/ (index.html, posts/*) | features and screens described, the privacy note, the hotkey, prices ("free"), platform claims | the app; site/sitemap.xml lists every page; tests/site-*.test.js | a feature claim the app dropped; a page missing from the sitemap or the Blog JSON-LD |
.claude/skills/*/SKILL.md | procedure steps, script names, flags | CLAUDE.md (the skills defer to it), their own scripts/ | a step CLAUDE.md changed and the skill still repeats |
docs/architecture/*.json | the map at meta.repository.revision | git log <revision>..HEAD -- src-tauri/src src/ | report staleness only; refreshing is its own procedure in CLAUDE.md |
Local-only docs (docs/MARKETING.md, DESIGN.md, PRODUCT.md,
PITCH-SCRIPT.md) are ignored by git. Check them only when the scope names
them; fix factual drift in place and say so, since nothing gets committed.
Out of bounds:
docs/history/*: records of what was found and decided at the time. Don't correct them to today's code. The one check: test names that cite a finding id (H1,BH3-1) still point at an id that exists there.site/latest.json: written by the release step, never by hand.- Code, tests, config. If a test pins wording you need to change, stop and ask; the test may be the decision.
Procedure
- Branch.
git switch -c chore/doc-audit-<yyyy-mm-dd>off an up-to-datemaster. A dirty tree: say what's dirty and ask before going on (a phantomsrc-tauri/Cargo.tomlLF diff is fine togit checkout --, per CLAUDE.md). - Extract claims. For each doc in scope, read it and list every checkable claim: a path, a symbol, a command or event name, a number, a default, a flag, a label, a URL inside the repo. Skip opinion and rationale; check only the facts the rationale rests on.
- Check each claim with Grep and Read, at
HEAD. Useful sweeps:- every path in backticks exists: extract
`[\w./-]+\.(rs|ts|tsx|js|mjs|json|md|css|html)`and test each; - every command named is in
generate_handler!; - every npm script named is in
package.json; - every
file:linereference still lands on the thing named. A claim that can only be checked by running the app (window focus, real paste, the hotkey) is unverified, not drift; list it, don't change it.
- every path in backticks exists: extract
- Classify each failure:
- Wrong: the doc states something false (a renamed command, a count that's off, a fixed limitation still listed).
- Missing: behaviour the code has and the doc's own scope says it should cover (a new setting in a section that lists the settings). Don't add docs for things the doc never meant to cover.
- Dead: a reference to something gone (a file, a test, a step).
- Contradiction: two docs disagree; the code decides which is right, and both get fixed.
- Fix each Wrong, Missing, Dead and Contradiction in the doc, in its
own voice: same density, same plain prose,
behaviour, sentence case, no new headings unless the doc already structures that way. Smallest edit that makes it true; rewording for style is not this audit's job.unix2dosthe files you touch, and only those. - Check.
npm test(the readme and site content tests),npm run lint, andnpx tsc -b --noEmitif you touched anything a test reads. Rust checks aren't needed for doc-only changes. - Commit one commit per doc, subject
Docs: <what was true again>(e.g.Docs: CLAUDE.md counts seven checks throughout), body naming each drift and what the code says. Don't push or merge; that's the human's say-so.
For the whole inventory, fan the reading out: one read-only general-purpose agent per row group (CLAUDE.md and skills; BEHAVIOR.md; README, site and CONTRIBUTING/SECURITY; BACKLOG, notices, packs, design), each told not to edit anything and to return findings in the report's row shape. Do the fixes yourself afterwards; several findings land in the same file and edits from parallel agents collide.
The report
Lead with the counts, then:
| Doc | Line | Kind | Doc said | Code says (where) | Fixed |
then Unverified (claims only the running app can confirm), then For the human: possible regressions (doc right, code wrong), test-pinned wording, decisions a doc implies but nobody made, and the architecture map's staleness. End with the branch name and the commits. A clean audit says so in one line and lists what it checked.
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.

