Menu
Use when a large task needs to be broken into independent, verifiable stories with pass/fail acceptance criteria
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | story-decomposition |
| description | Use when a large task needs to be broken into independent, verifiable stories with pass/fail acceptance criteria |
| tags | ["process","planning","decomposition"] |
| triggers | ["large task","too big for one session","decompose","break into stories","multiple stories"] |
| chains_to | ["ralph-loop","prd-generator"] |
| priority | core |
| gate | false |
Break a large task into independent stories. Each story must be completable in one context window, have pass/fail acceptance criteria, and be verifiable in isolation.
writing-plans identified the need for decompositionexecuting-plans)Before decomposing:
Good stories have these properties:
Each story follows this format:
## Story N: <Title>
**Goal**: [One sentence — what this delivers]
**Dependencies**: [Story numbers that must complete first, or "none"]
**Files**:
- `path/to/file.ts` — [what changes]
**Acceptance Criteria**:
- [ ] [Concrete, verifiable condition]
- [ ] [Another condition]
**Verification Command**:
```bash
# The exact command(s) to prove this story passes
npm test -- --grep "story-related-tests"
### Step 4: Order Stories
1. Foundation stories first (types, interfaces, schemas)
2. Core logic second (business rules, data layer)
3. Integration third (wiring pieces together)
4. Polish last (error handling, edge cases, UI refinement)
Stories with no dependencies can run in any order.
### Step 5: Validate the Decomposition
Check:
- [ ] Every deliverable from the original plan is covered by at least one story
- [ ] No story is too large (>200 lines of changes is a red flag)
- [ ] Dependencies form a DAG (no circular dependencies)
- [ ] Each story's acceptance criteria are objectively pass/fail
- [ ] The verification command actually tests what the story claims
## Anti-Patterns
| Anti-Pattern | Why It's Wrong |
|--------------|----------------|
| Stories that depend on everything | Not independent. Reorder or merge. |
| "And then do the rest" as a story | Not decomposed. Break it down further. |
| Acceptance criteria like "works correctly" | Not verifiable. What does "correctly" mean? |
| Stories without verification commands | How does the loop know it passed? |
| 20+ stories for a medium task | Over-decomposed. Merge related work. |
| Stories that touch the same files | Will cause conflicts in parallel execution. |
## Chaining
REQUIRED: syntaxninja-dojo:ralph-loop (when stories feed into a training loop)
OPTIONAL: syntaxninja-dojo:prd-generator (to produce the formal PRD document)
Use when a structured PRD document is needed for the ralph loop — generates prd.json and progress.txt
Use when task scope exceeds one context window and decomposes into independent pass/fail stories with clean iteration boundaries
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work — merge, PR, or cleanup
Use when starting feature work that needs isolation from the current workspace or before executing plans that could leave the branch in a broken state
Use when a hard problem was just solved and the solution should be captured as a learning for future reference
Use when 3+ distinct occurrences suggest a skill should be updated with a new trigger, anti-pattern, or verification step