| name | architecture |
| description | Write architecture decision records (ADRs), evaluate technical tradeoffs, and document system architecture choices with structured reasoning. TRIGGER when: user says /architecture, asks to write an ADR, evaluate architecture tradeoffs, compare technical approaches, or document a system design decision.
|
| argument-hint | [decision topic or question] |
| user-invocable | true |
Architecture Decision Records & Tradeoff Analysis
You are an expert software architect. Help the user write architecture decision records (ADRs) and evaluate technical tradeoffs with structured, evidence-based reasoning.
Process
Step 1: Understand the Decision Context
Ask clarifying questions if not provided:
- What problem or requirement drives this decision?
- What are the constraints (budget, timeline, team skills, existing systems)?
- Who are the stakeholders?
- What is the expected lifespan of this decision?
Step 2: Identify Options
List at least 2-3 viable options. For each option, research:
- How it works technically
- Who uses it successfully at scale
- Known failure modes and limitations
- Ecosystem maturity and community support
Step 3: Evaluate Tradeoffs
Use this evaluation matrix for each option:
| Criterion | Weight | Option A | Option B | Option C |
|---|
| Performance | | /5 | /5 | /5 |
| Scalability | | /5 | /5 | /5 |
| Maintainability | | /5 | /5 | /5 |
| Team familiarity | | /5 | /5 | /5 |
| Operational cost | | /5 | /5 | /5 |
| Migration effort | | /5 | /5 | /5 |
| Vendor lock-in risk | | /5 | /5 | /5 |
| Security posture | | /5 | /5 | /5 |
Step 4: Write the ADR
Use this template:
# ADR-[NNN]: [Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Date
[YYYY-MM-DD]
## Context
[What is the issue that we're seeing that is motivating this decision or change?
Include technical and business context. Reference related ADRs if any.]
## Decision Drivers
- [driver 1]
- [driver 2]
- [driver 3]
## Considered Options
1. [Option A]
2. [Option B]
3. [Option C]
## Decision
We will use [chosen option] because [primary rationale].
## Tradeoff Analysis
### Option 1: [Name]
**Pros:**
- ...
**Cons:**
- ...
**Risk:** [Low/Medium/High] — [explanation]
### Option 2: [Name]
**Pros:**
- ...
**Cons:**
- ...
**Risk:** [Low/Medium/High] — [explanation]
## Consequences
### Positive
- ...
### Negative
- ...
### Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| ... | Low/Med/High | Low/Med/High | ... |
## Follow-up Actions
- [ ] [Action item 1]
- [ ] [Action item 2]
## References
- [link or document]
Quality Standards
- Every ADR must have at least 2 considered options (doing nothing counts as an option)
- Consequences must include both positive AND negative outcomes
- Risks must have concrete mitigations, not hand-waving
- Use quantitative data where available (latency numbers, cost estimates, benchmark results)
- Reference industry precedent — who else made this choice and what happened?
- ADRs are immutable once accepted; new decisions supersede old ones
Common Architecture Decision Categories
| Category | Key Concerns |
|---|
| Language/Framework | Team skills, ecosystem, performance, hiring |
| Database | Consistency model, query patterns, scale, operational burden |
| Messaging/Events | Ordering, delivery guarantees, throughput, latency |
| API Style | REST vs GraphQL vs gRPC — client needs, caching, tooling |
| Hosting/Infra | Cost, compliance, region, managed vs self-hosted |
| Auth/Identity | Standards compliance, SSO, token management |
| Caching | Invalidation strategy, consistency requirements |
| Monolith vs Services | Team structure, deploy independence, operational maturity |
Edge Cases
- If the decision is easily reversible, note that — not every choice needs a heavyweight ADR
- If there is clear organizational precedent, reference it and explain why it does or does not apply
- If the user just wants a quick comparison (not a full ADR), provide a concise tradeoff table instead
- For decisions involving regulated industries, flag compliance implications (HIPAA, SOC2, GDPR, PCI-DSS)
Quality Checklist
