3.1 From Problem Statement to Verifiable Requirements
Requirements work establishes a shared, verifiable understanding of the problem, boundaries, priorities, and acceptance criteria. Document length cannot do that on its own. A requirement that doesn't clearly state who needs it, why it's needed, and how completion can be verified is not yet sufficient to guide implementation.
First, Distinguish Problems, Requirements, and Solutions
These three statements sound similar, but they operate at different levels:
Problem: During peak registration periods, administrators have to manually merge multiple tables, leading to repeated data entry.
Requirement: After registration closes, administrators should receive a deduplicated, traceable list of participants.
Solution: Use Redis Set to store participant IDs.The first two statements describe the business context and desired capabilities, while the third already specifies a technical approach. Writing the solution into a requirement too early risks skipping alternative solutions and makes it difficult to assess whether the chosen solution actually addresses the problem.
A One-Page Problem Statement
Before breaking down a user story, first write a concise one-page summary:
| Item | Question to Answer |
|---|---|
| Objective | What outcome needs to change? |
| Stakeholders | Who uses, operates, purchases, audits, or bears risk? |
| Current Process | How is this currently done, and what are the pain points? |
| System Boundaries | What does this system own and what does it not own? |
| Constraints | What are the regulatory, timeline, budget, and technical limitations? |
| Success Signals | How will we know the problem has improved after launch? |
| Unknowns | Which assumptions still require interviews, prototyping, or experimentation to validate? |
"Users" are just one type of stakeholder. Operations staff care about recovery and diagnostics, security personnel focus on permission boundaries, and finance teams prioritize auditability of settlements. Each concern can produce requirements.
User stories are entry points for discussion, not complete specifications
A common format is:
As a <role>, I want <capability> so that <value>.For example:
As a participant, I want to cancel my registration before the deadline so that I can release the slot if I can no longer attend.This card serves only as a starting point for discussion. The actual items that need confirmation include: which time zone determines the deadline, whether re-registration is allowed after cancellation, how fees will be refunded, and whether administrative cancellation should leave an audit trail.
Technical work has value too, but avoid forcing it to fit the "as a system, I want..." pattern. Tasks like database migrations or observability improvements can be framed as engineering efforts and linked to the risks, quality attributes, or user stories they support.
Use Examples to Eliminate Ambiguity
Save this Gherkin specification as cancellation.feature. It still needs step definitions and a system under test before it can execute; scenario text alone is not a passed acceptance test. Given–When–Then describes observable behavior:
Feature: Registration cancellation
Scenario: Cancel a confirmed registration before the deadline
Given participant A has a CONFIRMED registration
And registration closes at 2026-08-10T18:00:00+08:00
And the current time is 2026-08-10T17:59:00+08:00
When participant A cancels the registration
Then the registration status becomes CANCELLED
And the number of available places increases by 1
And the system records the actor, operation time, and original registration IDAdditional examples and edge cases are needed:
- Is the cancellation allowed at the exact cutoff time?
- When a canceled request is retried, does it return success or a conflict?
- When a refund fails, how are the enrollment status and refund status combined?
- When two cancellation requests arrive concurrently, is the place released only once?
Turn those questions into proposed rules and then scenarios:
| Condition | Example agreement |
|---|---|
| First cancellation exactly at the deadline | Reject; release no place |
| Retry a successful cancellation with the same idempotency key | Return the original result; release exactly one place in total |
| Two concurrent cancellation requests | At most one state transition and place release |
| Cancellation succeeds but refund temporarily fails | Keep registration CANCELLED; put the refund into a retryable state |
For a first operation, use the server clock at the business decision point. Inject a fixed clock in tests instead of waiting for a real second to arrive. Keeping cancellation effective while refunding later remains a business decision that stakeholders must confirm.
Acceptance examples should describe externally observable outcomes. If they assert that a private method is called three times, the test has moved beyond the requirements into implementation details.
Beyond Functional Requirements: Quality Attributes
"System must be fast, stable, and secure" cannot be verified without context. Quality attributes must be grounded in specific scenarios. The SEI commonly uses six elements to describe such scenarios: stimulus source, stimulus, environment, affected component, response, and response metric.
Below is an example pending confirmation from stakeholders; the numbers are not universal standards:
| Element | Example |
|---|---|
| Stimulus source | Logged-in audience members |
| Stimulus | Request for the current leaderboard |
| Environment | During finals live broadcast, with 3,000 concurrent sessions |
| Affected component | Leaderboard query endpoint and its dependencies |
| Response | Return a snapshot of rankings no older than 5 seconds |
| Metric | p95 latency below 300 ms, with success rate at least 99.9% over a 5-minute window |
Three thousand sessions do not specify a request rate. An additional agreement might sustain 1,500 queries/s for five minutes, with fixed data size, request distribution, and timeouts: 450,000 attempted requests under these assumptions. Measure from client send to complete response, counting timeouts and rejections in the request population and failure rate. An HTTP success with a snapshot older than five seconds still misses the freshness requirement. Do not measure only successful cache hits.
Metrics must specify both the statistical window and the load conditions. A statement like "average latency of 100 ms" masks tail latency and fails to define under what traffic conditions the metric holds.
Common quality attributes include availability, modifiability, security, testability, observability, and cost. These often trade off against one another: stronger consistency may increase latency, while finer-grained auditing can raise storage and privacy governance costs. Expose these trade-offs during requirements work instead of promising to maximize every metric.
Constraints, Preferences, and Assumptions Should Not Be Mixed
Constraint: Payment data must remain within the designated region.
Preference: The team is familiar with PostgreSQL and prefers to reuse it.
Assumption: The peak write rate in the first year will not exceed 200 writes per second.Constraints typically cannot be bypassed; preferences can be reconsidered if the benefits are sufficient; assumptions require validation and the establishment of review triggers. Mixing all three into "musts" creates unjustified architectural limitations.
Establish a Domain Vocabulary
If "tournament," "match," "registration," and "eligibility" have different meanings across product documentation, code, and databases, no amount of visual design can eliminate confusion. A vocabulary list must at least record:
Tournament (Event): A competitive activity with a registration window and scheduled matchups.
Match (Game): A single encounter between two participants within a tournament.
Registration (Enrollment): A record of a participant applying to join a specific tournament.
Eligibility (Qualification): The set of rules that must be satisfied for a participant to register.Vocabulary is not a one-time document. Product requirements, APIs, events, and monitoring metrics should use consistent terminology. Whenever the meaning of a term changes, the impact of that change must be documented.
From Requirements to Traceable Delivery
A lightweight traceability chain can look like this:
Business objective
-> User story / Quality attribute scenario
-> Acceptance example
-> Architecture decision and interface contract
-> Implementation, testing, and runtime metricsThe purpose of traceability is not to assign line numbers to every piece of code, but to enable quick identification of relevant decisions and validation mechanisms when requirements change or production metrics go out of bounds.
What to Establish Before Architecture Design
- A single page of problem statement with clearly defined system boundaries;
- Stakeholders and their key concerns;
- User stories and acceptance criteria prioritized by importance;
- Measurable scenarios for critical quality attributes;
- Constraints, preferences, assumptions, and validation plans;
- A domain vocabulary list and unresolved questions.
This content does not eliminate change, but makes change visible. The next section uses this foundation to select architectural views and document the actual decisions that impact system structure.