Break down user stories into independently testable tasks. Each task is a small, verifiable unit of work that, when completed, contributes to the overall story completion.
⚠️ Two Modes — Read This First
This skill operates in two modes. Know which one you are in before doing anything.
1. Default — Story Planning (what normally happens)
Produces a STORY.<name>.md planning file (and, optionally, a STORY.<name>.TECH-SPEC.md). This is the planning artifact a human reads. It is not executed autonomously. This is the mode used whenever the user asks to plan, break down, or decompose a story.
2. Explicit Only — Ralph Task Generation
Produces Ralph-loop files (<task-name>.TASK.md + <task-name>.progress.txt) that the ralph.sh script runs autonomously, one story per iteration.
CRITICAL RULE
Never generate Ralph task files unless the user EXPLICITLY asks. Trigger only on direct requests such as:
- "break this into Ralph tasks"
- "generate the .TASK.md files"
- "make this runnable by Ralph" / "run this through ralph"
- "create a task breakdown for the ralph loop"
During normal story creation, do NOT emit .TASK.md / .progress.txt files. Producing STORY.<name>.md planning tasks (Step 1–5 below) is fine and expected — that is planning, not Ralph execution.
When mode 2 is explicitly requested, follow the full workflow in ralph-tasks.md.
The Job
Default mode (story planning):
- Receive a story description from the user
- Ask clarifying questions if needed
- Break down the story into small, testable tasks
- Save to
STORY.<name>.md - Spawn a writing-tech-specs subagent to create
STORY.<name>.TECH-SPEC.md
Ralph mode (explicit only): Follow ralph-tasks.md — generate <task-name>.TASK.md + <task-name>.progress.txt next to the story file. Do not enter this mode unless explicitly requested (see the CRITICAL RULE above).
Core Principles
Task Independence
Each task must be:
- Completable in isolation - no dependencies on incomplete tasks
- Testable - has clear verification criteria
- Non-breaking - app continues to work after each task
- Small - completable in one context window (~10 min of AI work)
Task Ordering (Critical)
ALWAYS order by dependency to avoid breaking changes:
- Database/Schema changes - migrations, new columns, new tables
- Backend/Repository layer - data access, queries, mutations
- API/Service layer - endpoints, business logic
- Frontend/UI - components, screens, forms
Wrong order causes broken builds!
Step 1: Analyze the Story
Understand what the user is asking for:
- New feature: Adding new functionality
- Update/Modify: Changing existing behavior
- Bug fix: Correcting incorrect behavior
- Refactor: Improving code without changing behavior
Ask Clarifying Questions If:
- Scope is unclear
- Multiple interpretations possible
- Breaking change risk exists
- Testing strategy is ambiguous
Example Clarifying Questions
- "What should happen when [edge case]?"
- "Is this a breaking change, or should existing behavior still work?"
- "Are there any constraints on [field/feature]?"
- "Should this work for all users or just [specific role]?"
- "What's the rollback strategy if something goes wrong?"
Step 2: Break Down Into Tasks
See examples.md for detailed breakdown patterns.
Quick Reference
| Story Type | Task Order |
|---|---|
| New field | DB → Repository → API → Frontend |
| Update field | Add parallel → Backend → Frontend → Remove old |
| New entity | DB → Repository → API → List UI → Detail UI |
| Bug fix | Identify cause → Add test → Fix → Verify |
Step 3: Define Verification Criteria
Each task MUST have testable verification criteria.
Good Criteria (Verifiable)
- [ ] Migration runs successfully
- [ ] Unit test: new column exists with correct type
- [ ] Typecheck passes
- [ ] App starts without errors
Bad Criteria (Vague)
- [ ] Works correctly
- [ ] User can see the change
- [ ] Good UX
Required Criteria for Every Task
- [ ] Typecheck passes
- [ ] All tests pass
- [ ] App runs without errors
BDD Format (Optional, for complex flows)
Given [context]
When [action]
Then [expected result]
Step 4: Generate STORY..md
File Naming
- Use uppercase STORY prefix with kebab-case name:
STORY.add-user-profile-picture.md - Remove articles: "the", "a", "an"
- Be descriptive but concise
Template Structure
# Story: [Title]
## Overview
[Brief description of what this story accomplishes]
## Dependencies
- [List any existing features/systems this depends on]
- [None if standalone]
---
## Tasks
### Task 1: [Title]
**Layer:** database | backend | api | frontend | cleanup
**Description:**
[What this task does]
**Changes:**
- [Specific file/table/function being changed]
**Verification:**
- [ ] [Specific testable criterion]
- [ ] Typecheck passes
- [ ] All tests pass
- [ ] App runs without errors
---
### Task 2: [Title]
[Same structure as Task 1]
---
## Completion Criteria
The story is complete when:
- [ ] All tasks are verified complete
- [ ] End-to-end flow works as expected
- [ ] No breaking changes to existing functionality
## Rollback Plan
[If something goes wrong, how to revert]
---
## Notes
[Any additional context, assumptions, or decisions made]
Step 5: Spawn a writing-tech-specs subagent
After creating STORY.<name>.md, spawn a subagent to create the technical specification.
Subagent Prompt Template
Read the file STORY.<name>.md and use the writing-tech-specs skill to create a detailed technical specification.
The tech-spec should include:
1. Model changes (database schema)
2. Flow diagrams (backend/frontend flows)
3. API endpoints
4. Happy path description
5. Backwards compatibility notes
Save the output to STORY.<name>.TECH-SPEC.md
Note: The tech-spec file uses the same <name> as the story file with .TECH-SPEC.md appended. For example, if the story is STORY.add-user-auth.md, the tech-spec becomes STORY.add-user-auth.TECH-SPEC.md.
Note: If the writing-tech-specs skill is not available, skip this step and note it in the story file.
Step 6 (OPTIONAL — Explicit Only): Generate Ralph Task Files
Only perform this step if the user explicitly asks for Ralph-loop task files. If they did not, stop here — the story planning is complete.
When explicitly requested, switch to the Ralph workflow documented in ralph-tasks.md and generate:
<task-name>.TASK.md— the task breakdown document<task-name>.progress.txt— empty progress tracking file
Both files are created next to the story file by default, and <task-name> must follow the task-<number>-<description> naming convention (e.g. task-1-add-currency-table.TASK.md). The user then runs ralph.sh <task-name>.TASK.md to execute.
Reminder: This step is opt-in. Never produce these files during ordinary story planning.
When NOT to Break Down
A story is already a good single task if:
- Single file/component change
- No database changes
- No API changes
- Completable in <30 minutes
- Has only one verification path
In this case, just create the story file without breaking into subtasks.
Anti-Patterns to Avoid
| Anti-Pattern | Problem |
|---|---|
| Too granular | "Create file", "Add import" - not real tasks |
| Too broad | "Implement feature" - can't verify in one sitting |
| Mixed layers | Database + frontend in same task |
| Vague verification | "Works correctly" - how do you know? |
| Missing rollback | No way to undo a database migration |
| Forward dependencies | Task 2 depends on Task 5 |
Common Patterns
See patterns.md for detailed patterns:
- Adding a New Field
- Updating an Existing Field
- Adding a New Entity
- Adding a New Relationship
Troubleshooting
| Problem | Solution |
|---|---|
| Story seems too large | Break into smaller subtasks, or split into multiple stories |
| Breaking change detected | Add parallel field/endpoint first, update frontend, then remove old |
| Unclear testing strategy | Ask user for clarification, add manual verification steps |
Checklist Before Saving
- Story is broken into small, testable tasks
- Each task has clear layer (database/backend/api/frontend)
- Tasks are ordered by dependency (no forward dependencies)
- Each task has specific verification criteria
- Every task includes typecheck, tests, and app runs checks
- Breaking changes use parallel fields or phased rollout
- Completion criteria covers the full story
- Rollback plan exists
- File is named
STORY.<name>.md - Did NOT generate Ralph
.TASK.md/.progress.txtfiles (unless the user explicitly asked for them)