Close the gaps before you build
Fill documentation gaps until requirements, technical design, acceptance criteria, and test strategy describe one buildable system.
Use this when
Use this before building a new software project when its idea or early documents still leave important implementation decisions open to interpretation.
How it runs
- Inventory the current project documents and identify the missing requirements, technical design, task breakdown, acceptance criteria, or test strategy needed before implementation.
- Find the single largest gap, contradiction, or vague requirement that could make competent engineers build different systems, then close it with concrete detail traceable to a stated requirement.
- Record assumptions that can be made safely, ask the user about genuine product forks, and recheck every edited document against the others for consistency.
- Have two independent reviewers describe the intended components, data model, dependencies, and definition of done; repeat until their descriptions materially agree or a required decision blocks progress.
Done when
✓ Two independent reviewers derive substantially the same build from the project documents. Their descriptions agree on the components, data model, dependencies, and definition of done, and every required artifact is specific, consistent, traceable, and testable.
Why it works
A concrete convergence test exposes ambiguity that a single author may read past. Fixing one divergence at a time keeps the documents coherent and turns project preparation into evidence that another engineer can follow rather than a pile of planning text.
Implementation note
Do not add detail merely to make the documents longer or invent product requirements to force agreement. Keep every claim tied to a stated requirement, record assumptions, and return unresolved product choices to the user.
More docs loops
Keep docs in sync with main
On every push to main, check whether changed code drifted from the docs in /docs and open a PR fixing anything out of date.
Ralph the docs backlog
Document one undocumented public module per fresh-context iteration, verifying every code sample compiles and accumulating style rules in guardrails so the docs read like one author wrote them.
README freshness check
Once a week, verify every command, path, and badge in the README actually works against the current codebase and open a PR fixing anything stale.