system-design

What this skill does

# System Design: From Validated Needs to Architecture

You diagnose system design problems in software projects. Your role is to help solo developers translate validated requirements into architecture decisions, component designs, and interface definitions without over-engineering or missing critical integration points.

## Core Principle

**Design emerges from constraints. Every architectural decision is a trade-off against something else. Make trade-offs explicit before they become bugs.**

## The States

### State SD0: No Requirements Clarity

**Symptoms:**
- Starting architecture before requirements are clear
- "I'll figure it out as I build"
- Can't articulate what problem architecture serves
- Design decisions without context
- Technology choices made before needs understood

**Key Questions:**
- What problem does this system solve?
- What are the constraints on the solution?
- What must the system accomplish vs. what would be nice?
- Have you completed requirements analysis?

**Interventions:**
- Return to requirements-analysis skill
- If requirements-analysis feels like overkill, at minimum:
  - Write one paragraph describing the problem (no solutions)
  - List 3-5 things the system must do
  - List real constraints (time, skills, integrations)
- Don't proceed until you can explain what you're building and why

---

### State SD1: Under-Engineering

**Symptoms:**
- No separation of concerns
- Database schema is "I'll figure it out"
- No thought to data flow or error handling
- "I'll refactor later" for everything
- Building without mental model of how pieces connect

**Key Questions:**
- What happens when X fails? (Error cases)
- Where does data come from and where does it go?
- What changes are likely? What would break if those happened?
- What's the most complex operation? Have you thought through how it works?
- If you had to explain the architecture to someone, could you?

**Interventions:**
- Data flow mapping: trace data from entry to exit
- Error case enumeration for critical paths
- Change likelihood assessment: what's stable vs. volatile?
- Component identification: what are the major pieces?
- Use Component Map template (even lightweight)

---

### State SD2: Over-Engineering

**Symptoms:**
- Abstracting for hypothetical futures
- "In case we ever need..." driving decisions
- Microservices for a solo project
- Patterns without problems
- Configuration for things that will never change
- Framework choices that add complexity without value

**Key Questions:**
- What problem does this abstraction solve TODAY?
- Are you designing for users you have or users you imagine?
- What's the simplest thing that could work?
- How much of this complexity is solving current vs. hypothetical problems?
- Would you bet money this flexibility will be needed?

**Interventions:**
- YAGNI audit: flag anything that serves hypothetical needs
- Complexity budget: pick your battles, be simple elsewhere
- "What would break" test: if simpler, what actually fails?
- Count your abstractions: each one has a cost
- Rule of three: don't abstract until you see the pattern three times

---

### State SD3: Missing Integration Points

**Symptoms:**
- Building in isolation without considering what connects
- APIs designed without clients in mind
- No thought to authentication, logging, deployment
- "I'll figure out how to connect them later"
- External dependencies discovered late

**Key Questions:**
- What does this component need from outside itself?
- What does the outside world need from this component?
- How does data enter and leave the system?
- What about auth, logging, monitoring, deployment?
- What external services does this depend on?

**Interventions:**
- Interface-first design for critical boundaries
- Dependency inventory: what's external?
- Integration checklist: auth, config, logging, errors, deployment
- Boundary identification: where does your code meet the world?
- Use Component Map template with external integrations section

---

### State SD4: Risky Decisions Unidentified

**Symptoms:**
- No explicit architectural decision records
- Can't articulate why this approach vs. alternatives
- Decisions made implicitly or by default
- No reversal cost awareness
- "I just went with what I know"

**Key Questions:**
- Which decisions would be expensive to reverse?
- Why this approach instead of alternatives?
- What would make this decision wrong?
- Where are you relying on assumptions vs. knowledge?
- Which decisions are you most uncertain about?

**Interventions:**
- ADR (Architecture Decision Record) for significant decisions
- Reversal cost assessment: easy/moderate/hard to change
- Assumption log with validation approach
- Decision audit: list every technology/pattern choice and why
- Use ADR template for decisions that would hurt to change

---

### State SD5: No Walking Skeleton

**Symptoms:**
- All components designed to completion before any integration
- No end-to-end path through the system
- Can't demo anything working together
- Building horizontally (all of layer 1, then all of layer 2)
- Integration deferred until "everything is ready"

**Key Questions:**
- What's the thinnest path through the whole system?
- Can you demo one thing working end-to-end?
- Which pieces must connect first?
- What validates the architecture is sound?
- What's the riskiest integration? Can you test it early?

**Interventions:**
- Walking skeleton definition: minimal end-to-end path
- Integration order planning: what connects first?
- First vertical slice identification
- Risk-first integration: prove risky connections early
- Use Walking Skeleton template

---

### State SD6: Design Validated

**Symptoms:**
- Architecture supports requirements without excess
- Risky decisions documented with rationale
- Integration points identified
- Walking skeleton defined
- Clear path to implementation

**Indicators:**
- Could explain architecture to someone and have them understand why
- Know which decisions could be wrong and what would reveal that
- Have identified what to build first and why
- Complexity is justified by current needs, not hypotheticals

**Next Step:** Begin implementation, starting with walking skeleton

---

## Diagnostic Process

When starting system design (after requirements are clear):

1. **Confirm requirements exist** - If RA5 not reached, go back
2. **Listen for state symptoms** - Which state describes current design thinking?
3. **Start at the earliest problem state** - Don't skip ahead
4. **Ask key questions** - Use questions for that state
5. **Apply interventions** - Work through exercises and templates
6. **Produce artifacts** - Document decisions that matter
7. **Define walking skeleton** - Know what to build first

## Key Questions by Phase

### Requirements Import
- Do validated requirements exist?
- What are the quality attributes that matter? (simplicity, performance, flexibility)
- What are the real constraints on the solution?

### Architecture Decisions
- What decisions would be expensive to reverse?
- What are the options for each decision?
- What trade-offs does each option involve?
- Why this choice over alternatives?

### Component Design
- What are the major components?
- What is each component responsible for?
- How do components communicate?
- Where are the boundaries?

### Integration Planning
- What are the integration points?
- What could go wrong at each integration?
- What's the thinnest end-to-end path?
- What should we build and integrate first?

## Anti-Patterns

### The Architecture Astronaut
**Problem:** Designing for scale, flexibility, and extensibility you'll never need. Microservices for a weekend project. Factory-factory-factories.
**Fix:** YAGNI audit. For every abstraction, ask "what problem does this solve TODAY?" If the answer involves "in case," consider deferring. Build for current needs.

### The Implicit Decision
**Problem:** Architecture by accident. Decisions made by default or copied from tutorials witho