← Phase 0 Phase 1 · Requirements Next: Phase 2 →

Home › Phase 1 · Requirements

Phase 1 · Requirements

Requirements, explained How a signed problem turns into a buildable list of exactly what the system must do — the idea beside the real example (expand any section for the full method), the complete worked example, and a quick reference.

How it works the idea beside the real example — expand any section for the full method · Example the complete Harbor artifacts · Steps the same procedure, no company, just the plugin · Reference the quick mechanics

Phase 0 agreed on the problem and one number that means "solved." But an AI can't build a problem — it can only build instructions.

Phase 1 is where the problem becomes a list of exactly what the system must do, written so precisely that two people couldn't build two different things from it.

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

01

Why this phase exists at all

An AI builds the instructions, not the intent

A coding agent does exactly what the requirement says. If the requirement is vague, the agent fills the gap with a guess — confidently, at 2 a.m., in week seven, with nobody watching. The whole point of Phase 1 is to leave no gaps worth guessing about.

The idea

A vague line isn't a small problem. It's an open invitation for the build to drift away from what anyone actually wanted — and you won't notice until the wrong thing is already running.

So Phase 1 turns the agreed problem into requirements precise enough that there's nothing left to invent. Each requirement carries the checks that prove it's met. A wish caught here is a sentence rewrite; the same wish caught in the build is a feature thrown away.

At Harbor Mutual

Harbor's whole reason for hiring the pod was a number from Phase 0: a claim takes a median of 11.4 days from being reported to a decision, and slow claims cost renewals. The target is half that.

11.4≤ 5.0 days from claim to decision today → the target — the number Phase 1's requirements have to actually move

A number like that isn't moved by good intentions. It's moved by a buildable, testable list of behaviors — which is exactly what this week produces.

Skip this phase and…

You hand an AI a goal instead of instructions, and it builds a confident, well-tested answer to a question nobody actually asked.

Go deeper — the full method

Phase 0 agreed on the problem and one measurable number. But a coding agent cannot build a problem — it builds instructions, and it does exactly what the instruction says. Phase 1 is where the signed problem becomes a requirements baseline: a list of exactly what the system must do, written so precisely that two people could not build two different things from it.

Phase 1 answers four questions, and nothing else:

  1. What must the system do? Functional requirements with testable acceptance criteria.
  2. How well must it do it? Non-functional requirements, each with a measurement basis.
  3. In what order does value ship? Epics, sequenced against the outcome, priorities set by the product owner.
  4. What is explicitly out? Scope boundaries written down before pressure arrives.

Everything that looks like architecture, technology selection, data modeling, or estimation is deliberately out of scope — that work belongs to Phase 2 and beyond. A requirement says what and how well, never how. A wish caught here is a sentence rewrite; the same wish caught three weeks into the build is a feature thrown away.

02

The rule that governs everything

Claude drafts and interrogates; humans decide and own

This is the busiest drafting week of the whole engagement — and the rule from Phase 0 binds harder than ever. The AI writes the requirements, finds the conflicts, and keeps the running list of decisions nobody's made. People make every one of those decisions and sign for them.

The idea

There are three things the AI is never allowed to do in this phase, because each is a human's accountability:

  • It never sets a priority — what ships first is a product call.
  • It never accepts a requirement as good enough — a person confirms it says what they meant.
  • It never decides what's in or out — scope is owned, not generated.

The AI's job is to make every decision visible and cheap to make. The human's job is to actually make it.

At Harbor Mutual

The clearest example: should the system that spots a "simple" claim decide it, or just recommend and let an adjuster confirm?

The decision the AI surfaced — but could not make
"Does the fast-path decide a claim, or recommend one for a human to confirm?"
Luis Ortega, Harbor's product owner — took the full two days, then ruled
"v1 recommends; an adjuster confirms with one click. Regulatory caution until 'simple' is proven against a year of data."

An unanswered question like that is exactly what an agent resolves silently in week seven. Here it got a named human and a recorded reason.

Go deeper — the full method

Phase 1 is the drafting-heaviest phase of the engagement, and the rule from Phase 0 still binds: Claude drafts and interrogates; humans decide and own. Concretely, Claude does a great deal:

  • Decomposition drafting. From the Phase 0 artifacts and the document corpus, Claude drafts the candidate epic map and candidate requirements — every one carrying a source trace (a document reference like DOC-003, or "elicitation session, day 2").
  • The decision list, continuously. Every draft regenerates the list of decisions no human has made yet ("you haven't decided what happens when a duplicate arrives"). The list is the PO's work queue, on a visible 2-business-day clock.
  • Conflict and gap checks. Claude cross-checks every requirement against the constitution and the Phase 0 constraints ("REQ-014 implies storing claimant documents; constraint C-05 says PII stays in the client tenant — reconcile") and flags requirements that trace to nothing.
  • Drafting the structure that makes review cheap. Stable requirement IDs, acceptance criteria in checkable form, error behavior spelled out for the highest-priority items (what it accepts, what it returns, what it does on failure).

What Claude never does in Phase 1: set a priority, accept a criterion, or make a scope call. Those are the product owner's, and in proxy mode they are logged, not just made.

03

What the week must answer

Four questions — and deliberately nothing else

Phase 1 answers exactly four questions about the system. Anything that smells like how to build it — the technology, the data model, the diagrams — is off the table. A requirement says what and how well, never how.

The idea — the four questions
  1. What must the system do? Behaviors, each with the checks that prove it works.
  2. How well must it do it? Quality targets — speed, capacity, uptime — each with a real way to measure it.
  3. In what order does value ship? The work sliced and ranked by what moves the goal first.
  4. What is explicitly out? The not-now list, written down before the pressure to cram it in arrives.
At Harbor Mutual — the four answers
  1. Every claim, from any channel, shows up in one queue within five minutes; duplicates get merged, never rejected.
  2. The queue handles 40,000 claims a year and a 10x storm surge; coverage status ready the same business day.
  3. Queue first (everything lands in it), then coverage, then the fast-path for the simple majority of claims.
  4. Out of v1: auto claims, SMS, fraud scoring, payment changes, and the adjuster dashboard rebuild.
The temptation to resist

It feels efficient to start naming technologies now — "we'll use a message queue." That's design leaking upstream. Write the behavior it wanted instead ("intake must keep accepting claims even when downstream systems are down"), and let Phase 2 choose the how.

Go deeper — the full method

Everything Phase 1 produces exists to answer exactly four questions, and nothing else:

  1. What must the system do? Functional requirements with testable acceptance criteria.
  2. How well must it do it? Non-functional requirements, each with a measurement basis — the number, how it is measured, and where it is read from.
  3. In what order does value ship? Epics, sequenced against the outcome, with priorities set by the product owner inside a top-tier budget.
  4. What is explicitly out? Scope boundaries written down before the pressure to cram them in arrives.

Everything that looks like architecture, technology selection, data modeling, or estimation is deliberately out of scope — that work belongs to Phase 2 and beyond. A requirement that names a technology ("the system shall use a message queue") is design leaking upstream; rewrite it as the behavior it wanted ("intake must accept submissions during downstream outages"), and let Phase 2 choose the how.

04

The technique that earns the phase

The vague-line test: could two people build two different things?

Every requirement gets one brutal question asked of it: could two people read this line and build two different things? If yes, it's a wish wearing a requirement's clothes — and it goes back to be sharpened, not quietly into the pile.

The idea

Words like "promptly," "intuitive," "robust," and "clearly visible" feel like requirements but specify nothing. An AI handed "respond promptly" will pick a number for you — and it won't be the one you'd have picked.

A dedicated person — the testability conscience — runs every acceptance check through this test before it's allowed to stand. This is the enforcement point: catch the vagueness here, on a Wednesday, not three weeks into the build when it's expensive.

At Harbor Mutual

On day 3, the testability pass caught five of thirty-one acceptance checks failing the test. The fixes turned wishes into things you can actually verify:

A line that failed the test
"The new claim appears in the queue promptly and is clearly visible."
The same requirement, sharpened
"A claim submitted via portal at 14:00 is visible in the queue with status 'new' by 14:05 — same for phone-entered and parsed-email claims."
Go deeper — the full method

Every acceptance criterion gets one question asked of it — the vague-line test: could two people read this line and build two different things from it? If yes, it is a wish wearing a requirement's clothes, and it goes back to be sharpened, not quietly into the pile.

The Quality Engineer is the testability conscience. On day 3, every acceptance criterion goes through the vague-line test; criteria that fail go back to the Pod Lead, not quietly into the pile. This pass is the enforcement point — not the build loop three weeks later, where the same vagueness is expensive.

The untestable criterion

"Intuitive," "robust," "fast." The vague-line test exists for exactly this. An AI handed "respond promptly" picks a number for you — and it will not be the one you would have picked.

05

The quality targets, made real

"Fast" is an opinion — until you say where the number is read

Beyond what the system does, there's how well it has to do it: speed, capacity, uptime. The trap is writing "the system shall be fast." A quality target without a way to measure it is just a wish with a number attached.

The idea

Every quality target must carry three things: the number, how it's measured, and where that measurement is read from. "Fast" becomes "95% of requests under 800ms, measured at the gateway, read off the monitoring dashboard."

And the number itself comes from a human — the client's own data or a stated target. If nobody on the client side ever said the number, it doesn't get invented into the draft; it goes on the decision list for someone to answer.

At Harbor Mutual

Writing the quality targets surfaced a gap nobody had named: storm season. The Phase 0 sizing said 40,000 claims a year — and said nothing about peaks.

What the data lead's catastrophe records showed
"A catastrophe event spikes intake to roughly 10x normal daily volume — about 1,600 claims a day — for a week straight."
The quality target it forced
"Sized for 40,000 claims/yr steady state and a 10x storm surge; load-tested at the surge profile before go-live."

A genuinely buildable spec has to survive a hurricane, not just an average Tuesday.

A common way this fails

Quality targets get written as theater — impressive-sounding numbers nobody can ever read. If you can't say where the number will be measured, the target isn't done.

Go deeper — the full method

Beyond what the system does is how well it must do it: speed, capacity, availability. Every non-functional requirement carries a measurement basis — the number, how it will be measured, and where it will be read ("p95 API response under 800ms, measured at the gateway, read from the monitoring dashboard," where p95 means 95% of requests come in at or under the number). An NFR without a measurement basis is an opinion.

The numbers themselves come from humans — elicitation, the constraints, the client's own data. A target nobody on the client side stated goes on the decision list, not into the draft.

NFR theater

Non-functional requirements with no measurement basis are wishes. If nobody can say where the number will be read, the NFR is not done.

06

Deciding what ships first

If everything is top priority, nothing is

Left alone, every requirement becomes "must-have." That's not a plan — it's a refusal to plan. The defense is a hard cap on the top tier, set before the room can argue, and the product owner does the cutting.

The idea

The pod sets a budget for the top priority tier — sized to what can credibly ship in the first stretch of building — and announces it when the priority session opens. The product owner ranks within that budget.

The pod advises on cost and risk; it never sets the order. And it refuses to start building from a list where the top tier is over budget — because a blown budget just means the hard choices got deferred to a worse time.

At Harbor Mutual

The priority session: a top-tier budget of 12 slots, and 19 candidates fighting for them. Luis did the cutting, not the pod.

Seven requirements cut to fit the budget — including, painfully, the adjuster dashboard rebuild.
"We survive with the current screens one more quarter."

That cut hurt — which is exactly what a real priority decision is supposed to feel like. The budget held.

Go deeper — the full method

Left alone, every requirement becomes "must-have." Priority inflation is the default state of nature, and it is a refusal to plan. The defense is a hard budget for the top tier, enforced in the priority session.

The Pod Lead sets the budget before the session — sized to what the pod can credibly deliver in the first stretch of Build — and announces it when the session opens. Every requirement gets a priority the PO assigns: the pod advises on cost and risk, the PO owns the order and ranks within the budget. The pod refuses to start a phase where the top tier is over budget, because a blown budget just means the hard choices got deferred to a worse time.

Everything is P0

If everything is top priority, nothing is. The budget is the only thing that forces the real choice — and the PO, not the pod, makes the cut.

07

Every requirement earns its place

Where did this come from, and what does it serve?

A requirement that can't say where it came from and what goal it serves is usually someone's pet feature in disguise. So every one has to point backward to a source and forward to the outcome it moves.

The idea

Backward: this requirement traces to a real document or a named working session — a human said it. Forward: it traces to one of the agreed outcomes — it actually helps.

A requirement that traces to nothing gets challenged on the spot. And a special trap: the client's original hiring document is evidence, not a requirements list. Anything that traces only to that document and was never confirmed by a person is a candidate, not a commitment.

At Harbor Mutual

The traceability check claimed one casualty: a requirement for SMS notifications that traced to nothing — no document, no session, no stakeholder.

Where it actually came from
"It came from the boilerplate appendix of the RFP — the hiring document — and no human ever confirmed it."
What happened to it
"Cut on day 5; recorded in the explicit not-in-v1 list so the choice is visible, not silent."
The trap in plain sight

The hiring document feels authoritative, so its every line gets treated as a requirement. But Phase 0 already proved the client's own documents contradict each other. Untraced lines are leads to confirm, not orders to build.

Go deeper — the full method

Traceability means every requirement points backward to its source (a document or a named session) and forward to the outcome it serves. A requirement that can say neither is usually someone's pet feature wearing a requirement costume, and it gets challenged on the spot.

On day 5 the traceability check verifies that every top-priority requirement traces both ways. The traceability matrix — requirement → source and requirement → outcome — is populated for the top tiers by the Quality Engineer.

The corpus treated as requirements

The RFP is evidence, not a baseline. Requirements that only trace to the RFP and were never confirmed by a human in elicitation are candidates, not commitments — Phase 0's contradictions already proved the corpus disagrees with itself.

08

A fresh pair of eyes, on purpose

Have someone who didn't write it try to break it

The people who wrote the requirements share the same blind spots that produced them. So before the phase closes, fresh reviewers — who didn't write a word of it — attack the whole set from the product, quality, and security angles.

The idea

The review hunts for the things authors can't see: conflicting requirements, missing failure paths, unstated assumptions, regulatory gaps. It's adversarial by design — the goal is to find the holes now, cheaply, instead of in production.

For the top-priority items, this is also where error behavior gets nailed down: what each operation accepts, what it returns, and what it does on every way it can fail. That's where most confident-wrong builds get prevented.

At Harbor Mutual

The day-5 review produced two catches the authors had missed because they shared the draft's blind spots:

Catch one — a missing failure path
"The acknowledgment requirement had no plan for a bounced email — against a state rule that demands a written acknowledgment. Added a postal fallback."
Catch two — a hidden conflict
"A 'recommend' fast-path could let a claim sit unconfirmed past the regulatory clock. Fixed by adding the clock to the fast-path's escalation rule."
Go deeper — the full method

The people who wrote the requirements share the same blind spots that produced them. So on day 5, before the phase closes, a structured adversarial review runs: fresh eyes — a review agent that did not write the draft, plus the Quality Engineer — challenge the set from product, quality, and security angles, hunting for conflicting requirements, missing error paths, unstated assumptions, and regulatory gaps.

For the top two priority tiers, error behavior is spelled out explicitly: what each operation accepts, what it returns, and what happens on each failure mode. This is where most confident-wrong builds get prevented — an agent that knows exactly what to do on a bounce, a not-found, or a stale read cannot improvise the wrong thing at 2 a.m.

09

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 is front-loaded with conversation — the open questions, the working sessions, the full draft — and back-loaded with verification — the priority cut, the checks, the review, the gate. Five days, assuming Phase 0 did its job. Step through it.

Day 1 · handoff & the plan

Close the loose ends, draw the map

The two questions Phase 0 carried forward come due — and both get answered the same day: every channel gets the 15-day acknowledgment clock (one state needs it in writing), and 61% of claims turn out simple enough to fast-track. The AI drafts a candidate map of the work — six big slices — and the Pod Lead corrects it and plans the sessions.

Day 2 · elicitation

Draw the requirements out of the people who do the work

Five working sessions, the right person in each room. Crucially, not just the managers: the intake clerks reveal a duplicate-claim workaround nobody had documented — the same loss reported by phone and portal gets two claim numbers today. By evening, the AI has structured the notes into 31 candidate requirements, each traced to its source.

Day 3 · the full draft

The complete draft — and what it exposes

The AI produces all 31 requirements plus 7 quality targets, each with a real way to measure it. One target exposes the storm-surge gap nobody had named. The decision list regenerates — nine open product calls for Luis — and the testability conscience sends five vague lines back to be sharpened. A 30-minute sponsor checkpoint keeps the day-5 review from holding surprises.

Day 4 · priorities & stories

The product owner does the cutting

The 90-minute priority session: a 12-slot budget, 19 candidates, Luis ranking within it and cutting seven. The work gets sequenced by what moves the goal first. Stories get written under each slice with real, named stakeholders — no invented users. And the top-priority items get their error behavior spelled out in full.

Day 5 · verify, review, gate

Break it, check it, sign it

The traceability check cuts the untraced SMS requirement. Fresh reviewers attack the set and find two real holes. The automated gate check runs clean. The AI drafts the handoff to the design phase — decisions, open questions, risks, a recommended starting point. The product owner confirms the requirements say what he meant; the sponsor sees the not-in-v1 list with her own eyes. Sign-off. The engagement advances — billing milestone.

1 / 5
Go deeper — the full method

The default calendar is 5 business days — one week, assuming Phase 0 did its job (a signed problem statement, a verified metric, resolved contradictions, a working PO arrangement). It stretches to 8–10 days when the epic count is large, the domain is heavily regulated, or proxy mode adds ratification latency. The week is front-loaded with conversation and back-loaded with verification.

  • Day 1 — handoff intake and the elicitation plan. The pod works the open questions Phase 0 carried forward (each with an owner and a "this week" due date). Claude drafts the candidate epic map from the Phase 0 artifacts — 4–8 epics, each traced to one of the three outcomes — and the Pod Lead corrects it and plans one elicitation session per epic area. If the success metric could not be read end-to-end, the instrumentation epic goes on the map first. Orchestrators start the read-only feasibility spikes the handoff flagged.
  • Day 2 — elicitation. Working sessions with domain experts and the PO, one per epic area, 60–90 minutes each, run by the Pod Lead. The people interviewed are the ones who live the work — the intake clerk knows the duplicate workaround; the manager knows the org chart. By end of day, Claude has structured the notes into draft functional requirements with stable IDs and source traces.
  • Day 3 — the full draft and the decision list. Claude produces the complete draft: functional requirements with acceptance criteria, plus NFRs each carrying a measurement basis. The decision list regenerates and the PO starts working it on the 2-business-day clock (now the phase's critical path). The Quality Engineer runs the testability pass. A 30-minute sponsor checkpoint reads the draft epic map and emerging scope-out, so nothing at the day-5 review is a surprise.
  • Day 4 — priorities and stories. The 90-minute priority session, PO driving, ranking within the announced top-tier budget. Epics get sequenced by which moves the metric first. User stories are drafted under each epic with real stakeholder justifications — no fabricated personas. For the top two tiers, error behavior is spelled out. Feasibility spike results land and anything they contradicted gets reconciled.
  • Day 5 — verification, review, and the gate. The traceability check; a structured adversarial review; the automated gate check (placeholders fixed today); Claude drafts the Phase 2 handoff (summary, decisions with rationale, numbered open questions with owners, design risks, recommended starting point). At the phase review the PO confirms the requirements say what they meant and the sponsor sees the scope-out list. Sign-off recorded; the engagement advances; the first biweekly steering is scheduled.
When the week stretches

The PO can't keep the 2-day clock → escalate to the sponsor by name; the clock is in the SOW. Elicitation keeps finding new epics past 8 → the outcome is too broad; take it to the sponsor as a scope conversation, not a longer phase. Proxy mode → add 2–3 days for decision-log ratification and batch the log for one sponsor session.

10

How it goes wrong

The failure modes, and the defense against each

Every one of these has happened to someone. Knowing them by name is half the defense — and Harbor's structure caught several of them in the act.

The trapWhat it looks likeThe defenseAt Harbor
Everything is top priorityEvery requirement gets stamped "must-have" and the plan means nothingA hard budget for the top tier; the product owner ranks within it.Held — 19 candidates, 12 slots, 7 cut
Design in disguise"Shall use a queue," "shall be microservices" written as if it were a requirementRewrite as the behavior that motivated it. Phase 2 chooses the how.Behaviors only; no technology named
The hiring doc as gospelEvery line of the RFP treated as a committed requirementIt's evidence, not a baseline. Untraced lines are candidates.Caught — SMS line cut on day 5
The untestable line"Intuitive," "robust," "fast" — nothing you can verifyThe vague-line test, enforced before the line can stand.Caught — 5 of 31 sent back
Quality-target theaterImpressive numbers nobody can ever actually readEach target names where the number gets measured.All 7 carry a measurement basis
Only hearing managersEvery session attendee has "manager" in their titleTalk to the people who live the process daily.Caught — clerks found the dupe workaround
Go deeper — the full method

Every one of these has happened to someone. Knowing them by name is half the defense:

  • Everything is P0. Priority inflation is the default state of nature. The defense is a budget for the top tier, enforced in the priority session — the PO ranks within it, and the pod refuses to start a phase where the budget is blown.
  • Design wearing a requirements costume. "Shall use a queue," "shall be built on microservices." Each forecloses Phase 2 before it starts. Rewrite as the behavior that motivated it.
  • The corpus treated as requirements. The RFP is evidence, not a baseline. Requirements that only trace to the RFP and were never confirmed by a human in elicitation are candidates, not commitments.
  • The untestable criterion. "Intuitive," "robust," "fast." The vague-line test exists for exactly this, and the QE's testability pass is the enforcement point, not the build loop three weeks later.
  • NFR theater. Non-functional requirements with no measurement basis are wishes. If nobody can say where the number will be read, the NFR is not done.
  • Silent proxy drift. In proxy mode, the pod starts making product calls without logging them — each one a liability that surfaces at the worst time. The decision log is cheap; the month-six dispute is not.
  • Elicitation that only hears managers. The people who live the process know where the bodies are buried. If every attendee has "manager" in their title, the requirements describe the org chart's beliefs, not the work.
  • The decision-list stall. The PO's clock slips, the pod fills the silence with guesses, and Phase 1 quietly becomes proxy mode without the rider. Escalate the clock breach instead — it's in the SOW precisely so this moment has teeth.

When Phase 1 is done

You have a list precise enough to build from — and a list of what you won't

Requirements doesn't end in a wish list. It ends with a buildable set of behaviors, each with the checks that prove it, ranked within a budget, traced to the goal — and an explicit record of what's out, seen by the person who'd otherwise ask "I assumed that was included" in month four. Where to go next:

01

Before a single requirement is written, five files arrive and two questions are still open

What Phase 1 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 0 closed Friday 2026-03-13 with a signed problem, a verified baseline, and two open questions. Requirements does not start from a blank page — it starts from these five files, on disk, in Harbor's own repository.

Inherited from Phase 0 — the signed problem baseline; the plugin's Step 0 reads phase1-handoff.md phase1-handoff.md constitution.md problem-statement.md success-criteria.md constraints.md
The number, and the two unknowns that come due this week

The whole engagement turns on one number, and Phase 1's requirements are what have to move it. Two questions Phase 0 could not close came forward — and their answers shape the requirements, so they are due Monday.

11.4≤ 5.0 days from claim to decision today → the target the requirements must actually move
  • Q-13 (Luis) — do state claim-acknowledgment rules differ per intake channel?
  • Q-14 (Priti) — what share of claims is simple enough to fast-track?
Where the week is headed

Phase 1 turns the signed problem into a list of exactly what the system must do, written so precisely that two people could not build two different things from it. Everything this week is either a behavior the system must have, a number it must hit, or a decision a named human still owes.

Luis Ortega is the one to watch. Harbor's product owner spends his first real hours here: he assigns every priority, answers every product decision on a two-business-day clock, and does the cutting when the top tier is over budget. The pod advises; Luis owns.

Carried in from Phase 0, still open on Monday
Q-13 — per-channel acknowledgment rules? (Luis) · Q-14 — how many claims are simple enough to fast-track? (Priti)

Our pod

Maya ChenPod Lead — runs elicitation, owns requirement quality and the handoff
Rob FeldSetup Owner — enablement runs ahead; answers feasibility questions
Jonah KimOrchestrator / Checker — runs the feasibility spikes
Sara WhitfieldOrchestrator / Checker — runs the feasibility spikes
Nadia BrooksQuality Engineer — the testability conscience; owns traceability

Harbor Mutual

Karen VossVP Claims Operations — sponsor; sees the scope-out list, approves the advance
Luis OrtegaProduct owner — assigns priorities, answers decisions on a 2-day clock
Priti ShahData & reporting — the storm data, the instrumentation, Q-14
Dan KowalskiIT security — the replica-access question (Q-15) the requirements raise
Domain expertsGail Tran, Marcus Webb (adjusters), Dee Alvarez (intake), compliance
The ID codes, decoded

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

PrefixMeansBorn inExample here
DOC-NNNA client document taken in at intakePhase 0DOC-003 FNOL channels · DOC-007 the stale 2023 API inventory
C-NNA constraint — a hard limit the requirements must honorPhase 0C-03 auto-proof · C-04 15-day clock · C-05 PII-in-tenant
CON-NNA Phase 0 contradiction, resolvedPhase 0CON-01 real-time vs nightly batch
Q-NNAn open question with an owner and a due dateanyQ-13, Q-14 due this week; Q-15, Q-16 born here
D-NNA product decision the PO owes usPhase 0/1D-07 duplicate merge · D-09 fast-path recommends
REQ-NNNA functional requirementPhase 1REQ-014 same-business-day coverage
NFR-NNA non-functional requirement — a quality targetPhase 1NFR-02 the 10x storm surge
E-NNAn epic — a slice of the work, traced to an outcomePhase 1E-01…E-06
AQ-NNAn architectural question Design must answerPhase 1 handoffThe four that become Phase 2's ADR-001–004

The last row is the thread out of this phase. Phase 1's handoff records the AQ-NN — the architectural questions the requirements raise but must not answer. Phase 2's very first step reads exactly those out of phase2-handoff.md and turns each into a signed ADR. An AQ with no ADR at the end of design week is a gate failure.

02

The plugin's eight steps, the standard's five days, braided

The procedure, step by step

Phase 1 is eight numbered steps in claude-code-sdlc and five working days in this standard — 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 day leaves behind. This is the drafting-heaviest week of the engagement, and also the one where the most human work leaves no receipt. 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/16 · plugin Step 0 opens

Confirm the scope, then draw the map of the work

Before any requirement is written, the plugin stops for a human. Claude reads phase1-handoff.md and confirms scope: are Phase 0's open questions answered, is the prioritization clear, is anything expected that Discovery missed? Only then does drafting begin. The pod's own day-1 craft — which no command performs — is drawing the candidate epic map and planning one elicitation session per slice.

Tooling /sdlc-next Step 0 HITL gate /sdlc-coach requirements-analyst human decision
Out Q-13 & Q-14 answered — decisions, not yet on disk candidate epic map (draft)
At Harbor

Q-13 (Luis): the 15-day acknowledgment clock applies to every channel, and one regulated state requires a written acknowledgment — a portal screen alone does not count. Q-14 (Priti): the segmentation query says 61% of claims are single-dwelling, no-injury, under $25k. The requirements-analyst agent drafts the six-epic map; Maya corrects one boundary (email is its own beast, not part of the queue epic). Jonah and Sara start the feasibility spikes.

Day 2 — Tue 3/17 · elicitation · no command runs

Draw the requirements out of the people who do the work

The requirements come from humans in rooms, not from the tool. Five working sessions, 60 to 90 minutes each, one per epic area, the right person in every room — and crucially not just the managers. By evening Claude has structured the notes into candidate functional requirements, each carrying a source trace back to the document or session it came from.

Tooling none — human elicitation sessions; Claude preps question lists and structures the notes after
Out 31 candidate requirements, each source-traced (draft)
At Harbor

Sessions: queue/assignment (Dee plus two intake clerks), coverage (Gail, Marcus), fast-path (Luis, Marcus), acknowledgments (compliance), instrumentation (Priti). The clerks — not their supervisor — reveal the duplicate-FNOL workaround: the same loss reported by phone and portal gets two claim numbers today. That one finding becomes REQ-004 and D-07. Talk only to managers and it never surfaces.

Day 3 — Wed 3/18 · plugin Steps 1–2

The full draft — and what it exposes

Now the tool writes. Step 1 turns the notes into functional requirements — "the system shall…", each with a priority, a source trace, and (for the top tiers) an explicit error specification: what it accepts, what it returns, what it does on each failure. Step 2 writes the non-functional requirements, every number carrying a measurement basis. The decision list regenerates and the testability pass runs.

Tooling /sdlc-coach requirements-analyst
Out — under .sdlc/artifacts/01-requirements/ requirements.md non-functional-requirements.md the decision list — regenerated in the session; no file holds it
The gap you should know about

The standard's decision list is the PO's work queue — every unmade product call, visible, on a two-business-day clock. In claude-code-sdlc Phase 1, no file holds it. The plugin's Step 0 asks the human about open questions once, in conversation; nothing writes them down, ages them, or checks at the gate that they were answered. The clock the SOW bills against has no artifact behind it.

At Harbor

31 functional requirements and 7 NFRs land. NFR-02 exposes the storm-surge gap nobody had named — Phase 0 sized annual volume only. The decision list regenerates to nine open items for Luis; D-07 is answered same day, D-09 takes the full two days. Nadia's testability pass sends 5 of 31 acceptance criteria back for being untestable. A 30-minute sponsor checkpoint keeps the day-5 review free of surprises.

Day 4 — Thu 3/19 · plugin Step 3 · the priority session

The product owner does the cutting

Step 3 writes the epics — user stories in "as a / I want / so that" form with Given/When/Then acceptance criteria — into epics.md. But the day's real work is human and has no command: the priority session, where the PO ranks within a hard top-tier budget the pod announced, and cuts whatever doesn't fit. Feasibility spike results land and get reconciled.

Tooling /sdlc-coach stories + P0 error specs the priority session — the PO's room; no command sets an order
Out epics.md the P0 budget & the cut list — a decision, no file feasibility spike findings — no command writes them
The gap you should know about

The word "spike" appears in no file in claude-code-sdlc's Phase 1. Nothing prompts a feasibility check against the live system, and nothing records what it found. At Harbor the spikes were the most valuable hour of the week — and they leave no receipt.

At Harbor

The 90-minute priority session: a 12-slot budget, 19 candidates, Luis cuts 7 — including, painfully, the adjuster-dashboard rebuild. Epics get sequenced by what moves the metric. Error behavior is written for all 12 P0 requirements. The spikes land: DOC-007 (the 2023 API inventory) is stale in a useful direction — PolicyOne now exposes a read-only nightly snapshot replica (becomes Q-15), and the FNOL inbox is readable programmatically.

Day 5 — Fri 3/20 · plugin Steps 4–7 · the gate

Break it, check it, sign it

Fresh reviewers that did not write the draft attack the set from product, quality, and security angles. The traceability check runs. Then the tool writes the handoff, renders the stakeholder report, and the gate runs and stops for a human. advance_phase.py will not move the engagement forward without a named sign-off.

Tooling /sdlc-review --adversarial multi-reviewer /visual-explainer .sdlc/reports/phase01-visual.html /sdlc-gate check_gates.py /sdlc-next advance_phase.py
Out phase2-handoff.md phase01-visual.html phase01-report.html the adversarial-review record the traceability check the scope-out record the PO's + sponsor's sign-off — billing milestone 2
What the gate actually checks

check_gates.py verifies that four files exist, are non-empty, and contain no placeholder text: requirements.md, non-functional-requirements.md, epics.md, phase2-handoff.md. It never reads the nine-bullet exit checklist this standard specifies — priorities assigned by the PO, the scope-out seen by the sponsor, error specs for every top-tier operation, traceability traced both ways. That list lives in phase-registry.yaml, and no code opens it. The human gate is real. What it asks is not.

At Harbor

The traceability check cuts the untraced SMS requirement (it traced only to RFP boilerplate). The multi-reviewer pass plus Nadia produce two catches: REQ-022 (bounce-to-postal fallback for a bounced acknowledgment) and the fast-path/regulatory-clock conflict. The gate passes clean; Claude drafts the Phase 2 handoff. Luis confirms the requirements say what he meant; Karen sees the scope-out list. Sign-off; the engagement advances. First biweekly steering booked for Thursday 3/26.

1 / 5
03

Everything that exists on Friday and didn't on Monday

What Phase 1 produced

The requirements 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 of their own behind. Those are the rows to argue about.

ArtifactWhat it actually isWritten bySigned byLives atFeeds
requirements.mdThe functional requirements: each a "shall", with a priority, a source trace, testable acceptance criteria, the error spec for the top tiers, and the traceability matrix — all in one file/sdlc-coachrequirements-analystPod Lead; PO accepts.sdlc/artifacts/01-requirements/Phase 2 spec synthesis
non-functional-requirements.mdThe quality targets — speed, capacity, uptime — each with a number, a test method, and a measurement basis naming where the number is read/sdlc-coachrequirements-analystPod Lead + QE.sdlc/artifacts/01-requirements/Phase 2 design drivers (the AQ-NN)
epics.mdEpics and the user stories under them — "as a / I want / so that" with Given/When/Then acceptance criteria, each linked to a requirement ID/sdlc-coachrequirements-analystPO.sdlc/artifacts/01-requirements/Phase 3 spec backlog
phase2-handoff.mdRequirements summary, the architectural implications the NFRs raise (the AQ-NN), decisions with rationale, open questions under their original IDs, risks, recommended starting point/sdlc-coach drafts; Pod Lead completesPod Lead.sdlc/artifacts/01-requirements/Phase 2 Step 0, directly
phase01-visual.htmlThe requirements retold as a stakeholder-facing visual — the standard's "narrative companion", rendered/visual-explainer.sdlc/reports/The stakeholder review
phase01-report.htmlThe gate result and artifact inventory, self-contained. This is the document a sponsor actually reads before signinggenerate_phase_report.py.sdlc/reports/The manual sign-off gate
error-behavior specsFor every top-tier operation: what it accepts, what it returns, what it does on each failure modePlugin Step 1 — but into requirements.md, not its own filePod Lead + QEfolded into requirements.mdPhase 2 contract error semantics
traceability matrixEvery top-tier requirement traced to a source and forward to an outcome, both directionsPlugin Step 1 — but into requirements.md, not its own fileQEfolded into requirements.mdThe exit gate
user storiesThe stakeholder justification under each requirement — real people, no invented personasPlugin Step 3 — but into epics.md, not their own filePOfolded into epics.mdPhase 3 specs
the decision list / logEvery unmade product call, numbered, owned, aged on the 2-business-day clock — empty or fully-owned at the gatePO answers; nothing writes itPOno path — nothing writes itThe exit gate; Phase 2 open questions
feasibility spike notesEach handoff risk verified against the live system, or converted into a requirement change — the spike code deleted, the finding keptOrchestrators, on a throwaway branchPod Leadno path — nothing writes itPhase 2 design risks
scope-out recordThe explicit not-in-v1 list, shown to the sponsor at the review so no one assumes a cut item into the buildPod LeadSponsor has seen itno path — nothing writes itPhase 2 scope inputs
adversarial review recordFresh reviewers who did not write the draft, attacking it from product, quality, and security angles; the catches recordedmulti-reviewer + QEPod Leadno path — nothing writes itThe fixes it forces (REQ-022, the clock conflict)
Read the amber rows again

Seven of the thirteen things Phase 1 is supposed to produce have no home of their own. Three are folded into a bigger file — error specs and traceability into requirements.md, stories into epics.md — so they exist but can't be checked or cited on their own. Four leave no receipt at all: the decision list the SOW clock bills against, the spike that found Harbor's snapshot replica, the scope-out list the sponsor signs off, and the adversarial review that caught REQ-022. Human work is not the problem. Human work without a receipt is.

Deliberately not produced in Phase 1: architecture diagrams, technology choices, data models, API designs, story-level estimates, UI mockups. A requirement that names a technology ("the system shall use a message queue") is design leaking upstream — rewrite it as the behavior it wanted, and let Phase 2 choose the how.

04

An exhibit from epics.md — the four answers, and the epics they produced

Four questions — and deliberately nothing else

Phase 1's four answers at Harbor became six epics, each traced to an outcome and sequenced by which moves the metric first. The map was drafted day 1 by the requirements-analyst agent into epics.md, corrected by Maya, and sequenced by Luis on day 4.

IDEpicOutcome it servesSequence rationale
E-01Unified intake queue and assignmentSoftwareFirst — everything else lands in it; the auto-proof data model decision lives here
E-02Channel adapters (portal direct, email parsing, phone form)Software / BusinessSecond — kills manual re-keying and the no-SLA inbox (Q-11)
E-03Coverage verification against PolicyOneBusiness (the metric)Third — removes the built-in batch-window day from every claim
E-04Fast-path triage for simple claimsBusiness (the metric)Fourth — the 61% lever (Q-14); recommend-then-confirm per D-09
E-05Acknowledgments and notificationsBusiness / RegulatoryFifth — the 15-business-day clock (C-04), written-acknowledgment rule (Q-13)
E-06Metric instrumentationAll threeRuns alongside from the start — automates the S1 read, adds fast-path sub-metrics
Deliberately out of v1

Auto claims, SMS notifications, fraud scoring, payment-disbursement changes, and the adjuster dashboard rebuild — all named explicitly, so nobody assumes them into the build.

05

An exhibit from requirements.md — day 3's testability pass, and one error spec whole

The vague-line test: could two people build two different things?

On day 3, Nadia Brooks ran the testability pass over all 31 acceptance criteria. Five failed the vague-line test — lines like "promptly" and "clearly visible" — and went back to Maya for sharpening the same day, not quietly into the pile. An AI handed "respond promptly" picks a number for you, and it will not be the one you would have picked.

A line that failed
REQ-001, original acceptance criterion
"The new claim appears in the queue promptly and is clearly visible."
The same line, sharpened
REQ-001, after the testability pass
"A claim submitted via portal at 14:00 is visible in the queue with status 'new' by 14:05; same for phone-entered and parsed-email FNOL."

A representative slice of the 31 functional requirements — 12 of them P0 after the day-4 priority session:

IDRequirementPriEpicSourceAcceptance criteria (excerpt)
REQ-001Every FNOL, from any channel, appears in the unified queue within 5 minutes of receiptP0E-01DOC-003; Dee session 3/17A claim submitted via portal at 14:00 is visible with status "new" by 14:05; same for phone-entered and parsed-email FNOL
REQ-004Duplicate FNOL (same policy + loss date) is flagged and merged, never rejectedP0E-01Intake clerks session 3/17; D-07Second submission attaches to the existing claim with both sources recorded; submitter receives the existing claim number; no second claim number is ever issued
REQ-009Email FNOL is parsed into a queue entry within 15 minutes of arrivalP0E-02Q-11; Dee sessionAn email with attachments arriving 9:00 produces a queue entry with extracted fields and attachments linked by 9:15; parse failures route to a human triage view, never a dead letter
REQ-014Coverage status for a new claim is available the same business dayP0E-03CON-01 resolution; Gail/Marcus sessionFNOL received before 16:00 shows verified coverage status by 17:00 the same day, with the data's as-of timestamp displayed
REQ-019Fast-path-eligible claims are auto-identified and routed with a recommended decisionP0E-04Q-14; D-09A single-dwelling, no-injury, sub-$25k claim is tagged fast-path at intake and carries a recommendation the adjuster confirms or overrides with one action; override reasons are recorded
REQ-021Acknowledgment is dispatched within 3 business days of FNOL, in the form each state requiresP0E-05C-04; Q-13; compliance sessionFor the written-acknowledgment state: a letter or compliant email is generated and dispatch-logged; the portal confirmation screen alone never satisfies the requirement
REQ-022Bounced or failed acknowledgments fall back to postal dispatch and alert the intake teamP0E-05Day-5 adversarial reviewAn email bounce within the regulatory window triggers postal generation and a queue alert; the regulatory clock display reflects the remaining margin
REQ-027The acknowledgment-compliance figure (S1) is computed continuously and readable on demandP1E-06Success criteria S1; Priti sessionThe figure matches the manual quarterly calculation within 0.5 points on the validation sample

Every P0 requirement carries an error-behavior structure — the specs the plugin folds into requirements.md. REQ-014's, abridged:

REQ-014 — error behavior
Accepts: a claim with a policy number that exists in the nightly snapshot.
Returns: coverage status (verified / not-covered / needs-review) plus the as-of timestamp of the underlying data.
On policy not found: status "needs-review" with reason code; never silently "verified"; claim flagged for adjuster attention within the same business day.
On replica unavailable: status falls back to "pending verification"; the queue entry shows the degradation; intake is never blocked.
On stale data (snapshot older than 36h): status carries a staleness warning; claims in the written-acknowledgment state escalate rather than auto-proceed.
06

An exhibit from non-functional-requirements.md — seven targets, each with a measurement basis

"Fast" is an opinion — until you say where the number is read

Writing the quality targets surfaced a gap nobody had named: storm season. The Phase 0 sizing constraint was annual volume only — it said nothing about peaks. NFR-02 made the surge design-driving.

The gap the data lead's records exposed
Priti's 2024 catastrophe-event data
"A catastrophe event spikes intake to roughly 10x normal daily volume — about 1,600 claims a day — for a week straight."
The quality target it forced — NFR-02
Sized, and load-tested, for the surge
"Sized for 40,000 claims/yr steady state and a 10x storm surge (≈1,600/day for 7 consecutive days); load-tested at the surge profile before go-live."

Confirming the exact surge profile against 2024 catastrophe data became Q-16, carried into design week.

IDRequirementMeasurement basis
NFR-01Queue ingestion p95 (the time 95% of intakes beat) under 5 seconds per FNOLMeasured at the API gateway; read from the application monitoring dashboard
NFR-02Sized for 40,000 claims/yr steady state and a 10x storm surge (≈1,600/day for 7 consecutive days)Priti's 2024 catastrophe-event data; load test at surge profile before go-live
NFR-0399.5% availability during business hours (7:00–19:00 local, Mon–Sat)Uptime monitor on the intake endpoints; monthly figure on the ops dashboard
NFR-05No PII in model context outside the approved tenant path (C-05)Verified by the security review checklist per change touching claim data
NFR-07Every queue action is audit-logged with actor and timestampAudit log completeness check in the test suite; sampled quarterly by compliance
07

Day 4 — the priority session · Day 5 — the decisions and the scope-out

If everything is top priority, nothing is

The priority session, Luis driving, 90 minutes. The P0 budget — a hard cap on how many requirements may sit in the top tier — was set at 12; the room had 19 candidates. Luis cut seven. The budget held. None of this — the cap, the cut, the reasons — is written to any plugin file; it survives only in the priorities column and the scope-out list.

The cut, and how the epics sequenced

The pod set the budget before the session and announced it when the room opened; Luis ranked within it. Epics got sequenced by what moves the metric: queue first (everything depends on it), then coverage verification (kills the batch-window day), then fast-path (the 61% lever), then acknowledgments, with instrumentation running throughout. Stories were drafted with real stakeholders — Dee's intake team, Gail's adjusters, the compliance officer by name.

Seven requirements cut to fit the 12-slot budget — including the adjuster dashboard rebuild.
"We survive with the current screens one more quarter."
The decision log — nine surfaced, the two that mattered

All nine decisions surfaced this phase were answered inside it. The two with teeth:

IDDecisionAnswerWhoDays
D-07Duplicate FNOL (same policy + loss date): reject, queue separately, or merge?Flag and merge; never reject; submitter gets the existing claim numberLuis0
D-09Does the fast-path decide, or recommend?v1 recommends; an adjuster confirms with one click; revisit after a year of override dataLuis2

Day 5's traceability check claimed one casualty — a candidate SMS-notification requirement that traced to nothing but RFP boilerplate, confirmed by no human. It was cut and recorded in the scope-out list Karen saw at the review:

  • Auto claims (the data model must not preclude them — C-03 — but nothing ships for them in v1)
  • SMS notifications (the RFP boilerplate requirement that traced to nothing — cut on day 5)
  • Fraud scoring and ML-based triage (fast-path uses explicit rules, not a model)
  • Payment disbursement changes (intake through decision only; payment flows untouched)
  • The adjuster dashboard rebuild (cut in the priority session; current screens survive v1)
Two catches the authors couldn't see

The day-5 adversarial review — reviewers who wrote none of the draft — found a missing failure path (a bounced acknowledgment against a written-acknowledgment state rule → REQ-022, bounce-to-postal) and a hidden conflict (a "recommend" fast-path could let a claim sit past the regulatory clock → the clock added to the fast-path escalation rule). Both were caught here, for the price of an afternoon, instead of in the build.

08

The handoff — and the architectural questions that travel with it

What Phase 2 receives

A phase ends by handing the next one a package, not a feeling. Everything below crosses the boundary into Design: the signed requirements, the quality targets, the epics — and, carried in phase2-handoff.md, the questions the requirements raise but must not answer, because answering them is Design's job.

Crosses into Phase 2 phase2-handoff.md requirements.md non-functional-requirements.md epics.md the decision log → open questions Q-15, Q-16 the scope-out record

The architectural questions Design must answer

This is the thread that ties the two phases together, and the one place a name in this handoff reaches directly into the next phase's first command. The requirements raise four questions they deliberately do not answer — each recorded as an AQ-NN in phase2-handoff.md, under its “What Design Must Address” section. Phase 2's Step 0 reads exactly these out of the handoff and turns each into a signed ADR before it may write anything else.

AQThe question the requirements raiseRaised byBecomes
AQ-01Where does a coverage check get its answer, given the once-a-night PolicyOne sync?REQ-014 (same-day) vs C-02/CON-01 (nightly batch)ADR-001
AQ-02What shape is the claim store, so duplicate-merge and auto-proof are both honored?REQ-004/D-07, C-03, NFR-07ADR-002
AQ-03How does intake absorb a 10x storm surge without dropping claims?NFR-02ADR-003
AQ-04How is a free-text email FNOL turned into a structured queue entry?REQ-009ADR-004

An AQ that reaches the end of design week with no ADR is a gate failure. That is how Phase 1's homework becomes Phase 2's output — and until this page said so, no companion page named the connection.

The open questions, carried under their original IDs

IDQuestionOwnerDue
Q-15Will security approve direct read access to the PolicyOne nightly snapshot replica, and under what controls?Dan KowalskiDesign week, day 2
Q-16What exactly does a storm surge look like in the 2024 catastrophe data (peak day, duration, channel mix)?Priti ShahDesign week, day 2
Recommended design starting point: the claim data model and queue — three constraints converge on it (auto-proof C-03, duplicate-merge D-07, audit logging) and every epic depends on it.

Phase 0 is signed and someone has handed you Phase 1. This page is what you actually type, in order, and what you do between the typing.

Phase 1 takes about a week. It is the drafting-heaviest phase of the whole engagement, and the thing that decides whether it lands on time is not the typing — it's whether the product owner answers questions inside two days. Read this once end to end before you start.

Before you type anything

What you need first

Phase 1 has an entry gate, not just an exit gate. Two of these come out of Phase 0 and you cannot fake them; the rest are people.

  • Phase 0 actually closed. /sdlc-status should say Phase 1. The registry's entry gate for this phase is two lines: Phase 0's exit gate passed, and phase1-handoff.md has been read.
  • phase1-handoff.md, read — not skimmed. Its open questions carry numbered IDs (Q-NN). Every one must be answered or formally escalated before you write requirements. They are inputs, not background reading.
  • The document registry, if Phase 0 ran intake. That's the DOC-NNN ID list. Requirements have to cite it — a P0 that came out of a client document and doesn't name which one fails the phase's own exit criteria.
  • The product owner, booked for the week. Elicitation, the decision list on a two-business-day answer clock, the priority session, sign-off. This is the phase their committed hours were written for.
  • Domain experts, one per epic area. 60–90 minutes each. Plus the data owner if Phase 0 found the success metric can't be read yet, and compliance/security if the domain is regulated.
  • A number for the top priority tier, decided before the priority session. How many P0s the pod can credibly deliver in the first stretch of Build. You set it; the PO ranks inside it.
The mistake new people make

Writing requirements while Phase 0's open questions are still open. Every unanswered Q-NN becomes an assumption buried inside a requirement, and nobody finds it until the build disagrees with the client. Answer them first — that's why the phase opens with a gate that asks.

01

Type this — then answer four questions before anything gets written

Open the phase

You type /sdlc

What happens: it reads .sdlc/state.yaml, loads this phase's definition, and prints the phase purpose, any resolved questions it can find in Phase 0's handoff, what to do next, a checklist of required artifacts marked exists or missing, the exit criteria, and a reminder block of the gate commands. It changes nothing.

Then Phase 1's first workflow step runs, and it is a blocking human gate. Claude puts four questions to you through a real prompt, not chat text: are the Q-NN open questions from Discovery answered; is the P0/P1/P2 prioritization clear; are there requirements you expect that Discovery never captured; and — if intake ran — does the document registry imply requirements the handoff missed. No requirement gets written until you confirm scope.

What you do: answer from the handoff document and from the PO, with both in front of you. "I think so" is not an answer to question one.

The output also prints a "Skills to Use" line — the registry names /deep-project and /plan for this phase. Those are separate skills, not part of the plugin. If they aren't installed, ignore that line; nothing depends on it.

Don't move on until: all four gate questions have real answers and you can name the epic areas you're about to run sessions for.

02

Nothing to type — this is the week's real work

Run the elicitation sessions

You type nothing — you're in a room, or on a call

What you do first: have Claude draft the candidate epic map from the Phase 0 artifacts and the document corpus — 4–8 epics, each traced to one of the outcomes, each with a one-paragraph intent. Correct it. Then use it to plan sessions: one per epic area, the right domain expert in each. If Phase 0 found the success metric can't be read end to end, the instrumentation epic goes on the map now and goes first.

What happens in the sessions: 60–90 minutes each, you running them. Claude preps the question list from the corpus and the epic intent beforehand, and structures the notes afterwards into draft requirements with stable IDs, each traced back to the session or the document it came from.

Also running this week: read-only feasibility checks against the risks the handoff flagged — is that API inventory still current, does the integration surface exist as documented. Anything the checks contradict has to be reconciled before the requirement that depends on it is signed.

Interview the doers, not just the managers

The intake clerk knows the duplicate-claim workaround. The manager knows the org chart. If every attendee has "manager" in their title, your requirements describe what the org chart believes, not what the work actually is.

The plugin ships a /sdlc-spike command for the harder version of this — a boxed, read-only investigation of a question nobody can answer yet, which commits a written finding rather than code. It is real and it is in the plugin, but it is missing from the command reference, so treat its exact flow as something to read in commands/sdlc-spike.md before you lean on it.

03

Back at the keyboard — and there is no one command for this

Draft the three requirement documents

Paste your session notes into Claude and work through the phase's drafting steps. There is no /sdlc-requirements. Claude writes; you correct. Do it the same day the sessions happened.

FileWhat has to be in it
requirements.mdA summary table by priority and domain; the functional requirements as a table — ID, requirement, priority, domain, source, source document(s); business rules kept separate from requirements; a traceability matrix linking every P0/P1 to a Phase 0 pain
non-functional-requirements.mdPerformance, security, scalability, reliability, maintainability. Each NFR as a row — ID, requirement, metric, test method, priority, measurement basis
epics.mdAn epic for every P0 and P1. "As a … I want … so that …", with at least two Given/When/Then scenarios — happy path and an error case — and the requirement ID it came from

The two rules that catch everyone:

  • Every P0 and P1 needs Accepts / Returns / Errors. What valid input it expects, what it produces on success, and what it does on each failure — named, one by one. "Handles invalid input gracefully" is not a specification. "If the email format is invalid, return 400 with a field-level error naming the invalid field" is.
  • Every numeric NFR threshold needs a measurement basis. One of four: Measured (cite the profiling run), Industry standard (cite the reference), Contractual (cite the document), or [aspirational — validate in the Build loop]. Aspirational is honest and allowed. A number with no stated basis, treated as validated, is not.
Design wearing a requirements costume

"The system SHALL use a message queue" is not a requirement, it's a Phase 2 decision that snuck upstream and closed off options before anyone weighed them. Rewrite it as the behavior that wanted it: "intake must accept submissions while downstream systems are unavailable." Same for anything naming a database, a framework, or a hosting model.

The plugin ships starter templates for these under templates/phases/01-requirements/, but nothing copies them into your project — they are reference, not scaffolding. Read them for the expected table shapes.

04

Nothing to type — and nothing in the plugin enforces the outcome

Run the priority session

You type nothing — 90 minutes, the PO driving

What you do: announce the top-tier budget when the session opens — the number you set before anyone walked in. The pod advises on cost and risk; the PO assigns every priority. Then sequence the epics against the outcome: which one moves the success metric first. Then draft the stories under each epic, each carrying a named stakeholder and why they need it.

What Claude does not do here: set a priority, accept a criterion, or make a scope call. If there's no client PO and you're covering the role, every one of those decisions gets logged for the sponsor to ratify — made and written down, not just made.

Everything is P0, and nothing checks that it isn't

Priority inflation is the default state of nature, and it is the failure mode this phase is most likely to die of. Nothing in the plugin verifies that the top tier respected its budget, or that a human rather than Claude assigned the priorities — there isn't even a prose check for it in the exit gate. The budget holds because you hold it.

Don't move on until: no story carries an invented persona. If nobody named the stakeholder in a session, the story doesn't get one made up for it.

05

Type nothing — but this file will block your gate

Write the decision list by hand

You type nothing — no command writes this file

What it is: every product decision this phase surfaced and could not answer. Not topics — questions with their options. "Fail open or fail closed on a duplicate submission?" is a decision list entry. "Duplicate handling" is not.

What each entry needs: a stable D-NN ID that blocked specs can point at; the decision stated as a question with its options; a named human who can actually answer it, not a role; the date raised and the date due on the agreed clock; and the answer when it arrives, with who gave it and when.

Why it matters more than it looks: a spec cannot enter the Build loop with an open decision belonging to its story. If it does, the agent picks an answer — silently, plausibly, on a Tuesday, and correctly-looking. This file is what stops that.

The file nothing creates for you

decision-list.md is a required artifact in the phase registry, so /sdlc-gate blocks without it. No command writes it and no template ships under that name. The template that does ship is decision-log.md, which calls itself optional and lives at .sdlc/decision-log.md as a phase-spanning file that /sdlc-status reads. They are not the same thing and one does not satisfy the other. Write decision-list.md into this phase's artifact folder yourself.

If the work genuinely didn't happen, the file still has to exist, containing a line in the form WAIVED: <name> — <reason>. The gate accepts it and reports it, by name, in the record the approver signs. A missing file still blocks. The escape is from the work, never from the record.

06

Type this — fresh eyes before the gate, not after

Attack your own requirements

You type /sdlc-review --adversarial

What happens: a reviewer agent that did not write the draft goes at this phase's artifacts and challenges every assumption. It writes review-report.md into the phase's artifact folder with CRITICAL / HIGH / MEDIUM / LOW findings, each naming a specific artifact and carrying an actionable recommendation. With no flag it runs --council instead, which reviews from the architecture, product, quality and security angles at once; --all runs everything and combines the report.

What you do: fix the CRITICAL and HIGH findings now. The review changes no state and blocks nothing — it is advisory by design — but those two levels usually predict exactly what the gate is about to fail on. Run your own testability pass alongside it: take every acceptance criterion and ask whether two people could build different things from that line. If yes, it goes back to be rewritten, not quietly into the pile.

You now have review-report.md — the agent's findings adversarial-review-record.md — the receipt; you write it, nothing does

Worth knowing: the phase definition says the approver is asked about the optional records — the adversarial review record and the scope-out record — at sign-off. Nothing in the gate or in /sdlc-next currently asks. If you want them in front of the person signing, put them there yourself.

07

Type nothing — but get this section right or Phase 2 improvises

Write the handoff, and the AQ list inside it

phase2-handoff.md carries the requirements summary, what the NFRs imply for design, the decisions you made and why, the product questions still open, the risks worth watching, and a recommended design starting point. One section inside it does more work than all the rest.

The section is called "What Design Must Address." It is a numbered list of architectural questions, AQ-01 onward, one line each, each citing the REQ and NFR IDs that raised it. For example: does the intake API need idempotency, or can duplicates be reconciled downstream? (driven by REQ-014, NFR-003).

The rules: one question per AQ — if answering it takes two decisions, it's two AQs. It's architectural if the answer changes the shape of the system: a component boundary, a data flow, a technology choice, a consistency or failure model. If it only changes what a screen says, it's a product question and belongs under open questions instead. And do not answer them here — an AQ that arrives pre-answered has skipped the gate that exists to get a human's name on it.

Also carry forward: Phase 0's open questions, under their original Q-NN IDs. Renumbering them breaks the trail back to who raised what.

Why a thin AQ list is expensive

Phase 2 opens with a blocking human gate that reads this list and has no other input. It pulls each AQ-NN, puts two or three concrete options to a human, and the answers become the ADRs the rest of the engagement rests on. If the section is thin, Claude improvises the architectural questions instead — and the signed decisions trace back to identifiers nobody ever assigned.

08

Type this — the machine checks your work

Run the gate

You type /sdlc-gate

What happens: seven gates run. Required artifacts exist (G1). They're non-empty and free of placeholder markers — TODO, TBD, ${, PLACEHOLDER, [INSERT (G2). Metrics, compliance, and cross-phase drift follow (G3–G5), then content quality and cross-references (G6). Last, G7 prints the phase's own exit conditions as prose for the human who signs — it never passes or fails them. Then it writes an HTML report and opens it in your browser, and records the results in state. It never advances the phase.

What you do: fix every MUST failure and run it again until it's clean. The usual culprits are a leftover TODO and a missing decision-list.md. If it offers to auto-repair the fixable issues, that's a repair agent, not magic — read what it changed.

Before you run it: the command checks that a visual report exists at .sdlc/reports/01-requirements-visual.html — the phase's registry slug, not the name the phase definition gives (phase01-visual.html), which will not be found. Same for the generated report: it lands at .sdlc/reports/01-requirements-report.html. Save yours under the slug names.

Also available: /sdlc-phase-report regenerates that HTML any time, and /sdlc-enhance writes a plain-language version of the artifacts for stakeholders to read before the review.

What the gate does NOT check

The four exit conditions it prints — the AQ list, no unresolved P0 conflicts, every NFR threshold's measurement basis, every P0 tracing to a Phase 0 pain — are reported, never enforced. Beyond those, four things the standard requires to close this phase have nothing behind them at all: that error behavior is spelled out for every top-tier operation, that the PO assigned the priorities and the top tier held its budget, that every open decision has a named owner (the file's existence is checked; its contents aren't), and that a scope-out record exists and the sponsor has seen it. A green gate is not a finished phase. Walk those four yourself.

09

Type this — last thing in the phase

Get the sign-off and advance

You type /sdlc-next

Before you type it: run the phase review. The PO confirms the requirements say what they meant. The sponsor sees the scope-out list with their own eyes — that page is what prevents the month-four "I assumed that was included" conversation. Schedule the first biweekly steering while everyone is still in the room.

What happens: it re-runs the gates. If a MUST gate fails it stops, shows the blockers, generates the report anyway, and offers repair. If they pass, it presents the phase summary and asks you to confirm out loud before it moves anything. It then offers — optionally — to record per-discipline sign-offs by name. Skipping that advances exactly as before; whatever names you give get written into the sign-off record. Finally it condenses this phase's artifacts into a frozen summary layer later phases read instead of the full documents, and advances the project to Phase 2.

What you do: give it real names. The agent only records what it is told, and "the team approved" is not a name.

Phase 1 is done when state.yaml says Phase 2 the PO and the sponsor have signed the decision list is empty or every survivor has an owner and a due date everything is committed

Keep these handy

Commands you'll use constantly

Type thisWhen
/sdlcStart of every work session. Tells you what to do next and which artifacts are still missing.
/sdlc-statusAny time you're lost. Also surfaces open decisions and flags any that have blown their clock.
/sdlc-reviewBefore the gate. --adversarial here; --council if you want all four viewpoints at once.
/sdlc-coachYou're stuck and want to be walked through it conversationally instead of following a list.

Rule of thumb for the whole phase: Claude drafts and interrogates; humans decide and own. Claude never sets a priority, accepts a criterion, or makes a scope call — and if you let it, the gate will not catch you, because none of those three has a check behind it.

Reference · Phase 1 · Requirements

The precise mechanics — the exact roles, calendar, artifacts, gate, and 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 1 answers four questions, and nothing else. Architecture, technology selection, data modeling, and estimation are deliberately out of scope — that work belongs to Phase 2 and beyond. A requirement says what and how well, never how.

  1. What must the system do? (functional requirements with testable acceptance criteria)
  2. How well must it do it? (non-functional requirements, each with a measurement basis)
  3. In what order does value ship? (epics sequenced against the outcome; priorities set by the PO)
  4. What is explicitly out? (scope boundaries, written down before pressure arrives)

The human / AI contract for this phase

Human drivesClaude doesMandatory human stops
PO sets priorities and accepts requirements; Pod Lead runs elicitation, owns requirement quality and the decision list.Drafts the candidate epic map and requirements from the Phase 0 artifacts and corpus (every one carrying a source trace); regenerates the decision list continuously; cross-checks against the constitution and constraints; flags requirements that trace to nothing; drafts acceptance criteria and error behavior.Claude never sets a priority, accepts a criterion, or makes a scope call. In proxy mode those are logged, not just made. Phase advance.

Who is involved

Our side

PersonLoadWorkstream
Pod Lead80–100%Runs the phase — elicitation sessions, requirement quality, the decision list, priority-session facilitation, the handoff
Orchestrators30–50%Arrive for real — structure elicitation notes into draft requirements, run read-only feasibility spikes against handoff risks, sanity-check that requirements are buildable
Quality Engineer30–40%The testability conscience — every acceptance criterion through the vague-line test, every NFR checked for a real measurement basis, the traceability structure
Setup Owner30–50%Enablement runs ahead — pipeline groundwork and Phase 3 environment prep, plus answering feasibility questions the requirements raise

Client side

PersonNeeded forHow much
Product Owner (PO)The whole phase — elicitation, the decision list (2-business-day clock), the priority session, sign-offTheir committed hours, fully spent — the phase the PO clause was written for
Domain expertsElicitation sessions, one per epic area60–90 min each
Data ownerThe instrumentation epic (any metric Phase 0 showed can't be read yet)One session
Compliance / securityRegulatory requirements become explicit, testable entriesOne session if regulated
SponsorOne mid-week checkpoint (day 3) plus the phase review; biweekly steering starts at phase end~1.5 hours total

Proxy mode (no client PO): the Pod Lead owns stories and priorities, every product decision goes in the decision log, and the sponsor ratifies the log at the phase review. Same calendar; the decision-list clock binds the Pod Lead instead. Add 2–3 days for ratification latency.

The five-day calendar

The default is 5 business days, assuming Phase 0 did its job. It stretches to 8–10 when the epic count is large, the domain is heavily regulated, or proxy mode adds ratification latency.

DayFocusWhat happensTooling
1Handoff intake & elicitation planWork the open questions Phase 0 carried; draft the candidate epic map (4–8 epics, each traced to an outcome); plan one session per epic area; orchestrators start read-only feasibility spikes/sdlc-coachrequirements-analyst agent
2ElicitationWorking sessions with domain experts and the PO, one per epic area, 60–90 min; Claude preps question lists and structures notes into draft functional requirements with stable IDs and source tracesNo plugin command (human sessions)
3Full draft & decision listComplete draft — functional requirements with acceptance criteria, NFRs with measurement bases; decision list regenerates and the PO starts working it; QE runs the testability pass; 30-min sponsor checkpoint/sdlc-coachrequirements-analyst agent
4Priorities & storiesThe 90-min priority session (PO ranks within the top-tier budget); epics sequenced against the outcome; user stories drafted with real stakeholders; error behavior spelled out for the top two tiers; spike results reconciled/sdlc-coach (stories + error specs); priority session has no plugin command
5Verification, review & gateTraceability check; structured adversarial review; automated gate check; Phase 2 handoff drafted; phase review & sign-off; first biweekly steering scheduled/sdlc-review --adversarialmulti-reviewer; /sdlc-gatecheck_gates.py; /sdlc-phase-reportgenerate_phase_report.py; /sdlc-nextadvance_phase.py

When the PO can't keep the 2-day clock, escalate to the sponsor by name — the clock is in the SOW. When elicitation keeps finding new epics past 8, the outcome is too broad: take it to the sponsor as a scope conversation, not a longer phase.

The artifacts

All of it lands in the requirements artifacts folder of the delivery repo, committed, by the gate run.

ArtifactDrafted by / Owned byDone means
Functional requirementsClaude / Pod Lead (content), PO (acceptance)Every requirement: stable ID, testable acceptance criteria that pass the vague-line test, a PO-assigned priority, a source trace, an outcome trace
Non-functional requirements (NFRs)Claude / Pod Lead + QEEvery NFR has a number, a measurement method, and a named place it will be read from — no "the system shall be fast"
Epic mapClaude (candidates) / PO4–8 epics, each traced to an outcome, sequenced by which moves the metric first; instrumentation epic included if the metric needs it
User storiesClaude (drafts) / POStories under epics with real stakeholder justifications — no invented personas
Error behavior specs (top tiers)Claude (drafts) / Pod Lead + QEFor every top-priority operation: what it accepts, what it returns, what it does on each failure
Decision list / decision logClaude (generated) / PO (answers) or Pod Lead (proxy, ratified)Empty, or every survivor is a numbered open question with an owner
Traceability matrixClaude / QERequirement → source and requirement → outcome both populated for the top tiers
Feasibility spike notesOrchestrators / Pod LeadEach handoff risk verified or converted into a requirement change / design risk
Phase 2 handoffClaude / Pod LeadSummary, decisions with rationale, numbered open questions with owners, design risks, recommended starting point
Scope-out recordPod Lead / Sponsor (has seen it)The explicit not-in-v1 list, shown at the phase review
Narrative companion (optional)Claude / Pod Lead (edits)The requirements retold for stakeholders, human-edited before any client sees it

Deliberately not produced: architecture diagrams, technology choices, data models, API designs, story-level estimates, UI mockups. A requirement that names a technology ("the system shall use a message queue") is design leaking upstream — rewrite it as the behavior it wanted ("intake must accept submissions during downstream outages").

The cadences

RhythmWhoWhat
Daily 15-min pod syncWhole podElicitation findings, decision-list status, spike results. Coordination, not ceremony
The decision-list clockPO + Pod LeadEvery open decision visible with its age; 2-business-day turnaround per the SOW; breaches escalate to the sponsor by name
PO working sessionsPO + Pod Lead2–3 across the week: elicitation (day 2), priority session (day 4), sign-off (day 5)
Anchor eventsPer calendarElicitation day (2), priority session (4), gate and review (5). Move for people, never for polish
Biweekly steering beginsSponsor + Pod LeadFirst one at the end of this phase; from here through Build it runs every two weeks with a live demo once there's software to show

The exit gate

Phase 1 closes when all of these are true, verified at the phase review:

  • The automated gate checks pass — artifacts exist, are complete, contain no placeholders
  • Every top-priority requirement has testable acceptance criteria, a source trace, and an outcome trace
  • Every non-functional requirement has a measurement basis (number, method, named source)
  • Every top-tier operation has its error behavior spelled out
  • Priorities were assigned by the PO (or logged and ratified in proxy mode) — and the top tier respected its budget
  • The decision list is empty, or every survivor is a numbered open question with an owner and a due date
  • The scope-out record exists and the sponsor has seen it
  • The Phase 2 handoff carries the open questions under their original IDs
  • A named human (PO + sponsor side) approved the advance — gates report, humans decide

What goes wrong

  • Everything is P0. Priority inflation is the default state of nature. The defense is a budget for the top tier, enforced in the priority session — the PO ranks within it, and the pod refuses to start a phase where the budget is blown.
  • Design wearing a requirements costume. "Shall use a queue," "shall be microservices." Each forecloses Phase 2 before it starts. Rewrite as the behavior that motivated it.
  • The corpus treated as requirements. The RFP is evidence, not a baseline. Requirements that only trace to the RFP and were never confirmed by a human are candidates, not commitments.
  • The untestable criterion. "Intuitive," "robust," "fast." The vague-line test exists for exactly this; the QE's testability pass is the enforcement point, not the build loop three weeks later.
  • NFR theater. Non-functional requirements with no measurement basis are wishes. If nobody can say where the number will be read, the NFR isn't done.
  • Silent proxy drift. In proxy mode, the pod starts making product calls without logging them — each one a liability that surfaces at the worst time. The decision log is cheap; the month-six dispute is not.
  • Elicitation that only hears managers. The people who live the process know where the bodies are buried. If every attendee has "manager" in their title, the requirements describe the org chart's beliefs, not the work.
  • The decision-list stall. The PO's clock slips, the pod fills the silence with guesses, and Phase 1 quietly becomes proxy mode without the rider. Escalate the clock breach instead — it's in the SOW precisely so this moment has teeth.