system-design-reviewer

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)

1. Understand the decision or question being asked
2. Identify the key trade-off dimensions
3. Score each option across dimensions
4. Recommend with rationale

Full Version (comprehensive design review)

1. Gather context — read existing code, configs, docs, README
2. Identify decisions — list implicit and explicit architectural decisions in the codebase
3. 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)
4. Identify risks — what could break at 10x scale, 100x scale?
5. 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]