| name | system-design-reviewer |
| description | Use this skill to review system design, evaluate architectural trade-offs,
or create Architecture Decision Records (ADRs).
MANDATORY TRIGGERS: system design, design review, trade-off analysis, ADR,
architecture decision record, scalability review, design document review,
technical decision, should we use, which approach, design trade-offs.
Also use when: comparing technology choices, evaluating migration strategies,
reviewing RFC or design docs, assessing scalability and reliability,
documenting why a decision was made.
Do NOT use for: code-level architecture mapping (use architecture-analyzer)
or CI/CD pipeline review (use pipeline-auditor).
|
| metadata | {"author":"N.V","version":"1.0"} |
| allowed-tools | Read, Grep, Glob, Bash |
Overview
Reviews system design decisions by analyzing existing code, configs, and documentation.
Evaluates trade-offs across dimensions (scalability, complexity, cost, team fit)
and produces structured recommendations or Architecture Decision Records (ADRs).
When to Use This Skill
- Evaluating whether a design choice is appropriate for the project
- Comparing two or more technical approaches (e.g., "monolith vs microservices")
- Reviewing an existing RFC or design document
- Creating an ADR to document why a decision was made
- Assessing scalability, reliability, or maintainability risks
- Preparing for a tech lead / architect review meeting
Workflow
Quick Version (single decision review)
- Understand the decision or question being asked
- Identify the key trade-off dimensions
- Score each option across dimensions
- Recommend with rationale
Full Version (comprehensive design review)
- Gather context — read existing code, configs, docs, README
- Identify decisions — list implicit and explicit architectural decisions in the codebase
- Evaluate each decision across trade-off dimensions:
- Scalability (horizontal, vertical, data growth)
- Complexity (learning curve, operational burden)
- Reliability (failure modes, recovery, data integrity)
- Performance (latency, throughput, resource usage)
- Cost (infrastructure, development time, maintenance)
- Team fit (skill set, hiring, onboarding)
- Identify risks — what could break at 10x scale, 100x scale?
- Generate deliverable — trade-off matrix, recommendations, ADR(s)
Trade-Off Analysis Framework
For each decision, evaluate:
| Dimension | Questions to Ask |
|---|
| Scalability | Does it scale horizontally? Vertically? What's the bottleneck? |
| Complexity | How hard to understand? Operate? Debug? |
| Reliability | What are the failure modes? How does it recover? |
| Performance | What's the latency profile? Throughput limits? |
| Cost | Infrastructure cost? Dev time? Ongoing maintenance? |
| Team Fit | Does the team know this tech? Easy to hire for? |
| Migration | How hard to change this decision later? |
ADR Template
# ADR-[NUMBER]: [Decision Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-X]
## Context
[What is the problem or situation that requires a decision?]
## Decision
[What is the decision that was made?]
## Options Considered
### Option A: [Name]
- ✅ [Pro]
- ✅ [Pro]
- ❌ [Con]
### Option B: [Name]
- ✅ [Pro]
- ❌ [Con]
- ❌ [Con]
## Trade-Off Matrix
| Dimension | Option A | Option B |
|-----------|----------|----------|
| Scalability | ⭐⭐⭐ | ⭐⭐ |
| Complexity | ⭐⭐ | ⭐⭐⭐ |
| Cost | ⭐⭐⭐ | ⭐ |
## Consequences
[What are the positive and negative consequences of this decision?]
## Review Date
[When should this decision be revisited?]
Critical Rules
- Always state assumptions — scalability matters at 1K users but not at 50
- No perfect answers — every design is a trade-off; acknowledge what you're giving up
- Consider reversibility — two-way-door decisions are low-risk, one-way-door decisions need more scrutiny
- Ground in the codebase — don't give generic advice; reference actual files, patterns, and constraints
- Include "change later" cost — how painful is it to reverse this decision in 6 months?
Output Format
# System Design Review: [Topic]
## Summary
[1-2 sentence overview of the design question and recommendation]
## Current State
[What exists today in the codebase — cite specific files and patterns]
## Trade-Off Analysis
| Dimension | Current Approach | Alternative |
|-----------|-----------------|-------------|
| Scalability | ⭐⭐ | ⭐⭐⭐ |
| Complexity | ⭐⭐⭐ | ⭐ |
| Reliability | ⭐⭐⭐ | ⭐⭐ |
## Recommendation
[What to do and why — ground in project-specific context]
## Risks If No Action
[What happens if the current approach continues unchanged]
## Action Items
1. [Specific action] — [effort estimate]
