Phase 2 · Design — how it works, worked, and referenced

Some decisions are cheap to change later. A few are not — and those few quietly decide whether the whole thing works.

Phase 2 is where you find the hard-to-undo decisions, make them on purpose, and write down why.

Every idea below is paired with the real thing — examples come from a fictional but fully worked engagement, Harbor Mutual, a regional insurer.

Why this phase exists at all

A handful of decisions are expensive to take back — so take them deliberately

By now the problem is fixed and the requirements are signed. The danger has shifted. It's no longer "are we building the right thing?" — it's "are we building it on a shape we can live with?" Most choices in a project can be reversed in an afternoon. A few cannot, because everything else gets built on top of them.

The idea

Phase 2 does one thing: it finds the small number of decisions that are hard to undo, makes each one in the open with real alternatives on the table, and records the reasoning so nobody has to guess later.

A shape chosen carelessly in week three becomes a rebuild in month four — because real code now sits on top of it. Spend a week choosing well now, and you save a quarter of rework.

At Harbor Mutual

Harbor's claims rebuild had to read policy data to decide coverage. The obvious source — the core system, PolicyOne — only updates once a night. Choose the wrong way to read it and you either re-add the very delay the project exists to remove, or you commit to mainframe work nobody could staff this year.

The decision that shaped the week

"Where does a coverage check get its answer — and how fast, given the once-a-night sync?"

Get that one wrong and the 11.4-days-to-5 goal is gone before a line ships.

Skip this phase and…

The hard-to-undo decisions still get made — just by accident, by whoever typed first, with no alternatives weighed and no record of why. You discover them when they break.

Go deeper — the full method

By now Phase 0 fixed the problem and constraints and Phase 1 produced a signed requirements baseline. Phase 2 decides the architecture — the small number of decisions that are expensive to undo, which is why every one of them gets a record and two signatures.

Phase 2 answers four questions, and nothing else:

What is the shape of the system? Components, boundaries, data flow, deployment view.
What are the contracts? API contracts, the data model, integration interfaces — with error semantics (how each operation behaves when things fail), not just the happy paths.
Which decisions are hard to undo, and what did we choose? Architecture decision records, each with real options and consequences, each signed.
How will the design be proven? The verification approach per NFR, and what the Phase 3 walking skeleton must demonstrate.

Production code, the full backlog of build specs, environment provisioning, and pixel-level UI design are out of scope — they belong to Phase 3 and the Build. Design spikes (small, throwaway code to test a risky assumption) are explicitly in scope; they are how design claims get verified against reality instead of against documents.

The rule that governs everything

Claude presents options; humans choose

This is the second-strictest version of the standard's spine, after Discovery's. The AI does the research, lays out the real choices with honest trade-offs, and drafts the records once a person has decided. But it never picks the architecture. A machine compares; a named human chooses.

The idea

For every decision that matters, the AI puts two or three genuine options on the table — with their costs, their risks, and what each one closes off later.

Claude researches the options, frames the trade-offs against this project's real constraints, and drafts the records after the choice is made.
People weigh the options, pick one, and put their name on it — on both sides of the engagement.

One option presented alone isn't a decision. It's a default wearing a decision's costume.

At Harbor Mutual

For the coverage-source decision, Claude laid out three real paths and what each cost:

Option, honestly costed

"Queue batch requests through PolicyOne — no new access, but answers arrive next business day. Re-adds the day the metric exists to remove."

What the humans chose — Rob (pod) + Wes (Harbor)

"Read the nightly snapshot replica directly. Milliseconds, fresh-as-of-yesterday, behind a service that owns the staleness rule."

The AI framed the choice; two named humans owned it.

Go deeper — the full method

This phase has the second-strictest human rule in the standard, after Phase 0's: Claude presents options; humans choose. Concretely:

Option research and framing. For each architecture-level decision, Claude researches and presents 2–3 genuine options with concrete trade-offs — costs, risks, what each forecloses — grounded in the actual requirements and constraints, not generic textbook comparisons. One option presented alone is not a decision; it is a default wearing a decision's costume.
ADR drafting, after the human picks. The record captures the context, the options actually considered, the choice, and the consequences — including the unpleasant ones.
Contract and model drafting. API contracts and the data model drafted from the requirements, carrying the Phase 1 error-behavior specs into concrete response codes, failure modes, and degradation behavior.
Consistency checking, both directions. Every top-tier requirement lands somewhere in the design; every major design element traces back to a requirement or constraint. Orphans in either direction get flagged ("this service exists but nothing requires it" is how accidental scope is born).
Threat-model preparation. Claude drafts the data-flow diagrams and candidate threat list the security session works from.

What Claude never does: choose an architecture, sign an ADR, accept a risk, or soften a trade-off to make an option look better.

How a decision becomes a record

Write down what you rejected, not just what you chose

A decision you can't reconstruct is a decision you'll relitigate. So each hard-to-undo choice gets a short record: what the situation was, which options were really considered, what was picked, and what that costs you — including the parts you won't enjoy.

The idea

The record's most valuable line is often the rejected option, with the reason beside it. That's what stops the same argument from coming back in month three — and it's proof the alternative was actually weighed, not waved past.

Two people sign each one: the team's design owner and the client's own engineer. A record with one signature is an engagement artifact. A record with both is a decision the client made with you, not one handed to them after.

At Harbor Mutual

The claim-store record could have just said "relational model, append-only log." Instead it recorded what it turned down:

The rejection, written down with its reason

"Full event sourcing — considered and rejected as unfunded gold-plating, and as an operability cost the team would carry at 2 a.m."

Nobody relitigates it later, and nobody wonders whether it was even considered. Every record that week carried both Rob's name and Wes's.

The failure mode to watch

The single-option record: one approach presented, everyone nods, and the document gets written around a reflex. The alternatives are exactly where the thinking lives — skip them and the record proves nothing.

Go deeper — the full method

An ADR is an architecture decision record: one hard-to-undo choice written down — the options considered, the decision, and its consequences — signed by a named human on each side (a signature is the person's name and date recorded in the ADR file itself). Claude drafts each ADR after the human picks, against the ADR template, capturing the context, the 2–3 options genuinely considered, the choice, and the consequences including the unpleasant ones.

The Setup Owner edits and signs; the client counterpart co-signs. An unsigned ADR is a conversation, not a decision. Decisions not worth a room are settled asynchronously between the Setup Owner and the counterpart, and still get an ADR if they're hard to undo.

The failure mode is the single-option decision: Claude (or the architect) presents one approach, everyone nods, and an ADR gets written around a default. The 2–3-options rule exists because the alternatives are where the thinking happens; an ADR with one option is documentation of a reflex. The absent counterpart is the other risk — ADRs signed by one side are an engagement artifact, not a client decision; surface it at steering while it costs days, not at close when it costs the handoff.

Don't bet the design on a guess

Test the risky assumption against the real thing — with throwaway code

A design quietly bets on things being true: that an old system answers fast enough, that an integration behaves like its documentation claims. Bet wrong and you find out in build week three, when it's expensive. So you check first — cheaply.

The idea

For each risky assumption, someone writes a small, throwaway piece of code that pokes the real system for a few hours. The point isn't the code — it gets deleted. The point is the finding, which the design then gets built around.

The most valuable spikes falsify something. A spike that proves a favored option won't work just did its job for the price of an afternoon.

At Harbor Mutual

Jonah spiked the snapshot replica. It answered in 180 milliseconds — easily fast enough. But the throwaway code found something no document mentioned:

What the spike found that the docs didn't

"The replica is unavailable during its 02:00–04:30 nightly refresh window."

Designed around the truth, not surprised by it

"During refresh, the service shows 'pending verification' and never blocks intake — written into the contract, not discovered as a 2 a.m. incident."

One hour of code nobody kept saved a midnight outage in month four.

Go deeper — the full method

A spike is small throwaway code written to test a risky assumption against reality before the design depends on it; the findings are kept, the code is deleted. Orchestrators run the design spikes — small, throwaway, time-boxed to hours: does the integration respond the way its documentation claims, does the candidate approach survive the surge profile, does the access path actually open.

Anything the design would bet on that has only been verified on paper gets a spike. The spike findings become design inputs: a refresh-window outage flows straight into a contract's degradation behavior instead of surfacing as a 2 a.m. incident in month four.

Faith-based integration

The design bets on an interface nobody called. The spike-before-you-depend rule is cheap insurance; the alternative is discovering the truth in Build week 3, which is how the last vendor died. If a spike falsifies a favored option — good, that's the spike doing its job. Re-run the option session with the surviving candidates rather than bending the finding.

Define the edges — including how they break

A contract that only describes success is half a contract

Every part of the system has a boundary where it meets the others. The boundary has to say not just what happens when things go right, but exactly what happens when they go wrong — because that's the part the next person will need and won't be able to guess.

The idea

For each operation, the design pins down the success behavior and the failure behavior: what callers see when a dependency is down, when data is stale, when the system is overwhelmed. The error behavior agreed earlier in requirements flows straight into these concrete responses.

Leave the failure paths to "the implementer's imagination" and you've thrown away the careful thinking that already happened — and guaranteed each developer invents a different answer.

At Harbor Mutual

The coverage-check contract spells out every failure, not just the happy answer:

A failure path, made explicit

"Policy not found → return 'needs-review' with a reason code — never a silent 'verified'; raise the queue flag the same business day."

And a degradation path the design review added

"Under a surge, the portal never rejects a claim: accept it, queue deeper, show the degraded-confirmation message the product owner approved."

Go deeper — the full method

A contract is exactly how a piece of the system behaves at its boundary, failures included — what callers may rely on. API contracts get completed for every operation: the request/response shapes, the error semantics carried down from the Phase 1 error-behavior specs, and the degradation behavior under each dependency failure. A contract that only describes success is half a contract.

Happy-path contracts — success specified, failure left to the implementer's imagination — are a named failure mode. The Phase 1 error-behavior specs exist precisely to flow into contract error semantics; if they don't, that work evaporates here. The error spec agreed in requirements becomes the verification endpoint's response codes, staleness header, and refresh-window degradation behavior.

The constraints don't bend

Design with the hard limit, not around it

Some constraints are fixed: a system that only syncs at night, a rule that the business must keep a door open for a future product, a regulatory clock. The tempting move is to wish them away — "we'll add a real-time feed later." That's how projects quietly break their own promises.

The idea

What Discovery fixed as non-negotiable, the design honors — or it re-opens the conversation out loud, never silently. The constraint is an input to the shape, not an obstacle to route around.

The forward-compatibility rule cuts both ways: don't close off the future the client paid to keep open — and don't furnish a room for a future nobody funded. "Must not preclude" means the door stays open, not that you build behind it now.

At Harbor Mutual

The constitution said the design must not preclude Harbor's future auto-insurance business — but v1 ships property claims only. Checking the draft model against that rule forced exactly one change:

Claim type moved from a fixed code-level list to a reference table with an extensible coverage schema.
Adding the auto book later becomes a data change, not a schema rebuild — door open, room unfurnished.

They honored the once-a-night sync the same way: the replica read is the design, not a workaround pasted over it.

Go deeper — the full method

The constitution is the short Phase 0 document fixing what must always be true (and what must never happen) for this engagement; later phases may not silently contradict it. On day 3 the forward-compatibility check the constitution demanded runs against the draft model: does this design preclude the futures the client paid to keep open? Verified now, gated again at every design review — the Setup Owner walks each constitution-protected future against the draft model and records the verdict, and what made it true, alongside the model.

Two named failure modes bracket this. Designing around the constraint instead of with it: the hard boundary (a batch window, a regulated data path) gets wished away with "and then we'll add a real-time feed later." Phase 0 resolved what's fixed; the design honors it or the engagement re-opens the conversation explicitly — never silently. Foreclosing the protected future — or gold-plating for an unfunded one: the forward-compatibility check cuts both ways. Don't preclude what the constitution protects, and don't build abstractions for futures nobody paid for. "Must not preclude" means the door stays open, not that the room gets furnished.

Build the smallest thing — the right way

Ship only what's funded, but leave the right seams

Restraint and foresight sound opposed, but they're the same discipline pointed in two directions: don't build the future, but don't make the future a rebuild either. The skill is knowing which is which.

The idea

The data model serves every top-priority requirement and nothing more — no service exists that no requirement asked for. But where the design knows a future is coming, it leaves a clean seam rather than a wall.

A good seam is invisible until you need it, costs nothing today, and turns tomorrow's "rewrite" into tomorrow's "configure." A bad one is a half-built feature nobody paid for.

At Harbor Mutual

The model carried its audit trail as structure, not as an afterthought, and its merge rules as first-class history:

From the data model summary

"Append-only event log — every state change with actor and timestamp; the duplicate-merge is an event pair, so history survives the merge."

And the coverage service got built as the seam for real-time: if Harbor funds it later, the contract doesn't change — only the source behind it does. That's a door left open, costing nothing now.

The check that keeps it honest

The design is traced both ways: every top requirement lands somewhere, and every component traces back to a requirement. A part that nothing asks for is how accidental scope is born — so it gets cut.

Go deeper — the full method

The data model and component design get drafted starting where the handoff said to start — the element where the most constraints converge. The model serves every top-tier requirement; the convergence constraints (audit, merge rules) are structural, not bolted on. A walking skeleton — the thinnest end-to-end slice of the system, built first to prove the architecture works in practice, not on paper — gets named for Phase 3 to make real.

Claude runs the consistency check in both directions: every top-tier requirement lands somewhere in the design, and every major design element traces back to a requirement or constraint. Orphans in either direction get flagged — "this service exists but nothing requires it" is how accidental scope is born.

The orphan service

A component creeps in that no requirement asked for. Trace the design both directions and cut what nothing needs — accidental scope dies in design, not build.

Now watch the whole thing happen

The week, end to end

You've got the ideas; here's the actual rhythm at Harbor. The week's spine is simple — options early, decisions in the middle, contracts and proving at the end — with the riskiest bets tested against reality on day two before anything depends on them. Step through it.

Day 1 · drivers & options

Find the few requirements that actually shape the architecture

Most requirements don't drive the design. The day's craft is finding the five-to-eight that do — the nightly batch window, the storm surge, the auto-proof rule, the regulatory clock. The two open questions carried from Phase 1 come due, because their answers are design inputs. Claude lays out two-to-three options per major decision; the design owner kills the strawmen and books the option session.

Day 2 · spikes & the option session

Test the risky bets, then let humans choose

Orchestrators run the throwaway spikes — does the replica answer fast, does the email parser reach useful accuracy. Then the option session: the design owner and Harbor's lead engineer work through Claude's framings with the spike results in hand, and choose. By end of day the architecture direction is set and the list of records to write is known.

Day 3 · decisions become records

Sign the decisions; draft the model

Claude drafts the records from yesterday's choices; the design owner edits and signs, the client's engineer co-signs. An unsigned record is just a conversation. The claim data model gets drafted — starting where the most constraints converge — and the forward-compatibility check forces its one structural change.

Day 4 · contracts, threats, proving

Pin the edges, walk the attack surface, plan the proof

The API contracts get completed — every operation, every failure path, every degradation behavior. The security session walks the data flows and assigns each threat: mitigate it in the design now, or guard it with a build-time gate later. The quality engineer writes how every quality target will be proven, and defines the thin end-to-end slice Phase 3 must make real.

Day 5 · review, gate, handoff

Fresh eyes attack it, then it ships forward

A reviewer that didn't draft the design challenges it from four angles — architecture, product, quality, security. Findings get fixed or accepted by name; the consistency check runs both directions and an orphaned service gets cut. The gate runs, the sponsor gets the narrative (not the diagrams), the signatures land — and the engagement advances. That sign-off is billing milestone three.

1 / 5

Go deeper — the full method

The default calendar is 5 business days, stretching to 8–10 when the integration estate is large (many external systems to connect to) or the client's review boards add latency. The week's spine: options early, decisions in the middle, contracts and verification at the end. The Setup Owner's enablement work from Phases 0–1 continues in parallel and is why Phase 3 can start immediately after.

Day 1 — design drivers and the option set. The pod extracts the design drivers from the Phase 1 handoff — the 5–8 requirements and constraints that actually shape the architecture. The open questions the handoff carried come due; their answers are usually design inputs. Claude presents the option sets; the Setup Owner kills the strawmen and schedules the option session. The riskiest assumptions get named and spikes get assigned.
Day 2 — spikes and the option session. Orchestrators run the design spikes (throwaway, hours-boxed). The option session (90–120 min): Setup Owner and the client's lead engineer work through Claude's framings with spike results in hand, and the humans choose. Product-facing trade-offs split off to the PO with the usual clock. By end of day the architecture direction is chosen and the ADR list is known.
Day 3 — decisions become records; the model takes shape. Claude drafts the ADRs from the day-2 choices; the Setup Owner edits and signs; the client counterpart co-signs. The data model and component design get drafted, and the forward-compatibility check runs against the draft model.
Day 4 — contracts, threat review, and the proving plan. API contracts completed with error semantics and degradation behavior. The threat review session with client security assigns mitigations — some design changes, some build-time security gates feeding the risk-tier map. The Quality Engineer completes the proving plan and the walking-skeleton definition.
Day 5 — review, gate, and the handoff. The design review: fresh eyes challenge it from four angles. The consistency check runs both directions; orphans resolved. The automated gate check runs; the Phase 3 handoff is drafted. Steering: the sponsor gets the design narrative, not the diagrams. Sign-offs recorded; the engagement advances to Foundation.

When the week stretches: a formal architecture review board gets scheduled for day 4–5 from day 1, and if its cadence can't fit, the phase stretches and gate-based billing makes the latency visible rather than absorbed. A spike that falsifies a favored option is the spike doing its job — re-run the option session with the survivors. A counterpart who keeps missing sessions gets escalated at steering; co-signature is the handoff being built early.

How it goes wrong

The failure modes, and the defense against each

Every one of these has killed a real project. Knowing them by name is half the defense — and Harbor's structure caught two of them in the act.

The trap	What it looks like	The defense	At Harbor
The single-option decision	One approach presented, everyone nods, a record written around a reflex	Two or three real options, or it's not a decision. The alternatives are where the thinking is.	Three options costed per decision
Resume-driven architecture	The interesting technology beats the boring one that fits	The client runs it at 2 a.m., not you. Their operating model is the tiebreaker.	Serverless rejected — foreign to Harbor's ops
Designing around the constraint	"We'll add the real-time feed later" wishes the batch window away	Honor the fixed limit, or re-open it out loud — never silently.	The nightly replica is the design
Faith-based integration	The design bets on an interface nobody actually called	Spike it against the live system before you depend on it.	Caught — the spike found the refresh window
Happy-path contracts	Success is specified; failure is left to imagination	Carry the error specs down; failure behavior is half the contract.	Every contract row is a failure case
The orphan service	A component creeps in that no requirement asked for	Trace the design both directions; cut what nothing needs.	Caught — a service cut on day 5

Go deeper — the full method

The single-option decision. Claude (or the architect) presents one approach, everyone nods, and an ADR gets written around a default. The 2–3-options rule exists because the alternatives are where the thinking happens; an ADR with one option is documentation of a reflex.
Resume-driven architecture. The interesting technology wins over the boring one that fits. The constitution's principles and the client's operational reality are the tiebreaker — they will run this system at 2 a.m., not us.
Designing around the constraint instead of with it. The hard boundary gets wished away with "and then we'll add a real-time feed later." Phase 0 resolved what's fixed; the design honors it or the engagement re-opens the conversation explicitly — never silently.
Faith-based integration. The design bets on an interface nobody called. The spike-before-you-depend rule is cheap insurance; the alternative is discovering the truth in Build week 3, which is how the last vendor died.
The hundred-page design document. Nobody loads it, so nobody follows it. The design document is navigation — the decisions live in ADRs, the details live in contracts, and all three stay short enough to stay true.
Happy-path contracts. Contracts that specify success and leave failure to the implementer's imagination. The Phase 1 error-behavior specs exist precisely to flow into contract error semantics — if they don't, that work evaporates here.
Foreclosing the protected future — or gold-plating for an unfunded one. The forward-compatibility check cuts both ways: don't preclude what the constitution protects, and don't build abstractions for futures nobody paid for. "Must not preclude" means the door stays open, not that the room gets furnished.
The absent counterpart. ADRs signed by one side are an engagement artifact, not a client decision. If the counterpart can't engage now, the handoff is already failing — surface it at steering while it costs days, not at close when it costs the harness.

When Phase 2 is done

You have a shape you can build on — and a record of why it's that shape

Design doesn't end with code. It ends with the hard-to-undo decisions made and signed by both sides, the integrations proven against reality, the contracts honest about failure, and a thin end-to-end slice named for the next phase to make real. That's a foundation you can pour concrete on. Where to go next:

Phase 3 →Foundation — the harness gets installed, the rails go live, and the walking skeleton becomes running code. The Reference view →The precise mechanics of Phase 2 — roles, calendar, artifacts, the exact gate.

Before anything is written, five files arrive and two questions are still open

What Phase 2 received

Harbor Mutual — a fictional regional insurer — hired a five-person pod to rebuild how property-insurance claims get reported and decided. A claim takes a median of 11.4 days from FNOL (first notice of loss) to a coverage decision; the target is 5 days or less. Phase 1 closed Friday 2026-03-20. Design does not start from a blank page — it starts from these files, on disk, in the client's own repository.

Inherited from Phase 1 — read by synthesize_spec.py into one design brief phase2-handoff.md requirements.md non-functional-requirements.md epics.md constraints.md

The four design drivers, and the two unknowns

Most of a requirements baseline doesn't shape architecture. Four things here do — and two of them are still questions, which is why they're due this week.

PolicyOne & the replica. Policy data lives in an aging core that syncs only once a night; Phase 1 found a read-only nightly snapshot replica, queryable in milliseconds. Whether security allows reading it is open question Q-15.
Storm season. Catastrophe events spike claim volume ~10x for about a week (NFR-02). The exact surge profile is Q-16.
The fast path. 61% of claims are simple and get a recommend-then-one-click-confirm decision (D-09).
Auto-proof. The data design must not preclude Harbor's auto-insurance business later (C-03); v1 ships property only.

Where the week is headed

Those four drivers converge on one place — the claim data model — which is why Phase 1's handoff recommended starting design there. Everything decided this week is either a consequence of them or a bet being tested against them.

Wes Carter is the one to watch. Harbor's lead engineer co-signs every decision record next to Rob's name. At close, the harness hands to someone who chose this architecture — not someone it happened to.

Carried in from Phase 1, still unanswered on Monday

Q-15 — may we read the replica directly? (Dan) · Q-16 — what does the surge actually look like? (Priti)

Our pod

Maya ChenPod Lead

Rob FeldSetup Owner — the design authority; signs every ADR

Jonah KimOrchestrator / Checker — runs the replica spike

Sara WhitfieldOrchestrator / Checker — runs the email-extraction spike

Nadia BrooksQuality Engineer — owns the proving plan

Harbor Mutual

Karen VossVP Claims Operations — sponsor; approves the advance

Wes CarterLead engineer — co-signs every ADR; becomes Setup Owner at close

Luis OrtegaProduct owner — decides product trade-offs on a 2-day clock

Dan KowalskiIT security — answers Q-15; runs the threat review

Priti ShahData & reporting — answers Q-16

The ID codes, decoded

Every artifact in this engagement carries a stable identifier, so a decision made in week two can still be traced in month nine. You'll see these throughout:

Prefix	Means	Born in	Example here
`DOC-NNN`	A client document taken in at intake	Phase 0	The 2023 API inventory that turned out to be wrong
`C-NN`	A constraint — a hard limit the design must honor	Phase 0	C-02 nightly sync · C-03 auto-proof
`D-NN`	A decision the client's product owner owes us	Phase 0/1	D-07 merge rule · D-09 fast path · D-12 retention
`Q-NN`	An open question with an owner and a due date	any	Q-15 replica access · Q-16 surge profile
`REQ-NNN`	A functional requirement	Phase 1	REQ-014 same-business-day coverage status
`NFR-NN`	A non-functional requirement — a quality target	Phase 1	NFR-02 the 10x surge
`AQ-NN`	An architectural question Design must answer	Phase 1 handoff	The four that become ADR-001–004
`ADR-NNN`	An architecture decision record — a signed choice	Phase 2	ADR-001 coverage verification source

The plugin's Phase 2 begins by reading every AQ-NN out of phase2-handoff.md. An architectural question with no ADR at the end of the week is a gate failure — that's the thread tying Phase 1's homework to Phase 2's output.

The machine's ten steps, the humans' five days, braided

The procedure, step by step

Phase 2 is ten numbered steps in claude-code-sdlc and five working days in this standard. They are the same week seen twice. Below, they're braided: what the tool runs, what the humans do that the tool cannot, and the file each step leaves behind. Step through it.

Legend a command does it — and writes the file a person does it — and it is recorded a person does it — and nothing records it

Day 1 — Mon 3/23 · plugin Step 0 opens

Pull the architectural questions; put real options on the table

Claude reads phase2-handoff.md and extracts every AQ-NN Phase 1 left for Design. For each one it presents two to three concrete options with honest costs. This is a blocking human gate in the plugin: collect human decisions for all AQs before writing any artifact. Claude encodes decisions; it does not invent them.

Tooling /sdlc-next → Step 0 HITL gate human decision

The pod also brings its own day-1 craft, which no command performs: reading the baseline for the five-to-eight requirements that actually shape architecture, and killing the strawman options before a human ever sees them. Two Phase 1 questions come due today, because their answers are design inputs.

Out AQ decisions — made by humans; recorded as ADRs on day 3

At Harbor

Drivers extracted: C-02 batch window, NFR-02 surge, C-03 auto-proof, C-04 regulatory clock, C-05 PII-in-tenant, D-07 merge rule. Both open questions land. Q-15 (Dan): replica read approved under controls. Q-16 (Priti): the surge is real — peak 1,710 claims on day 2, nine elevated days. Claude presents three options for each of four decisions; Rob kills one strawman per set and books the option session for tomorrow.

Day 2 — Tue 3/24 · the option session · no command runs

Test the risky bets against the real thing, then let humans choose

Before anyone commits to an option, the assumptions underneath it get tested. Orchestrators run spikes: throwaway code, hours-boxed, on branches that get deleted, pointed at the client's live systems rather than the client's documentation. Then the option session — 90 to 120 minutes, the Setup Owner and the client's engineer, spike results in hand — and they choose. This closes the plugin's Step 0 gate.

Tooling none — exploratory coding on a throwaway branch, then humans in a room

Out spike-findings.md — the method requires it; no command writes it four decisions, made and owned

The gap you should know about

Phase 2's exit gate says "every external integration the design depends on was spiked against the live system." The word "spike" appears in no file in claude-code-sdlc. Nothing prompts you to run one, and nothing checks that you did. This is human work that currently leaves no receipt — and it is exactly the work that saved Harbor a 2 a.m. incident in month four.

At Harbor

Jonah's spike: the replica answers in 180ms at the 95th percentile — and is unavailable 02:00–04:30 nightly during its refresh. No document mentioned that. Sara's spike: LLM email-field extraction hits 88% on 50 redacted samples — promising, below target, and exactly the number ADR-004's confidence-threshold design needs. In the option session Rob and Wes choose all four decisions. One product-facing trade-off — what the portal shows users during surge degradation — splits off to Luis on the 2-business-day clock.

Day 3 — Wed 3/25 · plugin Steps 1–6

The machine runs; decisions become signed records

With every architectural question answered, the tool is finally allowed to write. Six steps fire in sequence: synthesize the design brief, run the planner, map its output into the engagement's artifact directory, write the ADRs from yesterday's human decisions, fill the gaps in the generated skeletons, and define the data model.

Tooling synthesize_spec.py → planning/spec.md /deep-plan → planning/claude-plan.md map_deep_plan_artifacts.py /sdlc-coach → ADRs

Out — all under .sdlc/artifacts/02-design/ design-doc.md api-contracts.md adrs/ADR-001…004.md adr-registry.md phase3-handoff.md research-notes.md integration-notes.md deep-plan-checkpoint.yaml

An unsigned record is just a conversation. Claude drafts each ADR against the template; the Setup Owner edits; the Setup Owner and the client's counterpart both sign. Two names, or it isn't a decision.

At Harbor

Four ADRs drafted, edited by Rob, signed by Rob and Wes, dated 2026-03-25. The claim data model gets drafted where the constraints converge. Running the forward-compatibility check against C-03 (auto-proof) forces exactly one structural change: claim type moves from a code-level enum to a reference table with an extensible coverage schema. Adding the auto book later becomes a data change, not a schema migration. Door open; room unfurnished.

Day 4 — Thu 3/26 · plugin Step 7 · plus the threat review

Pin the edges, walk the attack surface, plan the proof

The API contracts get completed — not just what success looks like, but every failure path and every degradation behavior, flowed down from the Phase 1 error specs. The tool renders the architecture as five diagrams, one of which is a trust-boundary diagram. Then the humans attack it: a security session walks each data flow and assigns every threat — mitigate it in the design now, or guard it with a build-time gate later.

Tooling /sdlc-coach → contracts /visual-explainer → .sdlc/reports/architecture-diagrams.html threat review — a human session; Claude drafts the data flows and the candidate list

Out architecture-diagrams.html threat-model.md + mitigation map nfr-proving-plan.md walking-skeleton.md

At Harbor

REQ-014's error spec becomes contract behavior: policy not found returns needs-review with a reason code, never a silent "verified"; the replica's refresh window returns pending-verification and intake never blocks. The threat review with Dan finds 9 threats: 7 mitigated in the design, 2 handed forward as build-time security gates — malware scanning on document upload, and a PII template-review gate on acknowledgment letters, because that data leaves the system on paper. Nadia writes how each NFR will be proven and where its number will be read. Steering with Karen surfaces document retention, which becomes D-12.

Day 5 — Fri 3/27 · plugin Steps 8–9 · the gate

Fresh eyes attack it, the gate reports, a human decides

A reviewer that did not draft the design challenges it from four angles. The consistency check runs both directions — every top-tier requirement lands in a design element, every design element traces back to a requirement. Then the gate runs, generates a report for the stakeholders, and stops. advance_phase.py will not move the engagement forward without --confirmed: a named human's sign-off.

Tooling /sdlc-review --all /sdlc-gate → check_gates.py /sdlc-phase-report → generate_phase_report.py /sdlc-next → advance_phase.py --confirmed

Out .sdlc/reports/phase02-report.html consistency-check.md the sponsor's signature — billing milestone 3

What the gate actually checks

check_gates.py verifies that five files exist, are non-empty, and contain no placeholder text. It never reads the ten-bullet exit-gate checklist this standard specifies — that list lives in phase-registry.yaml, and no code opens it. The human is stopped at the gate and asked to sign; the checklist they should be signing against is never put in front of them. The human gate is real. What it asks is not.

At Harbor

Three review findings survive Rob's triage. HIGH: no back-pressure behavior defined for surge — the contract gains an explicit degraded-acceptance mode. MEDIUM: the staleness flag isn't wired to fast-path escalation — fixed, traced to REQ-019. MEDIUM: a notification-preferences service that no requirement asked for had crept into the component diagram — cut. Accidental scope dies in design, not in build. Consistency check clean after the cut. Rob and Wes walk the ADRs, Luis confirms the product trade-offs, Karen approves.

1 / 5

Everything that exists on Friday and didn't on Monday

What Phase 2 produced

The design phase's whole output, named. Blue rows are written by a command and checked by the gate. Amber rows are the method's human work — required by this standard, produced by no tool, and today leaving no file behind. Those are the rows to argue about.

Artifact	What it actually is	Written by	Signed by	Lives at	Feeds
design-doc.md	The shape of the system: components, boundaries, data flow, deployment view. Navigation for the ADRs — short enough to be read, not a novel	`/deep-plan` drafts; Setup Owner enriches	Setup Owner	`.sdlc/artifacts/02-design/`	Phase 3 skeleton
adrs/ADR-NNN.md	One decision each: context, 2–3 options genuinely considered, the choice, the consequences including the unpleasant ones	Claude drafts from the Step 0 human decisions	Setup Owner + client counterpart — both	`.sdlc/artifacts/02-design/adrs/`	Phase 3 build; every later argument
adr-registry.md	The index of every ADR with its status — active, superseded, proposed	`/sdlc-coach`	Setup Owner	`.sdlc/artifacts/02-design/`	Close — the decision history Harbor inherits
api-contracts.md	Every operation: request and response shapes, auth, error semantics, degradation behavior per dependency failure. A contract that only describes success is half a contract	`/deep-plan` drafts; Setup Owner completes	Setup Owner	`.sdlc/artifacts/02-design/`	Phase 3 specs
phase3-handoff.md	Decisions, contracts, section breakdown, implementation order, build risks, open questions under their original IDs	`map_deep_plan_artifacts.py` drafts; Pod Lead completes	Pod Lead	`.sdlc/artifacts/02-design/`	Phase 3, directly
architecture-diagrams.html	Five rendered diagrams — layers, request flow, data flow, section dependencies, and the trust boundary	`/visual-explainer`	—	`.sdlc/reports/`	Stakeholder review; the threat session
research-notes.md integration-notes.md deep-plan-checkpoint.yaml	The planner's working memory: what it researched, what it learned about the client's systems, and enough session state for Phase 3 to resume	`/deep-plan`	—	`.sdlc/artifacts/02-design/`	Phase 3 resumption
phase02-report.html	The gate result and artifact inventory, self-contained. This is the document a sponsor actually reads before signing	`generate_phase_report.py`	—	`.sdlc/reports/`	The manual sign-off gate
spike findings	Each risky assumption confirmed or falsified against the live system, with evidence. The spike code is deleted; the finding is not	A human, on a throwaway branch	Setup Owner	no path — nothing writes it	The ADRs it should have informed
threat model + mitigation map	Data flows reviewed; each threat either mitigated in the design or assigned as a build-time security gate	Setup Owner + client security	Both	no path — nothing writes it	Phase 3's risk-tier map
NFR proving plan	Per quality target: the verification method, and the named place its number will be read	Quality Engineer	QE	no path — nothing writes it	Phase 9 monitoring
walking-skeleton definition	The thin end-to-end slice Phase 3 must ship — named, bounded, and sufficient to exercise every ADR's chosen mechanism at least once	Setup Owner + QE	Setup Owner	no path — nothing writes it	Phase 3, day 6
consistency check record	Requirements traced against design in both directions; orphans resolved or removed	Pod Lead	Pod Lead	no path — nothing writes it	The exit gate
data model	Serves every top-tier requirement; passes the forward-compatibility check; convergence constraints are structural, not bolted on	Plugin Step 6 — but into `design-doc.md`, not its own file	Setup Owner	folded into design-doc.md	Phase 3 schema

Read the amber rows again

Six of the fourteen things Phase 2 is supposed to produce have nowhere to live. The threat review happens, and its output survives as a memory and a couple of GitHub labels. The spike that found Harbor's 02:00–04:30 refresh window leaves no artifact at all — the finding reaches the ADR only because Jonah was in the room on Wednesday. Human work is not the problem. Human work without a receipt is.

Deliberately not produced in Phase 2: production code, the spec backlog (Phase 3 and triage own that), provisioned environments (Phase 3), UI visual design beyond what the product trade-offs required, and estimates beyond the SOW's phase figures.

Four signed ADRs — one reproduced whole

Write down what you rejected, not just what you chose

Four architectural questions came in from Phase 1; four ADRs go out. Claude drafted them against the template; Rob edited; Rob and Wes both signed, dated 2026-03-25. Each records the rejected options with their reasons — the part that stops the argument coming back in month three.

ID	Decision	Chosen	Rejected (and why)
ADR-001	Coverage verification source	Read the PolicyOne nightly snapshot replica directly (per Q-15 controls)	Batch request queue (adds a day back — defeats the metric); building a real-time PolicyOne API (cost and risk unfunded for v1; deferred to the auto phase)
ADR-002	Claim store shape	Relational model + append-only event log; auto-proof via line-of-business reference table and extensible coverage schema	Full event sourcing (unfunded gold-plating; team operability cost); document store (weak fit for the merge and audit rules)
ADR-003	Surge handling	Buffered ingestion queue + autoscaling, load-tested at the Q-16 surge profile	Permanent overprovisioning (pays for the storm all year); serverless rearchitecture (foreign to Harbor's operating model — they run this at 2 a.m.)
ADR-004	Email FNOL extraction	LLM extraction with per-field confidence thresholds; below-threshold fields route to the human triage view (REQ-009)	Deterministic template parser (insurer emails are too varied — Sara's spike); permanent manual triage (the no-SLA inbox is the problem being solved)

ADR-001 in full

Coverage verification reads the nightly snapshot replica. Status: accepted · Signed: Rob Feld (pod), Wes Carter (Harbor) · 2026-03-25.

Context. REQ-014 promises same-business-day coverage status. PolicyOne syncs downstream nightly (C-02, CON-01); the 2023 API inventory listed only batch interfaces, but the Phase 1 spike (Jonah, 3/19) found a read-only nightly snapshot replica, and security approved direct read access under controls (Q-15).

Options considered.

Read the snapshot replica directly. Fresh-as-of-yesterday data in milliseconds. Requires the Q-15 controls and a staleness contract.
Queue batch requests through the existing PolicyOne interface. No new access path, but answers arrive next business day — re-adds the day the metric exists to remove.
Build a real-time read API on PolicyOne. True real-time, but mainframe-side work Harbor can't staff this year; CON-01 already deferred real-time to the auto phase.

Decision. Option 1. The replica read, behind a verification service that owns the staleness contract.

Consequences.

Every coverage answer carries an as-of timestamp; data older than 36 hours triggers the escalation path (REQ-014's error spec).
The replica is unavailable 02:00–04:30 during refresh (Jonah's spike, 3/24): the service degrades to "pending verification" and intake is never blocked.
Access runs under the Q-15 controls: read-only service account, private endpoint, audited.
The unpleasant one: v1's accuracy ceiling is "as of last night." If Harbor later funds real-time, this service is the seam where it lands — the contract doesn't change, the source behind it does.

Wes's signature is the transfer event in miniature. Every ADR carries Harbor's own engineer's name next to Rob's — at close, the harness hands to someone who chose this architecture, not someone it happened to.

An exhibit from api-contracts.md — the coverage-verification endpoint

A contract that only describes success is half a contract

REQ-014's error specification flowed straight down into contract behavior: response codes, the staleness header, and what the endpoint does when its dependency is simply gone. Every row below is a failure case — the part the next person cannot guess and will otherwise invent.

Condition	Response
Policy found, data fresh	Coverage status + `as-of` timestamp
Policy not found	`needs-review` with reason code — never a silent "verified"; queue flag raised same business day
Replica in refresh window (02:00–04:30) or unreachable	`pending-verification`; queue entry shows the degradation; intake never blocks
Snapshot older than 36h	Status carries a staleness warning; written-acknowledgment-state claims escalate instead of auto-proceeding
Surge back-pressure (added by the day-5 review)	Portal acceptance never rejects a FNOL: accept, queue deeper, show the degraded-confirmation message Luis approved

The surge back-pressure row was a day-5 review finding (HIGH): no back-pressure behavior was defined for surge, so the contract gained an explicit degraded-acceptance mode.

An exhibit from design-doc.md — where the constraints converge

Ship only what's funded, but leave the right seams

The model was drafted starting exactly where Phase 1's handoff pointed: the claim, its event log, its channel sources, with D-07's merge rules structural rather than bolted on. The coverage service is the seam where real-time can land later without the contract changing.

The data model (summary)

Claim — the aggregate; carries line-of-business as a reference table (the auto-proof change), an extensible coverage-schema attribute, and a 7-year retention attribute (D-12).
Claim event log — append-only; every state change with actor and timestamp. NFR-07's audit requirement is structural; the duplicate-merge (D-07) is an event pair, so history survives the merge.
FNOL source — one claim, many sources; each keeps its channel, raw payload reference, and received-at.
Acknowledgment record — dispatch attempts, form (email/postal), bounce chain (REQ-022), and the regulatory-clock fields the escalation rules read.

The one change the constitution forced

Phase 0's constitution said the design must not preclude Harbor's future auto-insurance business (C-03) — while v1 ships property only. Walking that protected future against the draft model forced exactly one structural change:

Claim type moved from a code-level enum to a reference table with an extensible coverage schema.
Adding the auto book later becomes a data change, not a schema migration — door open, room unfurnished.

"Must not preclude" means the door stays open, not that the room gets furnished. The nightly sync (C-02) was honored the same way: the replica read is the design, not a workaround pasted over it.

D-12 (document retention) surfaced at Thursday's steering; Luis answered next morning — seven years, per the stricter state's regulation — and it landed in the model as a retention attribute, not a TODO.

The check that keeps it honest

On day 5 the consistency check runs both directions: every top-tier requirement must land in a design element, and every remaining element must trace back to a requirement. It found a notification-preferences service that no requirement had asked for, sitting in the component diagram. Cut. Accidental scope dies in design, not in build.

The handoff — and the two questions that travel with it

What Phase 3 receives

A phase ends by handing the next one a package, not a feeling. Everything below crosses the boundary into Foundation: the signed decisions, the slice that proves them, the security gates to wire, and the questions that are still open — carried forward under their original IDs, never silently dropped.

Crosses into Phase 3 phase3-handoff.md design-doc.md api-contracts.md adrs/ + adr-registry.md deep-plan-checkpoint.yaml walking-skeleton definition threat mitigation map → risk-tier map NFR proving plan

Threat review outcomes

Day 4, with Dan. Claude drafted the data flows and candidate list; the session decided. Two of the nine become Phase 3's build-time security gates — this is the one place a Phase 2 human session reaches directly into the factory Phase 3 builds.

9 threats identified; 7 mitigated in the design (private endpoint for the replica, per-channel input validation at the adapters, audit log integrity, least-privilege service accounts among them).
2 assigned as build-time security gates, feeding the Build loop's risk-tier map: document upload path → malware scanning, HIGH tier, security workflow on every touching PR; acknowledgment letter templates → PII template-review gate (data leaves the system on paper).

The proving plan and the walking skeleton

Nadia's, day 4.

NFR	Proven by	Read from
NFR-01 (ingestion p95 < 5s)	Load test + continuous gateway metric	Monitoring dashboard
NFR-02 (10x surge)	Load test at the Q-16 profile (1,710/day peak, 9 days) before go-live	Load-test report; hardening pass 1
NFR-03 (99.5% business hours)	Uptime monitor on intake endpoints	Ops dashboard, monthly
NFR-05 (PII boundary)	Security checklist per change touching claim data	PR security gate records
NFR-07 (audit completeness)	Event-log completeness suite in CI	Test results; quarterly compliance sample
ADR-004 eval gate	200-email golden set, ≥95% field accuracy	Eval suite in CI; regression blocks prompt/model changes

The walking skeleton (what Phase 3 must make real): one portal FNOL flows end to end — queue entry → replica coverage check → test-mode acknowledgment → metric event — deployed to Harbor's dev environment through the real pipeline, with the blocking hooks and the grader (a fresh AI reviewer that did not write the code) live.

The Phase 3 handoff (summary)

Signed decisions: ADR-001 through ADR-004; the two build-time security gates registered for the risk-tier map.
Recommended first specs: the walking skeleton, sliced — 0001 queue entry from portal FNOL, 0002 replica verification read, 0003 test-mode acknowledgment, 0004 metric event. Each rides the full loop; together they prove the architecture under the rails.

ID	Open question	Owner	Due
Q-17	Postal dispatch vendor: which provider, and who provisions API credentials for acknowledgment letters?	Dan Kowalski + Harbor ops	Foundation week
Q-18	Construction of the surge load-test dataset from the 2024 CAT event (volume curve + channel mix)	Priti Shah + Nadia Brooks	Before hardening pass 1

You've been handed a project and told to run Phase 2. This page is what you actually type, in order, and what you do between the typing.

Phase 2 takes about a week. Almost none of that is typing. The commands assemble documents; the decisions inside them are human, and four of the files the gate demands have no command behind them at all. Read this once end to end before you start.

Before you type anything

What you need first

Phase 2 cannot be started cold. It runs on what Phase 1 handed you, and on two people you don't control. Book the people on day one — they're the long pole.

Phase 1 closed. /sdlc-status must show Phase 2 active. If it still says Phase 1, finish that gate first — the design scripts read Phase 0–1 artifacts and will produce a thin spec without them.
phase2-handoff.md, read. This is the file Phase 1 wrote for you. Inside it is a section listing AQ-NN items — architectural questions Phase 1 deliberately refused to answer. Step 1 is nothing but resolving them. If your handoff has no AQ list, go back and ask why.
The client's lead engineer or architect, booked. They co-sign every architecture decision record. They own this system after you leave, so they choose with you, not after you. Expect to need 3–5 hours of their time across the week.
Client security, booked for one session. The threat review is a real meeting with a real output that Phase 3 reads. Get it on the calendar around day 4.
Credentials for anything you'll spike against. A spike is throwaway code run against a live system to check an assumption. Sandbox access requests take days. Start them now.
/deep-plan available. Phase 2 leans on it heavily, and it is a separate skill — not part of the SDLC plugin. Check it's in your slash-command list. The phase registry names /plan as the secondary skill if it isn't.

The mistake new people make

Letting Claude answer the architectural questions. It will produce a confident, plausible architecture in about four minutes, and every ADR after that documents a machine's default rather than a decision. Claude presents options; humans choose. That rule is stricter here than anywhere except Phase 0.

Type this — then stop; nothing gets written yet

Resolve the architectural questions

You type /sdlc

What happens: Claude shows you Phase 2 guidance, reads phase2-handoff.md, pulls out every AQ-NN in it, and then blocks. For each question it puts 2–3 concrete options in front of you with their trade-offs and waits. The phase definition is explicit: no artifact gets written until every AQ has a human answer.

What you do: don't answer alone at your desk. These answers become the ADRs, and an ADR the client's engineer didn't help choose is an engagement artifact, not a client decision. Get the option sets in front of your counterpart — a 90-minute session with the options on the table and any spike results in hand — and bring the humans' choices back here.

One option is not a decision

If Claude presents a single approach for an AQ, push back and make it produce real alternatives. The alternatives are where the thinking happens. An ADR built on one option is documentation of a reflex, and it is the most common way this phase goes wrong.

Don't move on until: every AQ-NN in the handoff has an answer a named human stands behind. Write the choices and the reasons down as you go — those notes are the raw material for step 6.

Type this — it just gathers, it decides nothing

Synthesize the spec

You run uv run scripts/synthesize_spec.py --state .sdlc/state.yaml --output planning/spec.md

What happens: the script reads requirements.md, non-functional-requirements.md, epics.md, constraints.md and phase2-handoff.md and stitches them into one file, planning/spec.md. That file is the input the next step consumes. It writes nothing else and changes no state.

What you do: open planning/spec.md and read it. If a requirement or constraint you know matters isn't in there, it came from a Phase 0–1 artifact that is missing or thin — fix the source file and re-run, don't hand-patch the spec.

The phase definition writes that path relative (scripts/…), but the scripts ship inside the plugin. If a bare path errors, use the form the command reference uses: uv run --project ${CLAUDE_PLUGIN_ROOT}/scripts ${CLAUDE_PLUGIN_ROOT}/scripts/synthesize_spec.py …

You now have planning/spec.md — one file, everything upstream

Type this — the long one; budget most of a day

Run /deep-plan, and stop it early

You type /deep-plan @planning/spec.md

What happens: a research-through-review workflow in six visible beats. It studies your existing code and searches the web for practices relevant to this architecture (planning/claude-research.md); it interviews you about technical trade-offs (planning/claude-interview.md); it re-synthesizes everything (planning/claude-spec.md); it writes the actual architecture blueprint in prose (planning/claude-plan.md); it runs a review of that plan by other models if you have them configured, or an Opus subagent if you don't (planning/reviews/); then it folds the review feedback back into the plan.

What you do: two things. First, feed your step-1 AQ answers into the interview — they are the decisions, and /deep-plan should be encoding them, not re-litigating them. Second, stop it after step 15. The steps beyond that are TDD planning and section splitting, and those belong to Phase 3. Let it run on and you'll have Phase 3's work done with Phase 2's information.

planning/claude-plan.md is the primary design artifact of this phase. Read it properly and approve it before you go further — everything downstream is a transformation of it.

Read the external reviews, don't just file them

The review files in planning/reviews/ are the only independent critique your architecture gets before it's built. They're cheap to skim and expensive to skip. Findings you decide not to act on should be written down as accepted, with a name.

Type this — it moves files; it does not write content

Map the outputs into SDLC locations

You run uv run scripts/map_deep_plan_artifacts.py --state .sdlc/state.yaml --phase 2 --planning-dir planning/

What happens: it transforms the planning/ output into the .sdlc/artifacts/02-design/ files the gate looks for. Two of them — design-doc.md and api-contracts.md — come out as skeletons extracted from the plan, with  markers where content is missing. It also copies the research notes, the integration notes and the reviews across, and writes deep-plan-checkpoint.yaml, which Phase 3 reads to resume.

What you do: understand what just happened, because it's easy to misread. This script relocated and reshaped the plan. It did not verify anything and it did not author anything new. The skeletons are starting points; step 7 is where you finish them.

You now have design-doc.md — skeleton api-contracts.md — skeleton phase3-handoff.md — section boundaries research-notes.md · integration-notes.md · external-reviews/ deep-plan-checkpoint.yaml

Note what it did not produce: no ADRs, no ADR registry, no threat model, no spike findings, no proving plan, no walking-skeleton definition. Six of the nine files the gate blocks on are still empty at this point.

Nothing to type — this one touches live systems

Run the spikes

You type nothing — Claude does not run spikes; they use real credentials against real systems

A spike is small throwaway code that answers one question nobody could answer from documentation. The code gets deleted. The written finding is the deliverable.

What you do: list every external system this design bets on, and every assumption it rests on that has only been checked on paper. For each one, phrase the question so that an answer would be recognisable — not "look at the carrier API" but "does the carrier API deduplicate on our idempotency key, or do retries create duplicate claims?" Then go and find out, against the live system. Record each in .sdlc/artifacts/02-design/spike-findings.md: the question, what you tested against (which environment, which version — sandbox and live differ, and the difference is usually the finding), what you observed, whether the assumption survived, and what it changes.

"Still unknown" is a real result and belongs in the file. If the design genuinely depends on no unverified assumption, say that explicitly and name who confirmed it — an empty file is not the same claim.

No command and no template writes this file

spike-findings.md is a required artifact: the gate blocks if it's missing. But nothing in the plugin creates it and there is no template for it. You write it by hand. If a spike genuinely could not happen, the gate accepts a line in the file reading WAIVED: <name> — <reason>, and it reports that waiver, by name, in the record the approver signs. A missing file still blocks. The escape is from the work, not from the record.

Nothing to type — Claude drafts, after you've chosen

Write the decision records

Every choice that would be expensive to reverse gets one file. Technology selection, structural patterns, integration approach, data storage, the security model, API design choices. If undoing it later would cause significant rework, it needs a record.

What you do: take the choices from step 1 and from claude-plan.md, and have Claude draft one record per decision from the template at templates/phases/02-design/adrs/ADR-template.md. Number them sequentially — ADR-001.md, ADR-002.md — and put them in .sdlc/artifacts/02-design/adrs/. Then register every one of them in adr-registry.md, which has its own template and needs three tables: active, superseded, and proposed.

Each record carries the context that forced the decision, the alternatives that were genuinely considered and why they lost, the decision itself, and the consequences — including the unpleasant ones. Then get it signed: yours and your client counterpart's name and date, in the file. The shipped template has a single Deciders: line; put both names there.

Delete the template's guidance comments

The ADR template ships with  comments in it, and <!-- REQUIRED: is one of the strings the gate treats as unfinished work. Leave them in and the whole adrs/ directory fails — one bad file fails the folder. The gate scans every file in that directory for TODO, TBD, PLACEHOLDER, [INSERT, ${ and <!-- REQUIRED:.

What the gate cannot see: it counts no options and reads no signatures. An ADR with one alternative, or with only your name on it, passes the machine check cleanly. Both of those are things the standard requires to close this phase. Nobody but you will catch them.

Nothing to type — you're finishing what step 4 sketched

Complete the design document, the contracts, and the model

The two skeletons are starting points, not drafts. Fill every  marker and enrich the rest.

File	What has to be in it
`design-doc.md`	Architecture overview, what each component does and owns, the key data flows for the primary use cases, the cross-cutting concerns (errors, logging, security, configuration), and the technology choices with their rationale pointing at the ADRs
`api-contracts.md`	Every endpoint or interface, request and response schemas, authentication per endpoint, the error response format and codes, and the versioning strategy
The data model	Entities and their relationships, key fields and types, and the persistence strategy

What you do: write the failure behavior down. A contract that specifies only success is half a contract — the error semantics from Phase 1 are supposed to flow into concrete response codes and degradation behavior here, and if they don't, that Phase 1 work evaporates. Also run the forward-compatibility check the constitution asked for: walk each protected future against the draft model and record the verdict next to it.

The data model has nowhere to live

The phase definition tells you to define the data model, and the standard names it as an owned artifact — but data-model.md is listed as optional in the phase registry, has no template, and no gate checks it. Put it in design-doc.md or write data-model.md yourself. Either is fine; what isn't fine is assuming a green gate means the model was written.

Nothing to type — a real meeting, with security in it

Run the threat review

This happens in Phase 2, not Phase 3, for one reason: Phase 3 wires its build-time security gates from this review's output. Skip it and those gates get chosen by whoever is wiring them, on the day, from memory.

What you do: work from the components, data flows and trust boundaries you just defined — a threat review before there's a design to review is theatre. For each boundary the design crosses, write down four things: what crosses it and how sensitive it is (PII, payment, auth material, client-confidential); what could go wrong, concretely, in this system; the mitigation and where it lives; and the guarded path — the file patterns that must trigger the security workflow on any PR touching them once they're built. Record it in threat-model.md, and record any risk you're knowingly not mitigating with the name of the human who accepted it.

That guarded-path column is the handoff to Phase 3. Get it in front of your client counterpart and security and have a named human accept it. An unreviewed guarded-path list means the security gate protects whatever Claude guessed was sensitive.

The phase text and the gate disagree about this file

The phase definition labels threat-model.md "RECOMMENDED" and says promoting it would block engagements already past Phase 2. The phase registry — which is what the gate actually reads — lists it under required. Trust the registry: the gate blocks on a missing threat-model.md. Like the other receipts, a WAIVED: <name> — <reason> line inside the file is accepted and reported by name.

Nothing to type — two files, both written by hand

Say how the design gets proved

Two required artifacts, no template for either, no command that produces either. Both are agreements, not documentation tasks.

File	What has to be in it
`nfr-proving-plan.md`	Per non-functional requirement: its id and threshold, the verification method (the load profile, the query, the measurement window), the named place the number is read from — a specific dashboard or report, not "monitoring" — who reads it and in which phase, and what happens if it misses
`walking-skeleton-definition.md`	The one user-visible path Phase 3 must build end to end; every ADR it exercises and the mechanism each chose; what is deliberately stubbed and what that defers; and the observable condition that means done

What you do: confirm each measurement method with your Quality Engineer before writing it down — it's an engineering commitment. Then present the proposed skeleton slice and its ADR coverage to the Setup Owner and the QE and get it agreed.

Why these two exist at all

Phase 9 reads the proving plan back when the system is live and the target is either met or it isn't — if the method was never agreed, that becomes an argument about what the number meant. And Phase 3 checks the running software against the skeleton definition; without the file, "the skeleton is done" becomes a matter of opinion. A skeleton that misses an ADR is the common failure here, and it stays invisible until Phase 3 is over.

Type this — or hand-roll it; either is allowed

Render the diagrams

You type /visual-explainer

What happens: you describe the five diagrams the phase asks for and it produces a single self-contained HTML page at .sdlc/reports/architecture-diagrams.html. The five: the architecture layer diagram, the primary flow (core loop or request path), the data flow for the main use case, a dependency graph of the implementation sections from phase3-handoff.md, and the trust-boundary diagram from your threat model.

What you do: replace every piece of ASCII art in design-doc.md with a link to a rendered diagram. If /visual-explainer isn't available, generate the HTML yourself with Mermaid — the rule is that the final artifacts contain rendered diagrams, not that a particular skill produced them.

This one is advisory. The gate surfaces it as a review item for the human signing off; it never blocks. It is also the artifact stakeholders actually look at, which is a decent argument for doing it anyway.

Type this — before the gate, not after

Get the design reviewed by fresh eyes

You type /sdlc-review

What happens: an agent that didn't draft your design reads the phase's artifacts from four viewpoints at once — architecture, product, quality, security — plus a consistency-and-ambiguity pass. It writes review-report.md into the phase's artifact directory with CRITICAL / HIGH / MEDIUM / LOW findings, each pointing at a specific artifact with an actionable recommendation.

What you do: run it with no arguments for this phase — that's the council mode, and it's the one the command reference recommends for Phase 2. Then fix the CRITICAL and HIGH findings before you run the gate; they usually predict gate failures. Findings you're choosing to accept get accepted explicitly, with a name attached, in the review record.

The findings are advisory. Nothing about this command blocks anything — it changes no state and the gate never reads its output.

Type this — the machine checks your work

Run the gate

You type /sdlc-gate → check_gates.py

What happens: seven gates run and an HTML report opens in your browser. For Phase 2 the ones that bite are the first two: every required artifact must exist, and every required artifact must be non-empty and free of unfinished-work markers. Nine files are required — design-doc.md, api-contracts.md, adrs/, adr-registry.md, phase3-handoff.md, spike-findings.md, threat-model.md, nfr-proving-plan.md, walking-skeleton-definition.md. The last gate prints the phase's prose conditions for the human who signs; it always reports and never blocks.

What you do: fix what it flags and run it again until it's clean. The usual culprit is a leftover template comment. Then read the report as a reader, not as an author.

What the gate does NOT check

A green gate here means nine files exist and contain no marker strings. It cannot tell whether any ADR considered more than one option, whether both signatures are on it, whether the integrations were actually spiked or the findings invented, whether the forward-compatibility rule was checked against the model, or whether requirements and design were traced in both directions — that last record, consistency-check-record.md, is optional and nothing checks it at all. Every one of those is on the exit checklist the standard says closes this phase. Walk them yourself.

Optional: /sdlc-phase-report regenerates the HTML at any time, and /sdlc-enhance writes a plain-language companion for stakeholders who won't read the design document.

Type this — last thing in the phase

Get the signatures and advance

You type /sdlc-next → advance_phase.py

Before you type it: finish phase3-handoff.md. It needs the design summary and key decisions, the breakdown of implementation sections, the recommended order with the dependency reasoning, the interface contracts between sections, the open technical questions, and the design risks. Then run the sign-off review — the sponsor gets the design narrative (what was decided, what it costs, what it protects), not the component diagrams. Get a named human on each side to approve the advance.

What happens: it re-runs the gates, then stops and asks you to confirm before it moves anything. Say yes and it marks Phase 2 complete and Phase 3 active. Then it does one more thing: it pulls every open question out of your handoff and makes you answer or explicitly defer each one before any Phase 3 work starts. That gate is blocking and has no exceptions.

What you do: answer them properly. An open question waved through here is a question someone rediscovers in build week three.

Phase 2 is done when state.yaml says Phase 3 every ADR carries both signatures the guarded-path map is accepted by a named human everything is committed in the client's repo

Keep these handy

Commands you'll use constantly

Type this	When
`/sdlc-status`	Any time you're lost. Shows what phase you're in and which required artifacts are still missing.
`/sdlc`	Start of every work session. Tells you what to do next in this phase.
`/sdlc-review`	Any time the design has changed materially. Cheap, advisory, and it reads what you'd rather not re-read.
`/sdlc-coach`	You're stuck and want to be walked through it conversationally instead of following a list.

Rule of thumb for the whole phase: Claude presents options, humans choose. The commands in this list assemble and check documents. Not one of them can make an architectural decision, sign an ADR, accept a risk, or run a spike — and the gate cannot tell the difference between a decision and a default. That difference is the whole value of the week.

Reference · Phase 2 · Design

The precise mechanics — the exact roles, calendar, artifacts, and gate, including the tooling specifics the How-it-works view leaves out. The full prose method sits under each section's “Go deeper” on the How it works tab; for the complete Harbor artifacts (every ID and quote), see Example.

The four questions

Phase 2 answers four questions, and nothing else. Production code, the build-spec backlog, environment provisioning, and pixel-level UI design are deliberately out of scope — they belong to Phase 3 and the Build. Design spikes are explicitly in scope.

What is the shape of the system? (components, boundaries, data flow, deployment view)
What are the contracts? (API contracts, data model, integration interfaces — with error semantics, not just happy paths)
Which decisions are hard to undo, and what did we choose? (architecture decision records, each with real options and consequences, each signed)
How will the design be proven? (the verification approach per NFR, and what the Phase 3 walking skeleton must demonstrate)

The human / AI contract for this phase

This phase has the second-strictest human rule in the standard, after Phase 0's: Claude presents options; humans choose.

Human drives	Claude does	Mandatory human stops
Setup Owner drives the option evaluation, owns the design document, signs every ADR. Client counterpart co-signs each ADR. PO owns product-facing trade-offs.	Researches and frames 2–3 genuine options per decision; drafts ADRs after the human picks; drafts contracts and the data model carrying Phase 1 error specs down; checks consistency both directions; drafts the data-flow diagrams and candidate threat list.	Choosing an architecture, signing an ADR, accepting a risk — all human. Claude never softens a trade-off to make an option look better. Phase advance.

Who is involved

Our side

Person	Load	Workstream
Setup Owner	80–100%	Design authority — drives option evaluation, owns the design document, signs every ADR, owns integration strategy
Orchestrators	50–70%	Design spikes against the riskiest assumptions; drafting API contracts and the data model under the Setup Owner
Pod Lead	40–50%	Keeps design traced to requirements, routes product trade-offs to the PO, runs steering, owns the handoff
Quality Engineer	30–40%	The proving plan — verification approach per NFR, test-strategy skeleton, what the walking skeleton must demonstrate

Client side

Person	Needed for	How much
Lead engineer / architect counterpart	The option sessions; co-signs every ADR — they own this system after handoff	3–5 hours across the week
Security	The threat review; data-flow approval; any open access questions from Phase 1	1–2 hours
Product Owner	Product-facing trade-offs only (behavior under degradation, what users see when things fail)	~1 hour; the 2-business-day decision clock still applies
Ops / DBA	Integration access realities, operational constraints the documents don't show	As the spikes demand
Sponsor	The steering (the design narrative, not the diagrams)	45 min

If the client cannot name an engineering counterpart, that's a finding, not an inconvenience — it predicts the handoff failing, and it goes to the sponsor at steering.

The five-day calendar

The default is 5 business days, stretching to 8–10 when the integration estate is large or the client's review boards add latency.

Day	Focus	What happens	Tooling
1	Drivers & options	Extract the 5–8 design drivers from the handoff; the carried open questions come due; Claude presents option sets; strawmen killed, option session booked; spikes assigned	`/deep-plan`
2	Spikes & option session	Throwaway, hours-boxed spikes run against the live systems; the 90–120 min option session — humans choose; product trade-offs split to the PO. Architecture direction set, ADR list known	— (spikes are exploratory Claude coding on throwaway branches; the session is humans choosing)
3	Records & model	ADRs drafted from the day-2 choices, edited, signed (Setup Owner + counterpart); data model and component design drafted; forward-compatibility check run against the model	`/sdlc-coach` → drafts ADRs (ADR template) & data model
4	Contracts, threats, proving	API contracts completed with error & degradation semantics; threat review with security; QE completes the proving plan and the walking-skeleton definition; first steering	`/sdlc-coach` → contracts; `/visual-explainer` → steering narrative; threat review is a human session
5	Review, gate, handoff	Multi-mode design review; consistency check both directions, orphans resolved; gate check; Phase 3 handoff drafted; steering; sign-offs — billing milestone 3	`/sdlc-review --all` → `multi-reviewer`; `/sdlc-gate` → `check_gates.py`; `/sdlc-phase-report` → `generate_phase_report.py`; `/sdlc-next` → `advance_phase.py`

When the client has a formal architecture review board, schedule it for day 4–5 from day 1; if its cadence can't fit the week, the phase stretches and gate-based billing makes the latency visible rather than absorbed. If a spike falsifies a favored option — good — re-run the option session with the survivors rather than bending the finding.

The artifacts

Artifact	Owned by	Done means
Design document	Setup Owner	The shape of the system — components, boundaries, data flow, deployment view; navigation for the ADRs, short enough to be read, not a novel
Architecture decision records	Setup Owner + client counterpart (both sign)	Each: context, 2–3 options genuinely considered, the choice, the consequences including the unpleasant ones, two signatures
Data model	Setup Owner	Serves every top-tier requirement; passes the forward-compatibility check; convergence constraints (audit, merge rules) are structural, not bolted on
API contracts	Setup Owner	Every operation: shapes, error semantics from the Phase 1 specs, degradation behavior per dependency failure
Integration design	Setup Owner	Every external touchpoint verified by a spike against the live system, not the documentation
Spike findings	Setup Owner	Each risky assumption confirmed or falsified, with evidence; spike code deleted
Threat model + mitigation map	Setup Owner + client security	Data flows reviewed; each threat mitigated in design or assigned as a build-time security gate
NFR proving plan	Quality Engineer	Per NFR: the verification method and where the number will be read
Walking-skeleton definition	Setup Owner	The thin end-to-end slice Phase 3 must ship — named, bounded, sufficient to prove the architecture (every ADR's chosen mechanism exercised at least once on the path)
Consistency check record	Pod Lead	Requirements ↔ design traced both directions; orphans resolved or removed
Phase 3 handoff	Pod Lead	Decisions, contracts, skeleton definition, build risks, recommended first specs, open questions under their original IDs

Deliberately not produced: production code, the spec backlog (Phase 3 and triage own that), provisioned environments (Phase 3), UI visual design beyond what product trade-offs required, and estimates beyond the SOW's phase figures.

The cadences

Rhythm	Who	What
Daily 15-min pod sync	Whole pod	Spike results, decision status, contract progress
The option session	Setup Owner + client counterpart (+ Pod Lead)	The anchor event — options chosen by humans, day 2
The decision-list clock	PO + Pod Lead	Still running — product-facing design trade-offs go to the PO at 2-business-day turnaround
The threat review	Setup Owner + client security + QE	Day 4; its outputs become design changes and build-time gates
Biweekly steering	Sponsor + Pod Lead	Falls mid-or-end of this phase — the design narrative, the trade-offs, what the decisions protect

The exit gate

Phase 2 closes when all of these are true:

Automated gate checks pass — artifacts exist, are complete, contain no placeholders
Every ADR records 2–3 genuinely considered options and carries both signatures (Setup Owner + client counterpart)
Every top-tier requirement maps to a design element, and every major design element traces back — no orphans in either direction
Every external integration the design depends on was spiked against the live system
Contracts carry error semantics and degradation behavior, not just success shapes
The forward-compatibility rule from the constitution was checked against the data model
The threat review happened; every identified threat is mitigated in design or assigned as a build-time security gate
Every NFR has a proving method and a named place its number will be read
The walking-skeleton definition exists and is sufficient to prove the architecture
A named human on each side approved the advance — gates report, humans decide

What goes wrong

The single-option decision. One approach presented, everyone nods, an ADR written around a default. The 2–3-options rule exists because the alternatives are where the thinking happens.
Resume-driven architecture. The interesting technology wins over the boring one that fits. The constitution's principles and the client's operational reality are the tiebreaker — they run this at 2 a.m., not us.
Designing around the constraint instead of with it. The hard boundary gets wished away with "we'll add a real-time feed later." Honor it, or re-open it explicitly — never silently.
Faith-based integration. The design bets on an interface nobody called. Spike-before-you-depend is cheap insurance; the alternative is discovering the truth in Build week 3.
The hundred-page design document. Nobody loads it, so nobody follows it. The design document is navigation — decisions live in ADRs, details in contracts, all three short enough to stay true.
Happy-path contracts. Success specified, failure left to imagination. The Phase 1 error-behavior specs exist precisely to flow into contract error semantics.
Foreclosing the protected future — or gold-plating for an unfunded one. "Must not preclude" means the door stays open, not that the room gets furnished.
The absent counterpart. ADRs signed by one side are an engagement artifact, not a client decision. Surface it at steering while it costs days, not at close when it costs the handoff.