| name | architecture-decision |
| description | Architecture decisions in ADR/RFC/RFD format: context, constraints, options, recommendation. Triggers: ADR, RFC, RFD, trade-offs, design choice, pick between, evaluate approach. |
| effort | medium |
| user-invocable | false |
| allowed-tools | Read, Write |
Architecture Decision Skill
Core Philosophy: "Everything is a Trade-off"
There are no "best solutions", only solutions with the right set of trade-offs for the specific context.
Decision Making Process (RFD / RFC)
- Context: What is the problem? Why now?
- Constraints: Budget, Time, Skillset, Legacy.
- Options: Propose at least 3 viable options.
- Trade-off Analysis: Compare constraints vs options.
- Recommendation: Choose one and justify.
Trade-off Analysis Matrix (Template)
| Feature | Option A (e.g. SQL) | Option B (e.g. NoSQL) | Option C (e.g. File) |
|---|
| Scalability | Medium (Vertical) | High (Horizontal) | Low |
| Consistency | Strong (ACID) | Eventual (BASE) | N/A |
| Complexity | Low (Known) | Medium (New tech) | Low |
| Cost | $$ | $$$ | $ |
Architecture Note
When a decision is made, document it.
# Architecture Note: Use PostgreSQL for Main Database
## Status
Accepted
## Context
We need a reliable, relational database for user data...
## Decision
We will use PostgreSQL 16.
## Consequences
- Positive: ACID compliance, rich ecosystem.
- Negative: Scaling writes requires sharding later.
Critical Factors to Evaluate
- Reliability (Availability, Fault tolerance)
- Scalability (Throughput, Latency)
- Maintainability (Simple vs Easy, Ecosystem)
- Security (AuthN/Z, Encryption)
- Cost (Infrastructure, License, Cognitive load)
Rules
- MUST present at least 3 viable options, including "status quo / do nothing" when relevant
- MUST state constraints (budget, time, team skillset, legacy) before enumerating options — options without constraints are arbitrary
- NEVER recommend an option without explicitly naming its failure mode and what would trigger revisiting the decision
- CRITICAL: the output is a document (ADR / RFC / RFD), not code changes. Code work belongs in
/plan or /refactor-plan.
- MANDATORY:
Consequences section names both Positive and Negative effects. A decision with only upside is not honestly analysed.
Gotchas
- "Status quo" is a genuine option and often the right one for constrained teams. Omitting it biases the analysis toward change for change's sake.
- ADRs are append-only. A reversed decision gets a new ADR with
Status: Supersedes ADR-N, not an in-place edit of the original — the history of thinking matters more than the current state.
- Qualitative scales (High / Medium / Low) without anchors are hand-waving. When scoring, pin each level to a measurable threshold (e.g., "High scalability = 10k req/s at p95 < 100ms on 2 nodes").
- "We might use X" and "We will try X" are not decisions — they are deferrals. A valid ADR states the chosen option unconditionally; if you cannot, the decision is not ready.
- Political constraints (team expertise, vendor relationships, executive preferences) are first-class constraints. Hiding them behind technical language produces ADRs that get silently ignored — name them explicitly in the Constraints section.
When NOT to Load
- To find what architectural problems exist — use
/architecture-audit (discovery) before this skill (decision)
- To plan implementation of an already-decided option — use
/plan or /refactor-plan
- To design a single module's interface — use
/design-an-interface
- When fewer than 2 options exist — there is no decision to make; document the constraint instead
- For runtime configuration choices (flag values, timeouts) — those are operational, not architectural
