occam-docslisted
Install: claude install-skill stephenoffer/occam
# Documenting code
Documentation written straight after the code tends to describe what the author meant to build, in a voice nobody uses. Facts come first, because a well-written wrong claim costs a reader more than a clumsy right one, and a rewrite for voice is when facts slip. That is why the steps run in this order.
Write what the request or the repository calls for. A small fix updates the sentence it made wrong and doesn't earn a new guide. `occam` below means `python3 ../occam/scripts/occam.py`, relative to this skill.
## Order
1. **Reader and scope.** Who reads this, and what are they trying to do? Extend the documents already here and follow their layout before adding one.
2. **Facts from the code.** Read the code as it is now, not the plan, the commit message or your memory of writing it: entry points, public names and signatures, flags and defaults, configuration keys, environment variables, errors and side effects. Keep a list with file and line. Capture real output from `--help` and from running it. Where code and intent disagree, that is a defect to report, not a sentence to write.
3. **Claims the evidence supports.** "Fast", "secure", "production ready" and "supports X" each need a test or measurement you have, with its scope. Say what is untested. Don't document a path nothing reaches, and don't invent output, benchmarks or versions. A breaking change's entry says what breaks, for whom, and the old-to-new steps, with an example you ran. A runbook's command