annotations/.cursor/skills/plan/templates/epic-spec.md

Epic Template

Use this template for each epic. Create epics via the configured work item tracker (see autodev/protocols.md for tracker detection).

---

## Epic: [Component Name] — [Outcome]

**Example**: Data Ingestion — Near-real-time pipeline

**epic_type**: [component | bootstrap | cross-cutting | tests]
**concern** (cross-cutting only): [logging | error-handling | config | authn | authz | feature-flags | telemetry | i18n | other-named-concern]

### Epic Summary

[1-2 sentences: what we are building + why it matters]

### Problem / Context

[Current state, pain points, constraints, business opportunities.
Link to architecture.md and relevant component spec.]

### Scope

**In Scope**:
- [Capability 1 — describe what, not how]
- [Capability 2]
- [Capability 3]

**Out of Scope**:
- [Explicit exclusion 1 — prevents scope creep]
- [Explicit exclusion 2]

### Assumptions

- [System design assumption]
- [Data structure assumption]
- [Infrastructure assumption]

### Dependencies

**Epic dependencies** (must be completed first):
- [Epic name / ID]

**External dependencies**:
- [Services, hardware, environments, certificates, data sources]

### Effort Estimation

**T-shirt size**: S / M / L / XL
**Story points range**: [min]-[max]

### Users / Consumers

| Type | Who | Key Use Cases |
|------|-----|--------------|
| Internal | [team/role] | [use case] |
| External | [user type] | [use case] |
| System | [service name] | [integration point] |

### Requirements

**Functional**:
- [API expectations, events, data handling]
- [Idempotency, retry behavior]

**Non-functional**:
- [Availability, latency, throughput targets]
- [Scalability, processing limits, data retention]

**Security / Compliance**:
- [Authentication, encryption, secrets management]
- [Logging, audit trail]
- [SOC2 / ISO / GDPR if applicable]

### Design & Architecture

- Architecture doc: `_docs/02_document/architecture.md`
- Component spec: `_docs/02_document/components/[##]_[name]/description.md`
- System flows: `_docs/02_document/system-flows.md`

### Definition of Done

- [ ] All in-scope capabilities implemented
- [ ] Automated tests pass (unit + blackbox)
- [ ] Minimum coverage threshold met (75%)
- [ ] Runbooks written (if applicable)
- [ ] Documentation updated

### Acceptance Criteria

| # | Criterion | Measurable Condition |
|---|-----------|---------------------|
| 1 | [criterion] | [how to verify] |
| 2 | [criterion] | [how to verify] |

### Risks & Mitigations

| # | Risk | Mitigation | Owner |
|---|------|------------|-------|
| 1 | [top risk] | [mitigation] | [owner] |
| 2 | | | |
| 3 | | | |

### Labels

- `component:[name]`
- `env:prod` / `env:stg`
- `type:platform` / `type:data` / `type:integration`

### Child Issues

| Type | Title | Points |
|------|-------|--------|
| Spike | [research/investigation task] | [1-3] |
| Task | [implementation task] | [1-5] |
| Task | [implementation task] | [1-5] |
| Enabler | [infrastructure/setup task] | [1-3] |

---

Guidance Notes

• Be concise. Fewer words with the same meaning = better epic.
• Capabilities in scope are "what", not "how" — avoid describing implementation details.
• Dependency order matters: epics that must be done first should be listed earlier in the backlog.
• Every component epic maps to exactly one component. If a component is too large for one epic, split the component first.
• A cross-cutting epic maps to exactly one shared concern and parents exactly one shared implementation task. Component epics that consume the concern declare the cross-cutting epic as a dependency.
• Valid epic_type values:
  • bootstrap — the initial-structure epic (always exactly one per project)
  • component — a normal per-component epic
  • cross-cutting — a shared concern that spans ≥2 components
  • tests — the blackbox-tests epic (always exactly one)
• Complexity points for child issues follow the project standard: 1, 2, 3, 5, 8. Do not create issues above 5 points — split them.