Before you write a single line of code, you have to find the actual problem. Maria says her team is drowning and wonders if AI can help. Your job is to turn that sentence into something you can build against.
Evidence pack #1 — the email that starts every engagement.
From: Maria Alvarez, Director of Operations
To: you
Subject: help with 311 backlog?
"Hi — we are drowning over here. We have something like 40,000 unresolved service requests in the queue and my team can't keep up. Somebody on the council asked whether AI can help. Can we talk this week? — Maria"
That's the whole brief. No spec, no budget line, no definition of "help." And yet you are expected to show up with a plan. Discovery is the craft of turning this email into a problem statement sharp enough to build on.
What the operators actually see
Before theorizing about Maria's email, look at the thing her team actually works from every day. The 311 data is public and free — you can pull it yourself right now:
Real command, real output. The oldest still-open request in the NYC 311 feed, pulled live from the public API:
curl "https://data.cityofnewyork.us/resource/erm2-nwe9.json?\$limit=1&\$where=status in('Open')&\$order=created_date"{
"unique_key": "45288020",
"created_date": "2020-01-01T13:01:00.000",
"agency": "DSNY",
"complaint_type": "Electronics Waste Appointment",
"status": "Open",
"borough": "QUEENS",
"incident_zip": "11412"
}Read that record like an operator would. Status: Open. Created: January 1, 2020. This electronics-waste pickup has been sitting untouched for years — and nothing in the row says so. No "days open" column. No priority flag. No "who's handling it." Operators get rows like this in a raw export, sort by received date, and start at the top. That's the whole triage process.
Triage — borrowed from emergency medicine — is the job of deciding what to handle first. Right now Maria's team triages blind: oldest-first, hoping nothing urgent is buried. When Dev says "don't trust the data," he means fields like incident_zip — real records carry wrong or missing ZIP codes, so sorting or grouping on them quietly misleads. And complaint types elsewhere in the feed read like "Plants- Noise Related Problems (PN1)": internal agency codes operators decode from memory. The data works, but it was never designed for a human deciding what matters.
Why vague requests are the norm
Now re-read Maria's email and notice what's missing. No users — who does the triaging? No workflow — how does a request move from "received" to "resolved"? No metric — what does "not drowning" look like in numbers? And "AI" is a solution proposed before the problem is defined. Maybe AI is the answer. Maybe it's a filterable queue and a daily export. Nobody can know yet — including Maria.
That is the normal starting condition of almost every engagement. Stakeholders describe pain, not requirements — urgency ("we're drowning"), a big-feeling number ("40,000"), a technology someone mentioned ("maybe AI"). Build on that at face value and you solve the wrong problem with real code: the most expensive mistake in the field.
Everything in this guide starts here. A wrong problem statement poisons every step downstream.
Three distinctions: symptom, problem, solution
Discovery runs on three ideas that are easy to confuse and expensive to mix up. Watch each one land on record 45288020 above:
| Concept | What it is |
|---|---|
| Symptom | Something observable and painful — "40,000 unresolved requests"; a 2020 e-waste pickup still open |
| Problem | The underlying cause you can intervene on — "operators can't see which requests are overdue, so they work oldest-first" |
| Solution | A specific intervention — "an AI priority queue," "a dashboard," "a spreadsheet filter" |
Symptoms tell you where to dig — record 45288020 is a symptom, sitting there in plain JSON. But you can never build a symptom; you can only build something that addresses a problem. And a solution is a hypothesis about which intervention fixes the problem, to be validated — not a request to be obeyed. When Maria says "maybe AI," she is handing you a solution-shaped guess. Walk it backward: what problem would AI have to solve for it to matter? If nobody can answer that, you don't have a problem statement yet.
Who to talk to, and what to ask
One stakeholder is never enough. Maria can tell you the pain, but she lives one layer above the work. The people doing the work see different problems than the people managing it — and the people constraining it see problems nobody else mentions. Add at least one frontline operator — the person actually clicking through requests all day. Their answers will contradict Maria's, and that contradiction is the point:
| Stakeholder | Why talk to them |
|---|---|
| Maria — Operations Director | Owns the outcome and the budget; defines what "better" is measured in |
| Dev — Data Engineer | Skeptical about the source data; knows exactly which fields (like incident_zip) you can't trust |
| Lisa — Security | Sets the hard constraints: complaint text containing PII — personally identifying information like names or phone numbers — may not leave the building |
| Tom — Borough Manager | Consumes the output; his weekly Excel export is non-negotiable |
How to run a 30-minute discovery call
Thirty minutes, five blocks, no slides. Stakeholders are doing you a favor, and precision here buys you weeks later.
0–5 min — the current workflow. "Walk me through how a request gets handled today." You want the as-is process — as it actually runs — step by step. Steer back from the future state with "and then what happens?"
5–12 min — the pain points. "Where does it break down?" Demand specific, recent examples: "the queue is unmanageable" is a feeling; "last Tuesday we re-opened a noise complaint from 2024 because it looked new" is evidence.
12–18 min — the workarounds. "What have you already tried?" Workarounds reveal the real workflow. Example: an operator screenshares a color-coded spreadsheet where yellow means "I think this one is urgent," maintained by hand every Friday. That spreadsheet is doing the job your system will eventually do. Screenshot it. Respect it.
18–25 min — constraints and veto points. "What can't change? What would kill this project?" Here Lisa says complaint text can't leave the building, Dev says the ZIP codes are unreliable, and Tom's Excel habit proves non-negotiable.
25–30 min — success, in their words. "Six weeks from now, what would make you say this was worth it?" Push past "the backlog is smaller" to a number. Maria measures everything — she'll have one if you ask twice.
Two rules. Ask about the work, not the tool: "what would you build?" gets you "AI, obviously"; "show me how you do it today" gets you the spreadsheet. Capture exact quotes: "we just work oldest-first and hope" beats any paraphrase.
The 5 Whys on the 311 backlog
The 5 Whys is a simple root-cause technique: take a symptom and ask "why?" repeatedly until you reach something you can intervene on — something you can actually change with the build. Watch it run on record 45288020:
Why is a 2020 e-waste request still open?
Because the team never noticed it was overdue.
Why didn't they notice?
Because there's no way to see which requests are overdue — every row looks the same in the export.
Why does every row look the same?
Because the export shows status and timestamp, but not age, agency SLA, or whether it's been touched.
Why doesn't it show that?
Because the only view anyone has is the raw feed — nobody built an operator view.
Why is everyone working from the raw feed?
Because the old internal tool was decommissioned and nothing replaced it.
Five whys, and "maybe AI" has quietly left the room. The candidate problem: operators triage blind because they work from raw data exports with no aging or priority view, so urgent and overdue requests sit untouched while the team works oldest-first. It might still be wrong — one interview is not discovery — but it is now testable. And if Dev then tells you the timestamps are unreliable, the chain shifts with it. That's the technique working as designed.
Myth 1: "Discovery means asking the customer what they want."
"What do you want?" gets you a solution-shaped guess ("AI!"). "Walk me through your day" gets you the color-coded spreadsheet, and the spreadsheet reveals the problem.
Myth 2: "The loudest stakeholder defines the problem."
Maria has the title and the urgency, but Tom's Excel dependency and Lisa's security constraints can each kill your project alone. Interview the quiet veto-holders too — especially the ones who won't be on the demo call.
Myth 3: "Discovery is the soft stuff; the real work starts at the code."
Discovery is the highest-leverage engineering work in the engagement. A correct problem statement makes the next four steps straightforward; a wrong one makes them expensive.
The deliverable: the one-page discovery note
Discovery isn't done when you understand the problem. It's done when you've written it down in a form a stakeholder can correct. That document is the discovery note — one page, five sections: problem statement (who is affected, what breaks, no technology mentioned), users (the humans doing the work, plus who decides it succeeded), current workflow (the as-is process with breakage points marked), constraints (security, data quality, non-negotiable habits, timeline), and success metric (a number both sides agree on, with baseline and target).
Here is what Maria's email becomes after real discovery:
Discovery note — CityOps, v1 (after three interviews)
Problem statement: Borough triage staff cannot tell which of ~40,000 open 311 requests need attention first, because they work from raw data exports with no aging or priority view. Urgent and overdue requests sit untouched while staff work oldest-first, and the unresolved count keeps growing.
Users: 6 triage operators across 3 borough offices (daily users); Maria, Director of Operations (success owner). Tom, borough manager, consumes the weekly Excel summary.
Current workflow: 311 feed → weekly raw export → spreadsheet → operators sort by received date → oldest requests handled first → overdue items discovered by complaint, not by process.
Constraints: complaint text may not leave the building (Lisa); ZIP-code data is unreliable (Dev — do not sort or dedupe on it); Tom's weekly Excel export is non-negotiable; six-week timeline, deadline will not move.
Success metric: reduce the number of requests open longer than 30 days by 25% within 8 weeks of launch (baseline: current count from the 311 feed).
Compare that to the email. Same situation — but now it names the user, the broken workflow, the boundaries, and a measurable finish line. And notice what it does not say: "AI," "dashboard," "priority queue." Those are candidate solutions for the scoping step. The discovery note describes the problem; the scope document — the separate write-up proposing what to build — comes next. Confirm the problem before you fall in love with the solution.
Break it: how discovery fails
Discovery fails in predictable ways. Learn the patterns so you can catch them in yourself:
Building from one interview. Maria's view is real but partial. Skip the operator and you build for the manager's mental model — which is how you ship a dashboard nobody opens.
Treating the requested solution as the problem. "They asked for AI" becomes the plan, and six weeks later you have a chatbot over a queue nobody can triage. The council member's suggestion was a guess, not a requirement.
Skipping Dev because he's difficult. The skeptic is your cheapest source of truth: "don't trust the ZIP codes" just saved you from a deduplication feature that would have silently corrupted the data.
Discovering constraints after the build. Lisa's rule — complaint text stays in the building — discovered in week five is a crisis. Discovered in week one, it's a design input.
Never writing it down. Undocumented discovery evaporates. Two weeks in, "what did Maria actually ask for?" becomes a debate instead of a document.
Must know
- Symptom vs problem vs solution: build problems, not symptoms; treat requested solutions as hypotheses
- Interview the work, not the wish: "walk me through your day" beats "what do you want?" every time
- Talk to the veto-holders early: security, data skeptics, and the person whose Excel habit you're threatening
- The 5 Whys: walk the symptom down until you reach something you can intervene on
- The discovery note: problem statement, users, current workflow, constraints, success metric — one page, written down, read back to the stakeholder
Useful later
- Formal user-research methods (personas, journey maps) — valuable at scale, overkill for a 30-minute call
- Stakeholder power-mapping for large enterprise accounts with layered politics
- Quantitative baselining: measuring the current workflow's throughput before you change it
Don't memorize this
- The exact 5-block timing of the call — the spirit (workflow, pain, workarounds, constraints, success) matters more than the minutes
- Any "correct" discovery-note template — Maria needs to recognize her own words in it, not admire your formatting
- Interview question scripts verbatim — curiosity beats checklists, and stakeholders can tell the difference
Make it durable: the read-back ritual
A discovery note nobody has seen is a diary entry. The step that makes it production-safe is the read-back: send the one-pager to the stakeholders and ask, "Did I get this right? What did I miss?" Maria corrects the user count. Dev adds that duplicate requests are rampant. Lisa sharpens the PII wording. You revise, they confirm — now the note is a shared artifact, not your private understanding.
This is why the discovery note is a required deliverable in the Stage 1 milestone. When scope arguments erupt in week four, you point at the agreed problem statement and success metric, and the argument becomes a decision instead of a debate. Version it in the repo. Date every revision.
Explain it to the customer in plain language
After discovery, you owe Maria a summary she can forward to her boss without translating:
"Maria — here's what I heard across our conversations. Your six triage operators are working from raw 311 exports with no way to see which requests are most overdue, so they work oldest-first and urgent items sit. The count keeps growing because the triage view never existed, not because the team is slow. My proposal: build the prioritization view they never had, keep Tom's weekly Excel exactly as it is, and keep all complaint text inside your systems per Lisa's rules. If we cut requests open longer than 30 days by 25% within eight weeks of launch, we call it a win. Did I get anything wrong?"
Notice the structure: what I heard → what I'll build → what I won't touch → how we'll measure it → confirm. The final question is the most important sentence in the paragraph — it turns your understanding into their correction, and their correction into your shared starting point.
Add it to CityOps
Your first real CityOps deliverable starts before any code exists. In the Stage 1 milestone you will:
1. Draft the discovery note as one page covering the five sections above, based on the evidence packs in this guide.
2. Run the read-back — in the milestone, that's a written self-review: which stakeholder would object to which line, and why?
3. Commit it to the repo as docs/discovery-note.md, dated and versioned, so every later decision can point back to it.
The discovery note is the seed the whole spine grows from. Stage 2's pipeline, Stage 3's operator console, Stage 4's copilot — all of them trace back to decisions made on this page. Get it right and the six weeks have a spine; get it wrong and you'll feel it at every milestone.
Discovery is the skill every one of these roles shares: find the real problem before anyone asks you to build.
Field check
- Maria emails: "We're drowning, maybe AI can help." List three specific questions you'd ask in your first 30-minute call — and for each, say what you're trying to learn.
- Take this symptom: "Nobody uses the dashboard we built." Run the 5 Whys on it until you reach something you can intervene on. Where did you stop, and why?
- A stakeholder says "just build what I asked for." What could fail if you do? How would you detect it early? What would you tell the customer instead?
What a good answer looks like
For (1): ask about the workflow ("walk me through how a request is triaged today"), the workarounds ("what have you tried?"), and the success measure ("what number would tell you this worked?") — each aimed at the as-is process, not at a tool. For (2): the whys should land somewhere buildable — nobody opens it because no operator was interviewed, so it shows what managers asked for instead of what operators need; the intervention is at the interview step, not the dashboard step. For (3): building the requested solution without a problem statement risks solving the wrong problem with real weeks; you detect it when you can't write the discovery note's five sections without guessing; you tell the customer you want thirty minutes to understand the work first, so what you build actually moves their metric.