Architectural Design
Think through system design decisions rigorously before writing them down. This skill is about the thinking — requirements, components, trade-offs, boundaries. When the design is ready, you MUST invoke Skill("write-docs") to write the design document — do not write the doc inline.
Scale to Complexity
Not every decision needs all 5 phases. Match the depth to the decision:
- Small (single component, clear constraints) — Phase 1 briefly, Phase 2, Phase 5. Skip deep dive and scaling.
- Medium (multi-component, some unknowns) — All 5 phases, but keep each concise.
- Large (new system, significant unknowns, cross-team) — All 5 phases in full depth, with diagrams and explicit load estimates.
Red Flag
Never:
- Skip requirements gathering and jump straight to a solution
- Design without understanding existing constraints (tech stack, team, timeline)
- Omit trade-off analysis — every decision has alternatives that were rejected for a reason
- Skip the Boundaries section — it's the core anti-drift mechanism
- Propose a design without verifying assumptions against the actual codebase
- Conflate "what we want" with "what exists" — be explicit about the gap
Phase 1: Requirements Gathering
Before designing anything, understand what you're solving.
Functional Requirements
- What must the system do? List concrete capabilities.
- What are the input/output contracts?
- What user-facing behaviors are required?
Non-Functional Requirements
- Latency: What response times are acceptable? (p50, p99)
- Throughput: How many requests/events per second?
- Availability: What uptime target? (99.9%? 99.99%?)
- Consistency: Strong consistency required, or eventual is acceptable?
- Data volume: How much data now? Growth rate?
Constraints
- Existing tech stack and infrastructure
- Team size and expertise
- Timeline and budget
- Compliance and regulatory requirements
- Backward compatibility requirements
Phase 2: High-Level Design
Map out the major components and how they interact.
- Component diagram: Major services/modules and their responsibilities. Each component should have a single clear purpose. Use ASCII art, mermaid, or a described diagram — the format matters less than clarity.
- Data flow: How data moves through the system — request paths, event flows, data pipelines. A sequence diagram helps for complex flows.
- API contracts: Key interfaces between components. Define input/output shapes, not implementation.
- Storage choices: Which database(s), why. Access patterns determine storage choice, not the other way around.
Phase 3: Deep Dive
Go deep on the components that matter most.
- Data model: Entities, relationships, indexes. Think about access patterns — how will this data be queried?
- API design: REST vs GraphQL vs gRPC. Endpoint structure, authentication, rate limiting, versioning strategy.
- Caching strategy: What to cache, invalidation approach, TTL. Cache only what's read-heavy and tolerant of staleness.
- Async and queues: What needs to be asynchronous? Retry policies, dead-letter queues, idempotency.
- Error handling: Failure modes for each component. Fallback strategies, circuit breakers, graceful degradation.
Phase 4: Scale and Reliability
Design for the load you'll actually face, not hypothetical scale.
- Load estimation: Back-of-envelope calculations for storage, bandwidth, compute. Ground these in real numbers.
- Scaling strategy: Horizontal vs vertical. Sharding strategy if needed. Read replicas.
- Failover: What happens when each component fails? Single points of failure?
- Monitoring: Key metrics to track, alerting thresholds, dashboards. What does "healthy" look like?
Phase 5: Trade-off Analysis
Every design decision has trade-offs. Make them explicit.
For each major decision:
- What alternatives were considered (at least 2)
- Pros and cons of each (concrete, not vague)
- Why this choice won (the deciding factor)
- What we're giving up (be honest about costs)
Common trade-off dimensions:
- Consistency vs availability
- Simplicity vs flexibility
- Build vs buy
- Latency vs throughput
- Cost vs performance
- Team familiarity vs best tool for the job
What to Revisit
Before wrapping up, flag decisions that won't age well:
- Load-dependent: "This works at 1k rps but needs rethinking at 10k" — name the threshold.
- Time-bound: "We chose X because Y isn't ready yet" — note when to re-evaluate.
- Assumption-sensitive: "If we go multi-region, the consistency model breaks" — link to the assumption.
These aren't weaknesses — they're honest engineering. A design that claims to handle everything forever is hiding its assumptions.
Design Document Output
When the design thinking is complete, the result should be written as a design document. Every design doc needs:
- Boundaries section (required) — what this design does NOT cover, what must not change without updating this doc. This is the core anti-drift mechanism.
- Trade-offs section (recommended) — the alternatives considered and why this choice won.
- Assumptions section (recommended) — what must be true for this design to hold (e.g., "assumes < 10k concurrent users", "assumes single-region deployment"). When assumptions change, the design is stale.
When the design thinking is complete, invoke Skill("write-docs") to write the design document with category design. Do not write the doc inline — the write-docs skill enforces frontmatter, numbering, and index generation.
Execution Handoff
After writing the doc via write-docs, output the report card (read skills/.shared/report-card.md for the standard format):
## [Arch Design] Report Card
| Field | Value |
|-------|-------|
| Status | <DONE / BLOCKED> |
| Summary | <one-line: what was designed and the key decision> |
### Metrics
| Metric | Value |
|--------|-------|
| Phases completed | <N>/5 |
| Trade-offs analyzed | <N> |
| Revisit items | <N> |
### Next Steps
1. **Write the doc (required)** — /ship:write-docs with category design
2. **Full workflow** — /ship:auto to implement the design
3. **Plan implementation** — /ship:design to create executable stories