Question-led guide · how-to
What five decisions should I make before writing code?
A five-decision card for defining the user, outcome, constraints, failure behavior, and verification evidence before implementation begins.
Direct answer
Decide five things: who experiences the problem, which observable outcome must change, which constraints rule out otherwise attractive designs, how failure and partial progress should behave, and what evidence will convince you the solution works. Write each as a falsifiable statement before asking AI or a teammate for implementation. These decisions do not freeze the design; they make later changes explicit instead of accidental.
Scope
Use the card for a feature, service change, automation, or AI workflow before selecting a library or generating code. A small change may need one sentence per decision. A high-impact or cross-team change should attach evidence and owner approvals to each item.
Why it happens
Implementation creates momentum. Once code exists, teams defend the emerging structure and reinterpret the problem around it. AI makes this faster: a vague request can become a plausible architecture before the user, constraints, or failure policy are explicit. The generated artifact then acts like an undocumented decision.
Diagnosis
Stop before coding if any answer is missing:
- User: Who makes or experiences the decision, including operators and affected parties?
- Outcome: What observable state changes if the work succeeds?
- Constraints: Which latency, consistency, security, privacy, cost, compatibility, or organizational limits matter?
- Failure: What happens on timeout, partial success, duplicate delivery, bad input, dependency loss, and cancellation?
- Verification: Which tests, runtime evidence, review, and rollback signal will support acceptance?
Solution
Write the decisions as tests against alternatives. “Use a queue” is not a constraint; “the request may take ten minutes and must survive process restart” is. “Handle errors” is not a failure decision; “the operation remains pending until reconciliation proves whether the effect occurred” is. “Add tests” is not verification; name the invariant, environment, and evidence.
Ask AI to challenge the card before it writes code: list missing stakeholders, counterexamples, incompatible constraints, and failure states. A human owner accepts the tradeoffs. After implementation, compare the system with the original card and record every material change.
Artifact
| Decision | One-sentence contract | Evidence or owner |
|---|---|---|
| User | Who needs the change and who bears failure? | Interview, workflow observation, owner |
| Outcome | Which observable state or decision improves? | Product event, business record, SLO |
| Constraints | What rules out designs? | Requirement, policy, measurement |
| Failure | How do partial, duplicate, delayed, and unsafe cases resolve? | State machine, runbook, threat model |
| Verification | What proves enough to release and when do we roll back? | Test, eval, canary, runtime signal |
Common mistakes
- Writing a solution in the outcome field.
- Treating current technology as a fixed constraint without checking why.
- Designing only success and leaving retries or cancellation to framework defaults.
- Asking AI to choose the acceptance evidence for a risk owned by someone else.
- Keeping the card unchanged after evidence invalidates an assumption.
Evidence
Secure development includes tracking requirements, risks, and design decisions rather than treating security as a final scan.
The NIST Secure Software Development Framework organizes practices across the software lifecycle and includes tracking software security requirements, risks, and design decisions.
Primary source · standard · checked Aug 25, 2026
Limit: SSDF is a security framework and does not define this five-decision card or every product-design concern.
AI risk management begins by defining system tasks, context, roles, risks, and measurement approaches.
The NIST AI RMF Core describes mapping context and tasks, governing roles, selecting measurements, and managing risk across the lifecycle.
Primary source · official-doc · checked Aug 25, 2026
Limit: The framework does not prescribe a five-item software design sequence.
The five-decision card is a compact author framework for making implementation assumptions reviewable.
The card forces product, architecture, failure, and verification choices into a shared pre-code artifact.
Signal Studio author framework · reviewed Aug 25, 2026
Limit: Complex or regulated systems require additional security, privacy, legal, data, operations, and stakeholder review.
Limitations
Five questions cannot capture every requirement. The card is intentionally compact and should trigger deeper architecture, threat-model, privacy, accessibility, data-governance, or compliance work when the system boundary requires it.
FAQ
- Is this a replacement for a design document?
- No. It is the smallest useful decision boundary. Expand any item whose uncertainty, blast radius, or coordination cost deserves a fuller design record.
- Can the decisions change after coding starts?
- Yes. Record what evidence changed the decision and revisit affected tests, operations, and stakeholders instead of silently moving the goalposts.
Related guides
Continue within Engineering judgment, or use one of these adjacent diagnostics:
English editorial review: Codex native-English editorial review, .