Documentation
Docs written later are docs written from memory, and they are wrong in ways nobody notices until someone follows them.
Ship documentation with the change
Every subsystem ships with its SOP in the same commit. Not afterwards.
| File | Holds |
|---|---|
docs/register.md | Every ask, with an honest status |
docs/decisions.md | Standing calls and what would justify revisiting them |
docs/infrastructure.md | Accounts, and the operational traps already paid for |
docs/roles.md | What each role can do — and honestly, cannot |
docs/sop/ | Task procedures, in the doing-person's language |
docs/rules/ | These non-negotiables |
skills/*/SKILL.md | The methodology agents follow — the real spec for output quality |
Status must be literal
Built means the code exists and typechecks. Live means it has run and the evidence is stated. They are different words because they are different things.
Say what does not exist
A document describing an unbuilt feature is the most expensive kind of wrong. Mark stubs explicitly. Showing seed data beside real data is how a system starts lying quietly.
Record the wrong turns
decisions.md and infrastructure.md deliberately record diagnoses that turned out to be wrong — RegistryLock was not the DNS blocker; bearer auth did not solve MCP. The wrong answer is worth keeping because without it the same investigation gets repeated.
One source of truth per fact
Link, do not restate. A number copied into two documents will disagree within a month.