Decision‑First Specs: Make PRDs Testable and Final
A practical guide to write PRDs and specs that force testable decisions, reduce ambiguity, and ship faster with fewer reworks.

- Design the document around exits: acceptance tests, observability, rollback.
- Collapse PRD, spec, and one‑pager into a single Decision‑First Spec.
- Write the test plan first; then describe features that pass those tests.
- Make responsibilities explicit for dev, QA, analytics, and go/no‑go.
- Keep the one‑pager as the executive contract; the spec is the playbook.
If it is not testable, it is not a decision. Treat every line as something you or QA can verify in code, logs, or the UI.
The output you will produce
- A one‑page executive contract: purpose, scope, non‑goals, success criteria, top risks, rollout gates.
- An operational Decision‑First Spec: context, decision rules, test plan, API and data contracts, UI flows and edge cases, observability, rollout and rollback, ownership.
- Acceptance tests that double as exit criteria.
Use your own template or start in the PRD tool to keep structure tight and reusable. PRD
The steps, in order
Write the test plan first
List user flows, edge cases, and what QA can run. Define metrics and logs you will check. If a claim is not testable, rewrite it as a test.
- User flows and negative paths
- Preconditions and data setup
- Expected UI states and copy
- Instrumentation: events, properties, IDs
- Metrics: guardrails and success measures
Write context and decision rules
State the problem, scope, and non‑goals. Then capture rules that drive behavior. Keep rules atomic and testable.
- Scope and non‑goals are explicit
- Business and security constraints
- Decision tables or if/then rules
Define API and data contracts
Specify request/response fields, status codes, error shapes, and idempotency. Include data contracts for analytics.
- Stable field names and types
- Error codes that map to UI states
- Event names and property schemas
Detail UI flows and edge cases
Screen states, validation, timeouts, retries. Include empty, error, and loading states with copy that QA can assert.
- State diagram or step list
- Accessible labels and focus order
- Copy variants for errors
Observability and analytics
Define logs, metrics, and dashboards. Who creates them and when they are considered ready to ship.
- Event names and sample payloads
- Log lines and identifiers to trace
- Dashboards and alerts tied to rollout gates
Rollout, exits, and rollback
Plan stages, kill switches, and the go/no‑go criteria. Write the rollback steps like a runbook.
- Stage percentages and time windows
- Exit gates with thresholds
- Rollback command, scope, and owner
Make ownership explicit
Name the person for each lane: dev lead, QA lead, analytics, release manager, on‑call approver. State the go/no‑go trigger.
- Who merges and who approves
- Who tracks metrics during rollout
- Who pulls the kill switch
Keep the one‑pager tight
Executives need the why, the scope, the exits, and the risks. Everything else stays in the spec as the operational playbook.
- Purpose and impact in plain words
- Scope and non‑goals
- Success criteria and top risks
What changes when you write Decision‑First
| Old style doc | Decision‑First Spec |
|---|---|
| Feature list and aspirational goals | Acceptance tests and exit gates define done |
| Observability left to SRE later | Instrumentation and dashboards defined up front |
| Vague non‑goals and scope creep | Clear non‑goals block out‑of‑scope asks |
| Unclear owners and approvals | Named owners and go/no‑go triggers |
| Rollout buried in a launch checklist | Rollout and rollback as a runbook in the spec |
Checklist before you share
- Tests first: could QA run this today from the spec?
- Each rule is observable in UI, logs, or metrics.
- Scope and non‑goals prevent re‑litigating later.
- API, error codes, and analytics events have stable names.
- Dashboards and alerts are named and owned.
- Rollout stages, thresholds, and a kill switch exist.
- Owners are named for dev, QA, analytics, release, and on‑call.
Worked example: Decision‑First Spec for Change Email Address
ScopeLet a signed‑in user change their account email. Security is strict: new email must be verified before it becomes primary. Old email gets a notice. Analytics capture attempts, successes, and failures. The change is reversible during rollout.
1) Acceptance tests (exits)
- User enters a new email and receives a verification link; clicking the link within 15 minutes marks the email verified and sets it as primary.
- If the link expires or is used twice, the user sees a clear error and can request a new link.
- Old primary email receives a notice that a change was requested. If the user did not request it, a recovery flow locks the change.
- Login works with the new email once verified; old email no longer works for login.
- All flows emit analytics events with user ID, request ID, and result code.
- Rollout gates block wider exposure if error rate or verification latency exceed thresholds.
2) Decision rules
- Only authenticated users can request an email change.
- New email must not be already in use; if it is, show an error with a link to sign in.
- Verification link expires after 15 minutes; one active token per user at a time.
- On success, set new email as primary and invalidate old sessions; send confirmation to both emails.
- On failure or expiry, keep old email as primary; user can request a new link.
3) API and data contracts
POST /user/email-change
- Body: { new_email, client_request_id }
- Responses:
- 202 Accepted: { request_id, expires_at }
- 409 Conflict: { code: "EMAIL_IN_USE" }
- 400 Bad Request: { code: "INVALID_EMAIL" }
POST /user/email-verify
- Body: { token, request_id }
- 200 OK: { status: "VERIFIED" }
- 410 Gone: { code: "TOKEN_EXPIRED" }
- 409 Conflict: { code: "TOKEN_ALREADY_USED" }
Analytics events
- email_change_requested { user_id, request_id, new_email_domain }
- email_change_verified { user_id, request_id, latency_ms }
- email_change_failed { user_id, request_id, code }
4) UI flows and edge cases
- Settings page: input with validation on blur; shows error for invalid format or existing account.
- After submit: show banner with masked new email and resend link; disable submit until token expires or is cancelled.
- Verify link clicked when user is signed out: show success and prompt to sign in with new email.
- Verify link expired: show error with a single button to request a new link.
- Accessibility: label input explicitly; focus returns to input on validation error; banner is aria‑live polite.
5) Observability
- Logs: one line per request with request_id, user_id hash, status code, and latency_ms.
- Dashboard tiles: request volume, verification success rate, median verification latency, error code breakdown.
- Alert: trigger if verification success rate falls below 95% for 10 minutes during rollout.
6) Rollout and rollback
- Stage 1: 5% of users. Exit if success rate ≥ 98%, median latency ≤ 3s, and no spike in support tickets.
- Stage 2: 25% of users. Same thresholds; observe for 24 hours.
- Stage 3: 100% if thresholds are met.
- Kill switch: feature flag disables new requests; verification endpoint still processes existing tokens.
- Rollback: flip flag off, drain tokens for 15 minutes, then invalidate all pending tokens.
7) Ownership and go/no‑go
- Dev lead: owns API and integration.
- QA lead: owns acceptance test plan and sign‑off.
- Analytics owner: builds dashboard and alert before Stage 1.
- Release manager: runs rollout and logs gate results.
- On‑call approver: final go/no‑go at each gate; owns kill switch.
8) One‑pager (executive contract)
Purpose: reduce account support load and improve security by letting users change their email safely.
Scope: change email for signed‑in users; excludes change of user ID or cross‑account merges.
Non‑goals: no bulk changes; no admin override UI; no support for unverified emails as primary.
Success criteria: verification success rate ≥ 98% and no increase in account lockouts post‑change.
Top risks: email deliverability, token abuse, and confusion about which email to use for login.
Rollout gates: thresholds as defined above; rollback ready.
Common mistakes to avoid
- Writing features before tests. Start with acceptance tests; features exist to pass them.
- Leaving observability to SRE. Define events, logs, and dashboards in the spec.
- Vague non‑goals. Name what you will not do to stop scope drift.
- Burying rollout criteria. Put gates and thresholds in their own section with owners.
- Forgetting data contracts for analytics. Event names and properties must be stable and reviewed.


