Skip to content

whatwhy

FILECONORFYI · 2026
WHATWHYFILED 2026
READ2 MIN READ
WORDS244
SECTIONS5
AI100%

PRDs say what, ADRs say why. A paper trail for repositories that agents work in.

JavaScriptAgent Process
AI-OMETER— DISCLOSURE INDEX
MACHINE-LED100%

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.

§ 01

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.

§ 02

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.

§ 03

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.

sh006 LN
# scaffold the process into this repository
npx whatwhy init --name "Acme" --description "Invoicing for freelancers."
# from then on the repository runs its own copy, offline
node scripts/whatwhy.mjs status
node scripts/whatwhy.mjs new prd "Recurring invoices"
§ 04

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
END OF FILE
Thanks for visiting