Epic Breakdown

epic-breakdown

Step 0: Read Template First

Before any other action — load both required templates through the executable contract:

python3 .speck/scripts/context/speck_context.py epic-breakdown

Require exit 0 and SPECK_CONTEXT_RECEIPT before any mutation. The receipt includes the breakdown and story templates; do not load them again.

Checkpoint: After reading, note the story table format and dependency notation. Then continue to Step 1.

Create a comprehensive story breakdown that maps all user stories within the epic, showing dependencies, parallelization opportunities, and suggested implementation order. This is NOT about concrete development tasks - it's about story organization and sequencing.

1. Load epic implementation context:

   • Epic specification (epic.md)
   • Technical specification (epic-tech-spec.md) - required (includes embedded research)
   • Epic codebase scan (epic-codebase-scan.md) - if exists, for brownfield code analysis
   • Project constraints from PRD
   • If tech spec missing: ERROR "Run /epic-plan first"

   Load Constitution Chain (if present):

   • [EPIC_DIR]/constitution.md — epic-level principles governing story boundaries, interfaces, and quality standards. Use when deciding how to slice stories (e.g., data ownership rules might force a story boundary; API versioning rules might require a dedicated contract story).
   • specs/projects/[PROJECT_ID]/constitution.md — project-level principles to honour across all stories.

   Brownfield Adaptation: If epic-codebase-scan.md exists, use it to identify existing code that needs refactoring or enhancement as part of story breakdown.

   Note: Research is now embedded in epic-tech-spec.md - no separate research.md file to load.

2. Story extraction and analysis:

   • Extract all user stories from epic.md
   • Map to technical implementation from tech spec
   • Identify story dependencies
   • Determine parallelization opportunities

3. Story breakdown approach:

   User Stories

   • Extract all user stories from epic.md
   • Map to technical approach from tech spec
   • Include acceptance criteria
   • Identify dependencies between stories

   Technical Stories

   • Infrastructure setup stories
   • Integration stories
   • Migration stories
   • Configuration stories

   Quality Stories

   • Testing stories
   • Documentation stories
   • Performance validation stories
   • Security review stories

4. Generate epic breakdown:

   CRITICAL: Follow the receipted breakdown template exactly.

   Write output to: [EPIC_DIR]/epic-breakdown.md

5. Create story directories with placeholder specs:

   Subagent Parallelization - Spawn speck-scribe for each story spec:

   ├── [Parallel] speck-scribe: Draft S001 spec.md (Draft state) from epic-tech-spec.md
   ├── [Parallel] speck-scribe: Draft S002 spec.md (Draft state) from epic-tech-spec.md
   ├── [Parallel] speck-scribe: Draft S003 spec.md (Draft state) from epic-tech-spec.md
   └── [Wait] → Create all story directories with drafted specs
   

   Each speck-scribe receives:

   • Story requirements from epic-breakdown.md
   • Technical context from epic-tech-spec.md
   • Template from .speck/templates/story/story-template.md
   • Dependencies from epic-breakdown.md (for YAML frontmatter)

   Speedup: Nx (where N = number of stories)

   IMPORTANT: Placeholder specs are saved as spec.md with lifecycle state Draft (Placeholder). The lifecycle state — not the filename — is what signals that /story-specify still needs to run. This eliminates the spec-draft.md vs spec.md confusion: there is always exactly one file.

   CRITICAL — Lifecycle state for placeholder spec.md files: Set **Current State**: Draft (Placeholder) and mark lifecycle checkboxes as:

   - [x] **Draft** - Placeholder spec.md created by `/epic-breakdown` (not yet specified)
   - [ ] **Specified** - spec.md enhanced by `/story-specify`
   

   NEVER set **Current State**: Specified in a placeholder — that falsely signals that /story-specify has already been run and can be skipped.

   CRITICAL: Include dependencies in YAML frontmatter:

   ---
   depends_on: [S004]  # From "Depends on" in epic-breakdown.md
   blocks: [S006]      # From Inter-Story Dependencies table
   ---
   

   The orchestrator reads depends_on from spec.md to determine which stories are blocked.

   Create story directories:

   [EPIC_DIR]/
   └── stories/
       ├── S001-technical-setup/
       │   └── spec.md (lifecycle: Draft, depends_on: [] in frontmatter)
       ├── S005-story-name/
       │   └── spec.md (lifecycle: Draft, depends_on: [S004] in frontmatter)
       └── .../
   

6. Save as [EPIC_DIR]/epic-breakdown.md

6b. Update Traceability Matrix Mapping (REQUIRED — conservation law):

• Read the existing [EPIC_DIR]/traceability-matrix.md (created by /epic-plan).
• For every PRM-NNN row, map it to the newly created story and AC ref by filling in the Discharge (story-id + AC-ref) column (e.g. S001 / AC-2).
• Re-read the promise text and the target AC together. The AC must assert the same actor, protected boundary, and outcome; shared vocabulary alone is not a semantic match. Correct any wrong-promise/wrong-AC pairing before save.
• Update its Status from open to mapped (or pilot-gated if retrofitted/deferred).
• Verify that there are zero open rows left in the matrix. Any unmapped/open rows remaining will block /analyze --level epic as a P1 unresolved promise.
• After the final breakdown, placeholder, and matrix edit, run bash .speck/scripts/validation/validators/validate-traceability-matrix.sh --check-fidelity "$EPIC_DIR" as a standalone command event. Do not chain, pipe, or wrap it, and do not mutate afterward; the recorded exit must belong to this validator. Treat every fidelity warning as a mapping review item, not a pass.

7. Resume the canonical epic flow in root AGENTS.md. Placeholder lifecycle state, not chat output, tells downstream routing that /story-specify is still required.

Note: This breakdown organizes stories for planning and coordination. Each story will generate its own concrete implementation tasks via /story-tasks. Placeholder specs provide a starting point but require /story-specify to reach "Specified" state before planning or implementation.