Best for
- READMEs last updated three jobs ago
- Projects where setup knowledge lives in one person's head
- Making the first hour with your repo painless
What you give it
- The repository, and tolerance for questions about the parts only you know
What you get back
- A README where every command was executed during writing — the broken ones fixed or flagged
- The real structure: what this is, quickstart, configuration, common tasks, troubleshooting
- The folklore captured: the environment quirk, the port that must be free, the seed step everyone forgets
How it works
- Executes the existing README from a clean state first — the diff between document and reality is the work list.
- Structures for the newcomer's actual questions in order: what is this, how do I run it, how do I change it, what will go wrong.
- Captures folklore by interview: the quirks veterans route around automatically get written down.
- Keeps it maintainable: short, linking out to deep docs, with the commands in copy-pasteable blocks.
Example
You: Refresh our README; the last three starters each lost a day to it.
Result: Found: 5 of 11 setup steps broken (two renamed scripts, a missing prerequisite, an environment variable the code now requires, and a database step that silently matters). All fixed and re-verified from a clean checkout. Added: the quickstart that gets to running in four commands, the troubleshooting section built from what the last three starters actually hit, and the one-paragraph 'what this is' the repo never had. Day-one time, measured with the next starter: 50 minutes.
Limits — please read
- Verification runs what a developer machine can; steps needing special access get marked with their grantor.
- A README is the front door, not the whole house — deep architecture docs are a separate job it links to.
- It will propose deleting sections that are archaeology; you approve the funerals.