---
name: design
description: >
  Kick off Phase 3 (Design). Produces the official system design with architecture
  diagrams, component breakdown, and interface definitions. Delegates to the architect agent.
---

# Phase 3: Design

You are beginning the Design phase. Your goal is to produce a complete system design that translates research into a buildable architecture.

## Prerequisites

- Approved research report from Phase 2 (check `docs/research/`)
- If no research report exists, run `/research` first.

## Process

1. **Review inputs.** Read the problem statement and research report. Summarize key constraints and decisions.
2. **Delegate to architect.** The `architect` agent should produce:
   - System overview with Mermaid architecture diagram
   - Component breakdown with responsibilities
   - Interface definitions between every component (inputs, outputs, errors)
   - Data flow diagram
   - Dependency map
   - Technology choices justified against research findings
3. **Cross-reference.** Verify the design covers:
   - Every requirement in the problem statement
   - Every recommendation from the research report
   - Modularity — can each component be extracted into another project?
   - Provider agnosticism — are external services abstracted?
   - Observability — metrics, logging, health checks designed in?
4. **Risk assessment.** Identify:
   - Single points of failure
   - Components with the highest uncertainty
   - Integration risks between components
   - Scaling bottlenecks
5. **Save** the design document to `docs/designs/<project-slug>-<date>.md`
6. **Present to user** with a summary of the architecture and any open design decisions that need input.
7. **Ask for approval** before moving to Phase 4 (Specification).

## Output: Design Document Template

```markdown
## System Design: [Project Name]
### Date: [date]
### Status: Draft | Approved

### Architecture Overview
[Mermaid diagram here]

[Text description of the architecture for accessibility]

### Components
#### [Component Name]
- **Responsibility:** [what it does]
- **Technology:** [language/framework/tool]
- **Inputs:** [what it receives]
- **Outputs:** [what it produces]
- **Dependencies:** [what it needs]

### Interfaces
#### [Component A] ↔ [Component B]
- Protocol: [REST/gRPC/message queue/etc.]
- Data format: [JSON/Protobuf/etc.]
- Error handling: [how failures are communicated]

### Data Flow
[Mermaid sequence or flow diagram]

### Risk Assessment
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| ...  | ...       | ...    | ...        |

### Design Decisions
| Decision | Options Considered | Chosen | Rationale |
|----------|--------------------|--------|-----------|
| ...      | ...                | ...    | ...       |

### Open Questions
[Anything requiring user input before spec phase]
```

## Rules

- Every component must have defined interfaces before proceeding
- All Mermaid diagrams must have accompanying text descriptions
- Design decisions must document alternatives considered, not just what was chosen
- Do not proceed to Phase 4 without explicit user approval
