Follow the docs literally to find where they lie, then rank the gaps by who gets blocked — and which wrong docs to delete.
Free & open · no signup · read-only — it ends by asking · nothing leaves your machine
You are working inside this repo. Mission: test the documentation against reality — follow it literally, find where it lies, find what's missing — and rank the gaps by who gets blocked.
Read-only pass. Your only write is the report file.
Phase 2 sweeps the codebase through every one of these, citing file and line for each finding.
follow it step by step; record the first point of failure and every divergence
diff the env vars and flags the code reads against what any doc mentions
documented endpoints/params vs what routes actually accept and return
inline comments contradicting the code beside them (worse than no comment)
could a new dev draw the architecture from docs alone? What's the biggest unexplained area?
broken links, references to removed files, stale screenshots
is there any way to learn what shipped recently and why?
One structured report at the repo root — or in reports/, if you keep one — the same shape every time, ready for a teammate — or the optional Studio — to act on.
Every Goal Prompt follows the same four steps, so results are consistent and repeatable — no matter which one you run.
List everything that documents this project.
README truth-test — follow it step by step.
Rank by who's blocked and how hard.
Create DOCS.md at repo root.
Copy it and paste it into your agent inside the repo you want checked.
Install the goal plugin once — two commands — then just type /goal:documentation-audit.
/plugin marketplace add GhostlyGawd/goal-prompts/plugin install goal@goal-promptsOr install only this Goal Prompt as /goal-documentation-audit:
curl -fsSL https://goal-prompts.vercel.app/install | BRIEF=16 shLet an agent fetch it mid-conversation, or pull the raw Goal Prompt by URL.
https://goal-prompts.vercel.app/raw/16.mdNothing hidden — this is the whole Goal Prompt, verbatim. Read it in a minute, edit it, or copy it as-is.
# Goal: Documentation Audit You are working inside this repo. Mission: test the documentation against reality — follow it literally, find where it lies, find what's missing — and rank the gaps by who gets blocked. Read-only pass. Your only write is the report file. ## Phase 1 — Inventory and audiences - List everything that documents this project: README, docs folders, wikis referenced, inline comments, API docs, changelog. - Name the audiences: new developer, end user, operator/deployer. Each doc serves one — or fails all. ## Phase 2 — Audit through 7 lenses 1. **README truth-test** — follow it step by step; record the first point of failure and every divergence 2. **Config coverage** — diff the env vars and flags the code reads against what any doc mentions 3. **API drift** — documented endpoints/params vs what routes actually accept and return 4. **Lying comments** — inline comments contradicting the code beside them (worse than no comment) 5. **The missing map** — could a new dev draw the architecture from docs alone? What's the biggest unexplained area? 6. **Dead ends** — broken links, references to removed files, stale screenshots 7. **Change history** — is there any way to learn what shipped recently and why? ## Phase 3 — Curate - Rank by who's blocked and how hard: setup-blocking beats nice-to-know - Mark docs to DELETE: wrong documentation is worse than none - Every finding cites the doc location and the code that contradicts it ## Phase 4 — Report Create `DOCS.md` at repo root: 1. **Truth-test log** — the README walk with divergences inline 2. **Fix-now list** — actively wrong docs: correct or delete, with effort 3. **Gap list** — missing docs ranked by blocked audience 4. **Proposed doc map** — what should exist, one line each, nothing aspirational 5. **The first doc to write** — outlined in 5 bullets Start the report with today's date. If `DOCS.md` already exists from a previous run, read it first and lead with what changed since. ## Rules - Test docs by following them, not by reading them - Fewer, accurate docs beat many stale ones - If a `reports/` directory exists at the repo root, write the report there instead of the root. - Before asking, present the top findings as a ranked list in plain words - Report only — end by asking which docs to fix first
reports/ directory exists at the repo root, write the report there instead of the root.Extract every user-facing string; hunt jargon, vague CTAs, and unhelpful errors; rewrite the worst ten before/after.
Naming, error shapes, status codes, and versioning — find the inconsistencies and sequence fixes from non-breaking to breaking.
Can a newcomer explain back what this is, who it's for, and how it works after one screen — or does the curse of knowledge leave them guessing?
Every message the product shows when something goes wrong — whether it says what happened, why, and what to do next, or leaves the user stuck.