admin/.cursor/skills/plan/steps/06_work-item-epics.md

Step 6: Work Item Epics

Role: Professional product manager

Goal: Create epics from components, ordered by dependency

Constraints: Epic descriptions must be comprehensive and self-contained — a developer reading only the epic should understand the full context without needing to open separate files.

0. Consult LESSONS.md — if _docs/LESSONS.md exists, read it and factor any estimation / architecture / dependencies entries into epic sizing, scope, and dependency ordering. This closes the retrospective feedback loop; lessons from prior cycles directly inform current epic shape. Note in the Step 6 output which lessons were applied (or that none were relevant).
1. Create "Bootstrap & Initial Structure" epic first — this epic will parent the 01_initial_structure task created by the decompose skill. It covers project scaffolding: folder structure, shared models, interfaces, stubs, CI/CD config, DB migrations setup, test structure.
2. Identify cross-cutting concerns from architecture.md and restrictions.md. Default candidates to consider (include only if architecture/restrictions reference them):
   • Logging / observability (structured logging, correlation IDs, metrics)
   • Error handling / envelope / result types
   • Configuration loading (env vars, config files, secrets)
   • Authentication / authorization middleware
   • Feature flags / toggles
   • Telemetry / tracing
   • i18n / localization For each identified concern, create ONE epic named Cross-Cutting: <name> with epic_type: cross-cutting. Each cross-cutting epic will parent exactly ONE shared implementation task (placed under src/shared/<concern>/ by decompose skill). All component-level tasks that consume the concern declare the shared task as a dependency — they do NOT re-implement the concern locally. This rule is enforced by code-review Phase 6 (Cross-Task Consistency) and Phase 7 (Architecture Compliance).
3. Generate epics for each component using the configured work item tracker (see autodev/protocols.md for tracker detection), structured per templates/epic-spec.md
4. Order epics by dependency: Bootstrap epic first, then Cross-Cutting epics (they underlie everything), then component epics in dependency order
5. Include effort estimation per epic (T-shirt size or story points range). Use LESSONS.md estimation entries as a calibration hint — if a lesson says "component X was underestimated by 2x last time" and the current plan has a comparable component, widen that epic's estimate.
6. Ensure each epic has clear acceptance criteria cross-referenced with component specs
7. Generate Mermaid diagrams showing component-to-epic mapping and component relationships; include cross-cutting epics as horizontal dependencies of every consuming component epic

CRITICAL — Epic description richness requirements:

Each epic description MUST include ALL of the following sections with substantial content:

• System context: where this component fits in the overall architecture (include Mermaid diagram showing this component's position and connections)
• Problem / Context: what problem this component solves, why it exists, current pain points
• Scope: detailed in-scope and out-of-scope lists
• Architecture notes: relevant ADRs, technology choices, patterns used, key design decisions
• Interface specification: full method signatures, input/output types, error types (from component description.md)
• Data flow: how data enters and exits this component (include Mermaid sequence or flowchart diagram)
• Dependencies: epic dependencies (with tracker IDs) and external dependencies (libraries, hardware, services)
• Acceptance criteria: measurable criteria with specific thresholds (from component tests.md)
• Non-functional requirements: latency, memory, throughput targets with failure thresholds
• Risks & mitigations: relevant risks from risk_mitigations.md with concrete mitigation strategies
• Effort estimation: T-shirt size and story points range
• Child issues: planned task breakdown with complexity points
• Key constraints: from restrictions.md that affect this component
• Testing strategy: summary of test types and coverage from tests.md

Do NOT create minimal epics with just a summary and short description. The epic is the primary reference document for the implementation team.

Self-verification:

• "Bootstrap & Initial Structure" epic exists and is first in order
• Every identified cross-cutting concern has exactly one Cross-Cutting: <name> epic
• No two epics own the same cross-cutting concern
• "Blackbox Tests" epic exists
• Every component maps to exactly one component epic
• Dependency order is respected (no epic depends on a later one)
• Cross-Cutting epics precede every consuming component epic
• Acceptance criteria are measurable
• Effort estimates are realistic and reflect LESSONS.md calibration hints (if any applied)
• Every epic description includes architecture diagram, interface spec, data flow, risks, and NFRs
• Epic descriptions are self-contained — readable without opening other files

8. Create "Blackbox Tests" epic — this epic will parent the blackbox test tasks created by the /decompose skill. It covers implementing the test scenarios defined in tests/.

Save action: Epics created via the configured tracker MCP. Also saved locally in epics.md with ticket IDs. If tracker: local, save locally only.