Decision4

Agents now make decisions on your behalf: what to change, what to leave alone, what to trade off, what to promise. The pull request goes green. The work looks done. And when one of those decisions turns out to be wrong, it is still you who answers for it.

Most teams respond in one of two ways. They read every line, and drown. Or they sign at the end for decisions nobody actually made, and hope. Neither keeps you in a position to answer.

This book gives you a third way. It starts from one question, asked of every decision an agent touches:

If this turns out to be wrong, what does it take to put right?

The answer puts every decision into one of four classes, and the class decides what the agent may hand back to you:

• Undo — a revert puts it right. The agent hands you the result.
• Repair — real work, contained to your team. You get the result, plus what it decided and why.
• Migrate — coordinated change involving other people. You get at least two real options, and you choose.
• Answer — the wrong outcome has reached someone outside the team, and nothing unmakes it. You get evidence and challenge, never a recommendation. All you can do is answer for it, so that decision is yours.

Three rules hold it together. When unsure, take the higher class. Escalation needs no justification, and every de-escalation is recorded. Unattended runs close only Undo.

That is the whole framework, and it fits on one page. The rest of the book is how you use it: on Monday morning, in your pull requests and specs, in your agent's instructions and your CI pipeline, in your platform, and in the decisions leaders make about vendors, models and policy.

What you get

• The one page. The question, the four classes and the three rules, ready to print and pin up.
• A handoff contract to paste into your project's AGENTS.md, so your agents know what they owe you at each class.
• The boundary map. A way to write down where the ground changes in your systems, so the class comes from the map rather than from mood, with a schema you can validate.
• Recipes. Practical patterns for reviewing a pull request by decision rather than by file, designing a risky change down to a cheaper class, building an evidence pack with no recommendation, recording a downgrade, and running a nightly loop that knows where to stop.
• Classify-this exercises in every chapter, with an answer key that explains the reasoning, not just the class.
• A thirty-day pilot a team can run on its own: one team, one page, the class mix measured in week one, and the signals read in week four.

Who this book is for

The book is written first for the experienced engineer or tech lead who is already working with coding agents and wants to stay in command of what they ship. Everyone reads Part I, about ninety minutes of common ground. Then you follow your own route:

• Experienced engineers and tech leads: lowering the class by design, following one feature round the loop, and staying in a position to answer, not just in the room.
• Apprentices and early-career developers: moving fast where the map says Undo, and knowing exactly how to ask everywhere else.
• Habitat curators: keeping the map and the decision records honest as the system changes underneath them.
• Platform teams: shipping the class as a platform layer, with pipelines that route by class and credentials that set the ceiling.
• Leaders: better questions than "is there a human in the loop?", the same four classes for your own decisions, and what to tell a board or an auditor.

Contents

• Part I. The Question. One question, four classes, what the agent may hand you, who classifies under pressure, and where the class comes from.
• Part II. In the Work. Lowering the class, one feature round the loop, the experienced engineer and the apprentice.
• Part III. In the Habitat. The habitat curator, the platform team, workflows at higher levels of maturity, the factory spectrum, and putting the lights on where the decisions are.
• Part IV. In the Room. Who can answer, the leader's own decisions, signals to read rather than target, and how it scales and how it fails.
• Part V. Reference. The one page, the full contract, boundary maps, the answer key, sources, a glossary and the thirty-day pilot.

Between the Parts, short interludes and field notes tell the story the chapters then take apart, from a building restorer deciding which jobs can be undone to the night an agent destroyed a production database while its owner watched.

Free and open at its core

Decision4 itself is open. The canonical definition, the handoff contract and the boundary-map schema live at github.com/Habitat-Thinking/decision4, free to use and adapt under CC BY 4.0. This book is the practice: how to put the definition to work, chapter by chapter.

Part of the Habitat Thinking series

Decision4 is part of the Habitat Thinking series, alongside The Sovereign Engineer: AI Literacy for Software Professionals and The Sovereign Apprentice. It stands on its own: you need no other book in the series to read it, and every idea it borrows is explained where it is first used.