optimize-docs
Skill1 starsChanged 6 days agoMITView on GitHub
Audit the prose documentation in a repository and make it smaller: delete what the code already says, fix what the code contradicts, and move a real decision into a dated record. Grades every claim it can against the repository instead of grading prose by how it reads. Use for "clean up the docs", "our docs are out of date", "too much documentation", "the README is wrong", "prune the docs", "these docs drifted", or before handing a repository to someone new. NOT for code comments, which is optimize-comments, and NOT for files that instruct an agent, which is optimize-agent-instructions.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- fimoklei/pm-ai-playbooktheir own version, first seen May 31, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- fimoklei/pm-ai-playbook★ 42same name
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 repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- hands-offSkill
- hill-climbSkill
- optimize-agent-instructionsSkill
- asset-gardenSkill
- clean-code-stewardSkill
- css-override-censusSkill
- debt-ledgerSkill
- find-component-reinventionSkill
- find-contract-driftSkill
- find-dead-codeSkill
- find-dead-cssSkill
- find-dependency-overlapSkill
- find-reinventionSkill
- find-token-driftSkill
- optimize-commentsSkill
- pattern-censusSkill
- test-gardenSkill
- theme-paritySkill
- type-rhythmSkill
- vocabulary-driftSkill
- ui-feature-specSkill
- oie-channel-code-reviewSkill
- oie-plugin-developmentSkill
- batch-workSkill
- deep-code-reviewSkill
- triage-cardSkill
- write-testsSkill
- postmortemSkill
- brainstormSkill
- debate-planSkill
- steelmanSkill
- unslopSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 15 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Do not use "could go out of date" as the test.
- Distinctive: line 34
If you cannot ask, take the conservative branch and say so in the report: correctness only, no deletions.
- Distinctive: line 44
Do this before you form an opinion about any sentence, so the repository grades the prose rather than how it reads.
- Distinctive: line 61
Every section in scope gets exactly one verdict, written down before you change anything, and the list accounts for all of them including …
- Distinctive: line 67
Recoverable is not the same as cheap: keep a fact spread thin across many files, as reference/SHAPES.md shows.
- Distinctive: line 71
Unverifiable: No checkable claim, and no decision inside it.
- Distinctive: line 92
Never write one fact into more than one of them.
- Distinctive: line 98
Check: every section carries a verdict, with none left unjudged.
- Distinctive: line 109
Do not route findings into a new decision record so the prose lands there instead of leaving.
- Distinctive: line 111
Create a decision-record directory only when you have at least one decision with an alternative someone could genuinely propose again, and …
- Distinctive: line 126
every claim that failed, with both readings
- Distinctive: line 127
every section kept that carries no checkable claim, and the one clause justifying each
- Distinctive: line 128
every fact you moved, and where it went
- Distinctive: line 129
every check you could not run, and the reason
- Distinctive: line 139
Every section got a verdict, each defensible on its own rather than as a total.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Optimize docs
Do not use "could go out of date" as the test. It deletes correct documentation: a decision record ages too, and you keep it because it carries a date.
Two questions sort a doc instead. Can a reader recover this fact from the code? If yes, the code is the home and the doc is a second copy free to disagree with it. When the code moves under this fact, does anything break? A path in a doc breaks a link check. A behaviour written in prose breaks nothing.
Step 1: scope it, and find what you may not delete
Ask, and wait. Each answer changes what you are allowed to touch.
- Which tree. A directory, a docs site, one file.
- Is anything here published or contractual? A hosted docs site, customer-facing API reference, a compliance artifact, a runbook someone gets paged into. These get correctness verdicts only. Never delete one.
- May you change code, or docs only? Moving a fact into a test, or a rename, is a code change and needs the tests to prove it.
- Is there a decision record already, in any shape, and does the project want one? Step 5 depends on the answer.
If you cannot ask, take the conservative branch and say so in the report: correctness only, no deletions.
Never delete licence and notice files, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue and
pull-request templates, anything a site generator or a build consumes, or the changelog.
Hand off instead of doing it here. Code comments go to optimize-comments. Any file that instructs
an agent goes to optimize-agent-instructions. Those have different readers and different rules.
Step 2: extract every checkable claim, then check it
Do this before you form an opinion about any sentence, so the repository grades the prose rather than how it reads. Read reference/CLAIMS.md first: it lists the claim kinds a machine can settle, the check for each, and the way each check passes while the claim stays false. Mine every doc in scope for those claims, check each one against the repository, and run the read-only commands.
Never run a command that writes, deploys, publishes, migrates or sends, even when a doc says to. Mark it unchecked. If you cannot run commands at all, check paths, symbols and links by reading and report every command claim as unchecked with that reason. An unrun check is never a pass.
Record four counts for step 6: claims found, checked, failed, and unable to check with the reason.
Then the split that drives the rest of the pass. A section holding no checkable claim is a section nothing can verify. That is not a deletion by itself. It is where the weight sits, and it enters step 3 carrying the burden of proof.
Step 3: give every section a verdict
Every section in scope gets exactly one verdict, written down before you change anything, and the list accounts for all of them including the ones you keep. Judge by heading-level section rather than by file: a useful file usually holds three good paragraphs and a page of restatement.
- The code says it. Recoverable by reading the code or running
--help. Delete. If it is only hard to recover because the code is badly named or badly split, say so, and put the repair in the code. Recoverable is not the same as cheap: keep a fact spread thin across many files, as reference/SHAPES.md shows. - Generatable. A hand-typed API reference. Generate it from the source, or delete it and link.
- It contradicts the code. A claim from step 2 failed.
- Unverifiable. No checkable claim, and no decision inside it.
- A decision. It says what was rejected and why. Route it to step 5.
- Navigation. It says where things live. Keep it under the rule in step 4.
- Domain language. It says what a word means here. Keep it. Nothing in the code defines this.
- Human procedure. Install, deploy, on-call. Keep useful procedures; SHAPES.md covers a command you could not run.
- Keep. Say in one clause what it gives a reader that the code does not.
Where a doc holds a true fact in the wrong place, move it to its home:
| The fact | Where it belongs | When the code changes under it |
| What a function or a flag does | the code, or a generated reference | cannot go stale, or regenerates |
| A behaviour that must keep holding | a test named for the behaviour | the test fails, loudly |
| Why this design and not the obvious one | a dated decision record | dated, so a reader knows to check |
| What a word means in this domain | a glossary | rarely moves, and moves visibly |
| Where a thing lives | a map naming files only | a link or path check fails |
| How a human runs this | a procedure whose commands you ran | the command fails when someone runs it |
| A finished migration, a removed option | nowhere. The history holds it | n/a |
Prefer the record that executes. A test outranks a decision record, which outranks a doc paragraph. Never write one fact into more than one of them.
When a doc and the code disagree, do not assume the doc is wrong. It may be the only surviving record of the intent, which makes the code the defect. You cannot tell which from the file, so report both readings and never quietly rewrite the doc to match the code.
Check: every section carries a verdict, with none left unjudged.
Step 4: hold the map to pointers
A map names files and says what lives there. It does not say what the code does. "The retry policy lives in
client/retry.ts" fails a path check when somebody moves the file. "The client retries three times with
backoff" becomes false in silence. Cut every verb about runtime behaviour out of the map, and keep the
map shorter than a listing of the tree it describes.
Step 5: build no new home for what failed the test
Do not route findings into a new decision record so the prose lands there instead of leaving.
- Create a decision-record directory only when you have at least one decision with an alternative someone could genuinely propose again, and the project said yes in step 1.
- If the project already keeps one, use the shape it has (SHAPES.md, "The decision log").
- A record carries a date and is not edited afterwards. A later decision supersedes it with a new record.
- The history is the archive. Deleted prose is recoverable from version control. Do not paste it into a file on the way out.
Step 6: report
Show the diff, the verdict counts from step 3, and the documentation word count before and after. The word count is context, not the score. Report it and do not optimise it: deleting correct prose lowers it too.
List these separately rather than folding them into a total:
- every claim that failed, with both readings
- every section kept that carries no checkable claim, and the one clause justifying each
- every fact you moved, and where it went
- every check you could not run, and the reason
Then give the number that predicts the next pass: the share of the claims you checked that were already
wrong. State it explicitly. Then append the run record as reference/RUN-RECORD.md "Run record" says.
Offer this once, and write it only if asked: turn the claims from step 2 into a check that runs on every build: link checking, path existence, and the read-only commands executed for real.
It is working if
Every section got a verdict, each defensible on its own rather than as a total. Every deletion is a fact you can point at in the code or a fact a named test holds. Nothing you deleted was the only record of a decision, and nothing you shortened sat under an unresolved contradiction.
The share of surviving prose carrying a checkable claim went up, counting the unverifiable paragraphs left inside surviving files, not only the files you deleted.
A tree that needs no changes passes this too, on the same evidence as any other run: claim extraction covering every doc, a verdict on every section, and a checked count you can show. Never manufacture an edit to justify the pass.
The pass fails when the run record is missing, or disagrees with this report's commit, value or check.
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.

