Ambiguity → Requirements
- Write a problem statement the customer would recognize as their own words, sharpened
- Separate functional from non-functional requirements and make every one testable
- Maintain an explicit assumptions-and-constraints log with owners and verification dates
- Scope ruthlessly into v0 / v1 / later, with a defensible rationale for every deferral
- Transform a real discovery transcript into a complete requirements document
| Spaced-rep warm-up: due cards incl. Day 163 rules & slots | 10 min |
| ELI5 + tech read; write the eight sections from memory | 15 min |
| Guided: build the Harbor & Vane doc, all eight sections | 45 min |
| Practice: adversarial IT-director review + resolutions | 20 min |
| Project: finalize doc + extract the reusable template | 15 min |
| Quiz + flashcards | 10 min |
Builds on: Day 163 — Discovery & the Mom Test — the Harbor & Vane transcript · Day 48 — System design method — requirements first · Day 134 — Golden sets — testable criteria
A family tells an architect: "we want the house to feel more open, and cooking is chaos when guests come." That is fog — true, felt, and unbuildable. The architect's craft is converting fog into blueprints WITHOUT losing the family's meaning: "remove the wall between kitchen and dining (structural engineer to confirm load-bearing status — assumption, verify by Friday); island with seating for four; done means: two people can cook while four sit, and the oven opens fully with someone seated." Notice what happened: feelings became checkable statements, each guess got labeled as a guess with a deadline, and the swimming pool the teenager wanted went to a "later" list with a reason attached, not a rejection.
Yesterday's discovery call left you with exactly such fog: Dana's stories about re-keying PDFs, a $40K exclusion miss, a 48-hour promise kept 70% of the time. Today you draft the blueprint: a requirements doc where every line is testable ("extraction of eight named fields at ≥95% accuracy on 50 sample claims" — not "accurate extraction"), every assumption is logged with an owner, and the v0 line is drawn where the pilot can prove value in six weeks. The doc is also a mirror: the customer reads it and says "yes, that's our problem" — or corrects you now, while corrections cost nothing.
Requirements docs are where FDE engagements are won or quietly doomed. Vague requirements produce the classic pilot death: three months in, the customer says "this isn't what we meant," and nobody can prove otherwise because nothing was testable. A sharp doc does the opposite — it converts Day 163's discovery into acceptance criteria that Day 140-style evals can literally execute, makes scope creep visible ("that's a v1 item, here's the log"), and becomes the contract-shaped artifact your Day 165 proposal prices. Interviewers for FDE and senior AI roles hand you a messy brief and watch for exactly this conversion skill.
Guided practice
Walk the template against Harbor & Vane — sections 1–4
25 minOpen your annotated Day 163 transcript and requirements_harbor_vane.md with the eight-section template. Build the first four sections:
- Problem statement. Draft it, then run the checks: Is it in Dana's vocabulary (claims intake, loss runs, cycle time — not "document AI")? Does it quantify from evidence (40–60 complex claims/week, ~2.5h each, 70% on a 48h SLA, one $40K exclusion miss)? Does it name who hurts (Priya's team daily; Dana's dashboard; Marcus's budget)? Zero solution words?
- Goals & non-goals. One primary goal tied to the SLA metric. Then at least three non-goals — practice the knife: simple auto claims out; writing INTO ClaimCore out for v0 (review-screen only — why? the $40K story means a human must stay in the loop, and IT trust must be earned); replacing the adjuster relationship out.
- Functional requirements. Write FR-1 through FR-6 minimum, MoSCoW-tagged, each with its transcript-line citation. Must-haves should cover: PDF intake from the claims inbox, eight-field extraction to a review screen, policy lookup cross-check, exclusion/endorsement flagging (that is the $40K line — arguably the highest-value FR), human confirm-before-commit.
- Non-functional requirements. At least five, each with number + measurement: field accuracy (how will you measure it? — a labeled sample, i.e., a golden set), processing latency, PII handling, audit trail ("every extraction traceable to source page" — Day 136's citation discipline appearing in a contract), and availability (business hours only for a pilot is FINE, and writing that down is the skill).
Sections 5–8: assumptions, scope ladder, acceptance criteria
20 min- Constraints. List five from the transcript. (AS400 read-only; emailed PDFs, formats uncontrolled; IT approval gate with OCR scar tissue; brokers won't change behavior; pilot must fit ops budget cycle — Marcus's.)
- Assumptions log. Table at least six. Seed set to beat: PDF quality distribution; volume seasonality; ClaimCore has an API or at least an import path (nobody asked! — that is an assumption with a deadline, owner: you, verify: ask IT this week); Dana can grant sample data access; the 8 fields cover 90% of re-keying time; Marcus's budget window.
- Scope ladder. v0 = the six-week pilot: extraction + review screen + exclusion flags on ONE claim type (water damage — you have evidence for it), measured against AC-1..3. v1 = more claim types, ClaimCore write-back behind approvals, exclusion-rule library. Later = auto-drafted broker responses, simple-auto automation. Every deferral gets a reason ("write-back deferred until extraction accuracy is proven and IT trust established").
- Acceptance criteria. Write AC-1 through AC-4, then apply the two tests: could a neutral third party run this as an exam and get an unambiguous pass/fail? And — does Dana's team help DEFINE the labeled sample? (If the customer co-owns the golden set, the pilot cannot end in "that's not what we meant.")
- Read the whole doc top to bottom as Dana. Mark any line she would frown at; fix or flag it.
On your own
The adversarial review
20 minSwap hats: you are now Harbor & Vane's skeptical IT director (the one still paying for OCR licenses), reviewing this requirements doc line by line in front of your boss. Write the seven hardest review comments you can — attack untestable lines, unverified assumptions, security silence, and anything that smells like the last pilot. Then, back in the FDE hat, resolve every comment: edit the doc or add a logged response.
Constraints: at least two comments must attack real weaknesses you left in (there are always some); at least one must be about data access/PII (transcript says claims contain client details — where does your doc handle Day 159's questions?); at least one must be unfair — and your response must de-escalate it with evidence rather than winning the argument.
Hints: strong IT-director openers — "what happens to our data, exactly, hop by hop?", "the last vendor also promised 95%", "who pays when the extraction is wrong?"
The requirements doc + reusable template
Finalize and commit two artifacts: (1) docs/requirements_harbor_vane.md — the complete eight-section document from guided work, revised through the adversarial review, with every FR traceable and every AC executable; (2) docs/templates/requirements_template.md — the blank eight-section template with your own one-line quality checks per section (e.g. under Acceptance Criteria: "could a third party run this as an exam?"). The template is a permanent tool: Day 168's simulation and Day 174's full-cycle sim both start from it, and it belongs in your portfolio next to the code.
Common mistakes & misconceptions
- Writing solutions as requirements. "Use RAG with a vector DB" is your design; "answers must cite the specific policy clause" is their requirement. Mechanisms leak, behaviors bind.
- Untestable NFRs: "fast, secure, user-friendly, scalable." Each needs a number and a measurement method or it is decoration that a dispute will ignore.
- Burying assumptions inside confident sentences. "ClaimCore's API will receive the data" — nobody verified ClaimCore HAS an API. Unlogged assumptions become week-4 crises.
- Scoping v0 by ease instead of by the buyer's metric. A pilot that is easy to build but doesn't move cycle-time gives Marcus nothing to fund v1 with.
- Writing acceptance criteria the customer didn't co-own. If Dana's team doesn't help define the labeled sample, "95% accurate" will be relitigated at pilot end.
- Polishing the doc in isolation for a week. It is a conversation artifact — ship the draft fast, let the customer's corrections improve it while corrections are still free.
Q1. Which is a correctly written non-functional requirement?
Q2. "ClaimCore will accept our extracted data" appears in your doc as a plain statement. What should it be instead?
Q3. Why should v0 exclude ClaimCore write-back even though it is the most automation-valuable feature?
Go deeper — curated resources
- MoSCoW under pressure — The tags only bite when the customer pushes a "could" into "must." Rehearse the response: "yes — which current must moves out to make room?" Scope is a conservation law; Day 171 trains the conversation.
- Complete eight-section doc committed with full traceability
- Assumptions log has ≥6 owned, dated rows
- Adversarial review run with all comments resolved
- Reusable template extracted; quiz ≥ 2/3
← Back: The acceptance criteria are Day 134's exam-before-the-student principle in contract form, the doc structure extends Day 48's requirements-first discipline, and every quantity traces to Day 163's transcript evidence.
Forward →: Tomorrow this doc gets priced and argued for in a proposal (Day 165). Day 166 prototypes only what the v0 scope permits, Day 168 repeats the transcript→doc conversion under simulation, and Day 173 turns the same numbers into ROI.
Unlocks: D165 Proposals & Architecture Docs · D166 Rapid Prototyping · D168 Week 24 Checkpoint: FDE Simulation I