Problem Definition: Clarity Before Code
Two engineers can use the same model and get very different results, because they start with different levels of clarity. Teams spend a great deal of attention on judging an agent's solution and far less on how the problem was defined in the first place. This page treats problem definition as the skill it has become: what a clear problem contains, how to tell how clear yours is, how to review and measure it, and how to teach it.
Why Clarity Decides the Result
An agent does not ask what you meant. It builds exactly what it was told and fills every gap with a plausible guess. Give it a vague problem and it returns a confident, well-structured answer to a slightly different question, and the error surfaces late: in review, in Launch, or in production.
That moves the leverage. When typing was the slow part, a fuzzy problem got sharpened while the code was written. Now the code arrives in minutes, so the sharpening has to happen before the request is made. Problem definition stops being a soft skill around the work and becomes the first engineering step of the work, which is why AIDLC gives it a phase of its own in Analyze.
The Anatomy of a Clear Problem
Five parts. The first four fit in one sentence; the fifth turns the sentence into something a test can check.
The specific person or role with the problem, not "users".
What they need to be able to do, stated as an outcome, not a feature.
The reason it matters, which decides every trade-off later.
The one thing that would make the solution unacceptable however good it looks.
Acceptance criteria in Given/When/Then that prove the need is met.
Example, all five parts:
Account owners (who) need a scheduled CSV of their paid invoices (needs) so their accountant can close the books without asking support (why), and must never receive another account's data (must never). Done when AC-1 to AC-3 pass, including the cross-account test.
The Clarity Ladder
A quick way to rate any request before it reaches an agent. Agents should only receive work at the top two rungs; everything below goes back to Analyze.
| Rung | What it sounds like | What an agent will do with it | Ready for an agent? |
|---|---|---|---|
| 1. Wish | "Customers want better exports." | Invent the problem, the user and the solution | No |
| 2. Request | "Add a CSV export to invoices." | Build a feature with every detail guessed | No |
| 3. Problem | The one-sentence problem: who, needs, why, must never | Build roughly the right thing, with untested edges | Not yet |
| 4. Brief | The problem plus criteria, constraints, open questions and risks | Design and build against checkable criteria | Yes, for design |
| 5. Contract | A ticket contract: criteria with IDs, risk tier, data, flag, rollback | Write failing tests first, then implement | Yes, for code |
Before and After
Five invented requests, each rewritten to the Problem rung. Notice that the rewrite usually adds the "must never" and the reason, the two things a request almost always leaves out.
| Before | After |
|---|---|
| "Make the dashboard faster." | Support leads need the open-tickets dashboard to load within the limit in the brief on a weekday morning, so they can triage at shift start; it must never show stale counts without saying so. |
| "Add SSO." | Admins at enterprise customers need their staff to sign in with their company identity provider, so leavers lose access the day they leave; local passwords must never remain usable once SSO is enforced. |
| "Use AI to answer support emails." | Support agents need routine how-to emails drafted with a cited help article, so they can answer more customers; a billing dispute must never be answered without a person. |
| "Clean up the user table." | The platform team needs duplicate user records merged, so password resets reach the right inbox; no account's order history may ever be lost or reassigned. |
| "Let users delete their data." | Account owners need to delete their account and personal data themselves, to meet the privacy commitment in our policy; invoices the law requires us to keep must never be deleted with it. |
Review the Problem Like Code
Code gets a reviewer; the problem it solves usually does not. A ten-question problem review before design starts is the cheapest quality gate in the whole cycle.
Problem review checklist
[ ] Is the "who" a specific role, not "users"?
[ ] Is the need an outcome, not a feature?
[ ] Is the reason stated, and does it decide trade-offs?
[ ] Is there a "must never"?
[ ] Would two engineers read it the same way?
[ ] What would an agent have to guess? (list it)
[ ] Are the empty, error and edge cases named?
[ ] Which systems or data does it touch?
[ ] Is anything here actually two problems?
[ ] Does every acceptance criterion trace to it?Prompt: make the agent restate it first
Before proposing any solution, restate this problem in your own
words: who has it, what they need, why it matters, and what must
never happen.
Problem: [paste the problem or brief]
Then list:
- every assumption you would have to make to solve it,
- every question whose answer would change your approach,
- anything that reads like two problems.
Do not propose a solution until I confirm your restatement.Measuring Problem Definition
If teams measure only the solution, they will only improve the solution. These signals make problem-definition quality visible; track them per team, never per person.
Backward moves to Analyze
How often Ideate, Develop or Launch sends work back because the problem or a criterion was unclear. See the backward moves.
Intent change requests traced to gaps
How many intent change requests answer a question the brief should have answered.
Questions raised in the problem review
Many questions early is good news; few in review and many in Develop means the review is not being done.
Escapes traced to the requirement
Production defects whose root cause is a missing or ambiguous requirement rather than a coding error.
Teaching the Skill
Four short team exercises. Each takes less time than one round of rework.
The rewrite drill
Take three real requests from the backlog and rewrite each to the Problem rung as a group.
Same prompt, two people
Two engineers give the same agent their own version of one problem and compare results. The difference is the lesson.
Five guesses
For any brief, list five things an agent would have to guess. Each guess becomes a question or a criterion.
The pre-mortem
Imagine the feature shipped and failed. Write the incident. The cause usually names the missing "must never".
One-Page Problem Template
The top of every requirements brief. The rest of the brief - constraints, open questions, risks - follows it.
PROBLEM (one sentence)
[Who] need [outcome] so that [reason], and [must never].
WHO EXACTLY
Role, situation, how often they hit this:
WHAT THEY DO TODAY
The workaround, and what it costs them:
WHY NOW
What changes if we solve it, and what happens if we do not:
MUST NEVER
The failure that would make any solution unacceptable:
DONE WHEN (acceptance criteria, Given/When/Then, with IDs)
AC-1
AC-2
AC-3 (the "must never", as a negative criterion)
WHAT AN AGENT WOULD HAVE TO GUESS (from the problem review)
-
-
OWNER: product owner REVIEWED BY:Frequently Asked Questions
Because an agent builds exactly what it is told and fills every gap with a plausible guess, and it does so in minutes. When typing was slow, a fuzzy problem got sharpened while the code was written; now the sharpening has to happen before the request, or the error surfaces late in review, Launch or production.
Five parts: who has the problem, what they need as an outcome, why it matters, what must never happen, and acceptance criteria that say when it is done. The first four fit in one sentence. Agents should receive work only once it reaches a brief or a ticket contract, never as a wish or a bare feature request.
Track, per team, how often later phases send work back to Analyze, how many intent change requests answer a question the brief should have answered, how many questions the problem review raises, and how many production defects trace to a missing or ambiguous requirement rather than a coding error.
Define It Before You Delegate It
Take the next request on your board up the clarity ladder before an agent sees it.