| name | planning-stories |
| description | Break down a user story into multiple testable tasks. Use when user mentions: story, ticket, task breakdown, implement feature, plan implementation, create tasks, split into tasks, story breakdown, task decomposition, acceptance criteria, definition of done, sprint planning, backlog, user story, feature breakdown, ralph, ralph loop, autonomous implementation, .TASK.md, progress.txt, run through ralph. Each task must be independently verifiable. NOTE: Ralph-loop task files (.TASK.md) are generated ONLY when explicitly requested — never automatically during normal story creation. |
| allowed-tools | Read, Write, Grep, Glob, Task, AskUserQuestion |
Planning Stories
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
