Purpose
Turn an open-ended "which approach should we take?" debate into a rigorous, documented decision — scoring each architectural option across the dimensions that actually matter for the system, surfacing the trade-offs each option forces, and producing a defensible recommendation tied to the team's real constraints. Replaces hallway opinions and gut calls with a structure you can attach to an ADR.
When to Use
Invoke this skill when the user asks to:
- Compare two or more architectural approaches for the same problem (e.g., monolith vs. microservices, REST vs. gRPC, SQL vs. NoSQL, event-driven vs. request-response)
- Write or support an Architecture Decision Record (ADR)
- Evaluate a build-vs-buy or in-house-vs-managed-service decision
- Justify a technical direction to a skeptical stakeholder or review board
- Decide between competing designs in a technical RFC or design doc
- Assess whether to migrate off a current architecture or keep it
Inputs Required
Before starting, collect:
- The decision: What architectural choice is being made, in one sentence
- The options: 2 or more concrete approaches being compared, each with a 1–2 sentence description
- System context: What the system does, current scale (users/RPS/data volume), and stack
- Hard constraints: Non-negotiables — compliance requirements, latency budgets, team size, deadline, budget ceiling
- Priorities: Which dimensions matter most right now (e.g., ship speed for an MVP vs. scalability for a platform play)
- Team profile: Team size, seniority, and existing operational expertise (what they already run well)
- Time horizon: How long this decision needs to hold up — 6 months, 2 years, indefinitely
If priorities or time horizon are missing, default to equal dimension weighting over a 2-year horizon and state the assumption explicitly.
Instructions
Step 1: Frame the Decision and Confirm the Options
Restate the decision in one clear sentence and list each option with a short, neutral description. If any option is underspecified, note the assumption you're making about how it would be implemented. Do not editorialize yet — establish a fair starting line.
Step 2: Set Dimension Weights
Score each option across six dimensions. Assign each dimension a weight (1–5) based on the stated priorities and constraints:
- Speed (time to ship): How fast can the team deliver working software with this option?
- Security: Attack surface, data exposure, blast radius, compliance fit
- Scalability: Headroom under growth — horizontal scaling, bottlenecks, performance ceilings
- Maintainability: Cognitive load, ease of change, debuggability, onboarding cost
- Operational complexity: Deployment, monitoring, on-call burden, failure modes
- Cost: Infrastructure spend plus engineering time, over the time horizon
If the user gave explicit priorities, weight those dimensions 4–5 and de-emphasize the rest. State the weights chosen and why.
Step 3: Score Each Option Per Dimension
For every option × dimension cell, assign a score (1–5, where 5 is best) and a one-sentence justification grounded in this specific system — not a textbook generality. Avoid generic claims like "microservices scale better"; tie it to the actual scale numbers and team profile provided.
Step 4: Build the Weighted Scoring Matrix
Produce a table: rows = options, columns = the six dimensions (with weights shown), plus a weighted total. Compute each weighted total as the sum of (dimension score × dimension weight). The matrix is a decision aid, not an oracle — flag any case where a slightly different weighting flips the result.
Step 5: Surface the Core Trade-Offs
For each option, state plainly:
- What you gain: The 1–2 dimensions where it clearly wins
- What you pay: The 1–2 dimensions where it forces a real cost
- The hidden trap: A non-obvious second-order consequence (e.g., "this option is cheap now but couples deploys, so velocity degrades as the team grows")
Step 6: Assess Reversibility
Classify the decision as a one-way door (expensive or impossible to reverse) or a two-way door (cheap to undo). For one-way doors, raise the bar for confidence and recommend de-risking experiments. For two-way doors, recommend biasing toward speed and learning in production.
Step 7: Make the Recommendation
Name one option as the recommendation. Justify it in 3–4 sentences tied directly to the hard constraints, priorities, and time horizon. State the conditions under which you'd choose differently (e.g., "if compliance scope expands to PII, switch to Option B"). Be decisive — do not present a tie.
Step 8: Define the Validation Signal
Specify what to measure in the first 30–90 days to confirm the decision was right, and the leading indicator that would signal it was wrong early enough to course-correct.
Output Format
- Structure: Decision frame → dimension weights → per-dimension scoring → weighted matrix table → trade-off breakdown per option → reversibility assessment → recommendation → validation signal
- Length: 1,000–1,400 words
- Format: Structured document with one scoring table; trade-offs as labeled bullets per option; recommendation as decisive prose
- Sections: The Decision → Dimension Weights → Scoring Matrix → Trade-Offs by Option → Reversibility → Recommendation → Validation Signal (First 90 Days)
- Tone: Staff engineer in a design review — precise, opinionated, grounded in the specific system, allergic to hand-waving
Quality Checklist
Before delivering output, verify:
- [ ] Every option is scored across all six dimensions (count the cells: options × 6)
- [ ] The weighted matrix math is correct and the totals reflect the stated weights
- [ ] Each dimension justification references the specific system context, not generic principles
- [ ] Every option has a stated "hidden trap" — a non-obvious second-order cost
- [ ] The decision is classified as one-way or two-way door
- [ ] A single recommendation is made (no tie) with explicit conditions for choosing differently
- [ ] Dimension weights tie back to the user's stated priorities, or the equal-weighting default is flagged
Notes
- The most common failure in architecture decisions is optimizing for scalability the system will never need while ignoring the maintainability cost the team pays every day — weight for the constraints that are real now, not the ones that flatter the design.
- Reversibility is the single most underused lens. A two-way door rarely deserves a three-week analysis; ship the reversible option and learn.
- When two options score within ~10% on the weighted matrix, the matrix isn't the decider — the team's existing operational expertise usually is. Favor what the team can already run well.
- If the user provides only one option, treat "do nothing / keep the status quo" as the implicit second option and score it honestly.
How to use this skill
This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.
Installing in Claude Code:
~/.claude/skills/<folder-name>/SKILL.md— auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)<your-project>/.claude/skills/<folder-name>/SKILL.md— auto-loads only when working in that project (recommended for project-specific skills)
Restart Claude Code or open a new session to register.
Using in Claude.ai, ChatGPT, Gemini, or other AI tools:
- Drag this file into a new chat, or copy and paste its contents
- Send your task or request as your next message — the AI will apply the skill where it fits
For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills