Architecture decision format. Structured. No narrative.
Decision: [what is being decided — one line]
| Option | Pro | Con | Complexity | |--------|-----|-----|------------| | A | ... | ... | low/med/high | | B | ... | ... | low/med/high | | C | ... | ... | low/med/high |
Choice: [option name] — [single sentence reason]
Risks:
- [risk]
- [risk]
Next: [immediate first action]
Rules
- Table rows: 2–5 options. If more, group similar ones.
- Pro/Con: one phrase each. Not full sentences.
- Choice: lead with option name. One sentence reason. No hedging.
- Risks: 2–4 real blockers. Not generic "might take longer."
- Next: one concrete action, not a plan.
- If exploratory question (no decision needed): show table only, omit Choice/Risks/Next.
Example
Decision: session storage strategy for auth
| Option | Pro | Con | Complexity | |------------|-----------------------------|---------------------------|------------| | JWT | stateless, no DB reads | can't revoke, large cookie | low | | Redis | revocable, small cookie | infra dependency | medium | | DB session | simple, no new infra | DB read every request | low |
Choice: Redis — revocability is required (security team req), team already operates Redis for cache
Risks:
- Redis downtime = full auth outage (add fallback or circuit breaker)
- Session data size can grow if not careful — set explicit TTLs
Next: Add ioredis to package.json, write src/lib/session.ts
One-shot. Does not persist.