planning-stories

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):

1. Receive a story description from the user
2. Ask clarifying questions if needed
3. Break down the story into small, testable tasks
4. Save to STORY.<name>.md
5. 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:

1. Database/Schema changes - migrations, new columns, new tables
2. Backend/Repository layer - data access, queries, mutations
3. API/Service layer - endpoints, business logic
4. 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.txt files (unless the user explicitly asked for them)