# Requirements Clarification
Requirements clarification turns a vague prompt into a bounded design problem. It prevents building the wrong system beautifully.
## Clarify In This Order
1. **Users and actors:** who writes, reads, administers, and integrates?
2. **Core workflows:** what must happen in the primary path?
3. **Scale:** QPS, data size, fanout, peak factor, regions.
4. **Correctness:** which invariants cannot break?
5. **Freshness:** what can be stale and for how long?
6. **Reliability:** required uptime, recovery, degradation.
7. **Security/privacy:** tenant boundaries, sensitive data, abuse paths.
8. **Out of scope:** what will not be solved in v1.
The order matters. Start with product behavior, then force the numbers and invariants to sharpen it. If you ask about databases, queues, or caches too early, you are usually choosing implementation before you know what the system must protect.
## Turn Answers Into Constraints
| Clarified answer | Design pressure it creates |
|---|---|
| "Only the owner can edit after publish" | authorization checks, audit history, soft delete, maybe versioning |
| "Readers can tolerate 30 seconds of staleness" | cache-friendly reads, async indexing, cheaper fanout |
| "Payments cannot be duplicated" | idempotency keys, transactional state changes, reconciliation jobs |
| "Search should feel live, but exact freshness is not required" | primary DB as source of truth, async search-index sync |
| "Admins need regional data export" | retention policy, background jobs, object storage, access logging |
This is the real output of clarification: not a list of nice questions, but a smaller set of constraints that directly change the architecture.
## Small Example
Suppose the prompt is "design comments for a document app." A weak requirement pass jumps straight to `comments` tables and WebSockets. A better pass asks:
- Are comments attached to the whole document, a text range, or a versioned snapshot?
- Can a comment be edited or deleted after replies exist?
- Do viewers need live updates, unread counts, email notifications, or all three?
- Is ordering by creation time enough, or do resolved threads stay visible?
- What happens if a user loses access to the document after commenting?
Those answers decide whether the design needs stable anchors, immutable comment events, permission rechecks on read, async notification fanout, or a realtime channel. The database shape is a consequence, not the starting point.
## Good Questions
- Is this system read-heavy, write-heavy, or fanout-heavy?
- What must be synchronous in the request path?
- What data is authoritative?
- What happens when dependencies fail?
- What is the first version vs future version?
## What To Write Down
End the clarification phase with a compact brief:
- **Primary users:** the actors whose workflows define success.
- **Core path:** the request or job that must work first.
- **Hard invariants:** rules that cannot be repaired later with a batch job.
- **Latency/freshness targets:** concrete p95 or staleness numbers.
- **Failure behavior:** what degrades, retries, blocks, or reconciles.
- **Explicit non-goals:** features and scale assumptions intentionally excluded.
## Pro Tip
In interviews and real design docs, requirements are a negotiation. A Staff-level engineer narrows ambiguity without making hidden assumptions.