agentleFS
MichaelLeeHobbsMichaelLeeHobbs/skills/skills/clean-code/optimize-docs/SKILL.md

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

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
  1. Distinctive:

    Do not use "could go out of date" as the test.

    line 14
  2. Distinctive:

    If you cannot ask, take the conservative branch and say so in the report: correctness only, no deletions.

    line 34
  3. Distinctive:

    Do this before you form an opinion about any sentence, so the repository grades the prose rather than how it reads.

    line 44
  4. Distinctive:

    Every section in scope gets exactly one verdict, written down before you change anything, and the list accounts for all of them including …

    line 61
  5. Distinctive:

    Recoverable is not the same as cheap: keep a fact spread thin across many files, as reference/SHAPES.md shows.

    line 67
  6. Distinctive:

    Unverifiable: No checkable claim, and no decision inside it.

    line 71
  7. Distinctive:

    Never write one fact into more than one of them.

    line 92
  8. Distinctive:

    Check: every section carries a verdict, with none left unjudged.

    line 98
  9. Distinctive:

    Do not route findings into a new decision record so the prose lands there instead of leaving.

    line 109
  10. Distinctive:

    Create a decision-record directory only when you have at least one decision with an alternative someone could genuinely propose again, and …

    line 111
  11. Distinctive:

    every claim that failed, with both readings

    line 126
  12. Distinctive:

    every section kept that carries no checkable claim, and the one clause justifying each

    line 127
  13. Distinctive:

    every fact you moved, and where it went

    line 128
  14. Distinctive:

    every check you could not run, and the reason

    line 129
  15. Distinctive:

    Every section got a verdict, each defensible on its own rather than as a total.

    line 139

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

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

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.

  1. Which tree. A directory, a docs site, one file.
  2. 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.
  3. 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.
  4. 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 factWhere it belongsWhen the code changes under it
What a function or a flag doesthe code, or a generated referencecannot go stale, or regenerates
A behaviour that must keep holdinga test named for the behaviourthe test fails, loudly
Why this design and not the obvious onea dated decision recorddated, so a reader knows to check
What a word means in this domaina glossaryrarely moves, and moves visibly
Where a thing livesa map naming files onlya link or path check fails
How a human runs thisa procedure whose commands you ranthe command fails when someone runs it
A finished migration, a removed optionnowhere. The history holds itn/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.

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.