whatwhy
PRDs say what, ADRs say why. A paper trail for repositories that agents work in.
Scaffolded by Claude the day after the repo went up, summarised from its README and its own PRDs and ADRs. I'll edit and add to it as the project settles.
Overview
Agents decide as they go, and the reasons vanish with the session. whatwhy makes the reasons a precondition of the commit: one dependency-free Node script, vendored into the repository by npx whatwhy init, that numbers, indexes and checks PRDs and ADRs so an agent never does it by hand. Also a template repository, and built with its own process.
Definitions
PRD. A product requirements document says what is being built and who it is for. You write one when adding something a user will see, and it stays a living document until that thing ships.
ADR. An architecture decision record says why a choice that is expensive to reverse was made. Once accepted it is frozen: a change of mind gets a new ADR that supersedes the old one, so the history of the reasoning stays intact.
Quick start
Run it in any git repository, new or existing. It copies the script to scripts/whatwhy.mjs, adds the process to AGENTS.md, and sets up the templates, config, commit hook and pull request workflow. Files you already have are left alone. Needs Node 20 or later and git.
# scaffold the process into this repositorynpx whatwhy init --name "Acme" --description "Invoicing for freelancers."# from then on the repository runs its own copy, offlinenode scripts/whatwhy.mjs statusnode scripts/whatwhy.mjs new prd "Recurring invoices"
Highlights
- One command per step: new, accept, approve, ship, check
- Every command takes --json and returns { data, changes[], warnings[] }
- Structure and immutability rules block the commit; traceability and architecture rules warn
- Converts existing ADRs in place
- No dependencies. The script is copied into the repository and runs offline