How-to: the manifesto, by phase
MANIFESTO.md states 25 domain-general tenets. These guides take those same tenets and project them onto the lifecycle of an issue. They follow it from the moment it arrives, through running in production, and on to the loop that turns what you learn into the next issue, and then to tearing the thing back out again. Each guide keeps the manifesto's form - a bold thesis, the failure it prevents, contrast bullets, the tension it creates, and a question to ask mid-work - and it cites the tenets it draws on by number. What you are after never really changes from one phase to the next, only the clothes it wears: minimise what a tired engineer must hold in their head to make a correct change, subject to a bounded blast radius for anything an attacker or an unlucky caller controls.
An issue moves through seven phases from arrival to running:
- Triage: decide whether the issue is real, how urgently it moves, and who owns it next, by the evidence and the blast radius rather than the reporter's volume.
- Planning: turn a fuzzy want into a bounded, owned, reversible plan an implementer can execute while ignorant of 99% of what you hold in your head.
- Implementing: build the change so the illegal state can't be built and the hostile input can't get in, and write the test that pins each move as you make it.
- Integrate: wire the change into the whole, where the failures live in the join and not in any one part. This is the lifecycle face of the companion
THE-SHAPE-OF-THE-WHOLE.md: map the substrate two services secretly share, give the invariant that spans them a home, compose the control loops on purpose, and probe the path end to end before a user does. - Reviewing: a reading order that confirms correctness was pushed into the structure, sorted by blast radius into must-fix and consider.
- Verify: prove the change actually resolves the issue and breaks nothing, in a running system, against the criteria triage and planning set.
- Ship & operate: release it so a mistake is cheap, and keep it healthy once it is live.
Two more phases close the arc:
- Retrospective: after an incident or a notable ship, turn what happened into a structural change (a test, an alert, a guardrail, a deleted state), blaming the system rather than the person, and feed the result back to Triage as new work. This is what makes the lifecycle a loop and not a line.
- Retire: the end of life. Remove a feature, service, flag, table, or dataset so nothing that still depends on it breaks and it stays gone. A removal is itself an issue that runs the whole pipeline; this guide is how to do the destructive part safely.
And one thing that is not a phase but a mode:
- Investigate: the mode you drop into when an unknown blocks you, in two faces, a forward spike to de-risk an approach you have not built and a backward debug to diagnose a defect that already exists. You enter it from inside planning, implementing, or operating, reduce the one unknown, and return.
The lifecycle is a loop and not a line. Operating throws up new issues, a retrospective takes the worst of them and turns it into structural change and then hands it back to triage, and at some point what you built gets retired. Writing the automated tests sits inside Implementing, where you pin each move with a test while the reasoning is still fresh in your head. Verify is a separate, later phase, and it proves the change resolves the issue in a running system, which is a different question from "are the units tested".
Sometimes a move in one guide pulls against a move in another. When that happens the way out is the manifesto's, not a slogan: who controls the input, and how wide is the blast radius. Wide and someone else's, you pay now. Contained and yours, you can defer it, but write down why.
The tenets these guides cite are not original to this repo. Each tenet in MANIFESTO.md carries an inline > *Lineage:* line crediting its sources, and the full bibliography lives in that file's Appendix: Sources & Influences.