/story - Interactive User Story Management

Create, manage, and track user stories in proper narrative format. Stories feed into Ralph Loop for autonomous implementation.

What It Does

The /story skill provides an interactive workflow for creating well-structured user stories that follow the proven "As a / I want / So that" narrative format. Stories are:

• Narrative-driven - Forces clarity of user role, desired action, and business value
• Validated - Ensures proper format before adding to work queue
• Trackable - Integrates with Ralph Loop for autonomous execution and progress tracking
• Filterable - Search by priority, status, or affected files
• Exportable - Generate markdown summaries for documentation

Quick Start

Create a Story

/story new

You'll be prompted for:

1. User role - "As a [developer/researcher/etc.]"
2. Desired action - "I want to [action]"
3. Business value - "So that [benefit]"
4. Title - Suggested auto-generated from action
5. Priority - 1 (high), 2 (normal), 3 (low)
6. Files - Affected files (comma-separated, optional)
7. Acceptance criteria - Multiple criteria (at least 1 required)

View Stories

/story show                        # List all stories with status
/story view STORY-001             # Show full details for one story
/story list --priority 1          # Filter by priority
/story list --status in_progress  # Filter by status
/story list --files src/auth.ts   # Find stories touching a file

Update Story

/story update STORY-001

Interactively change: status, priority, acceptance criteria

Export

/story export > stories.md

Generate markdown summary grouped by priority and status.

Two Paths: Quick vs Structured

When you run /story new, you choose your approach:

Quick Path (Default)

Traditional narrative format - fast for simple stories.

• User role → Desired action → Business value
• Builds "As a X, I want Y, so that Z" automatically
• Best for: Simple features, quick iterations, clear scope

Structured Path (Prevents Ralph Spiraling)

Ryan's methodology - comprehensive planning for complex work.

• Problem statement (what challenge does this solve?)
• Narrative format (As a / I want / So that)
• Functional requirements (what must the system do?)
• Constraints & non-goals (what's out of scope?)
• Success metrics (how do we measure success?)
• Auto-generates subtasks to prevent infinite iteration loops

Choose Structured when:

• Building large features with many moving parts
• You want Ralph to have clear sub-goals
• You need to prevent "Ralph spiraling" (infinite iteration loops)
• You want detailed requirements documented

Why Structured prevents spiraling:

• Breaks complex work into finite, testable subtasks
• Each subtask has one clear purpose
• Ralph processes TASK-001, TASK-002... in order
• Forces upfront thinking about scope and boundaries

Story Format

Stories follow the user story narrative:

As a [user role]
I want to [desired action]
So that [business value]

Why this format?

• Clarity - Each part serves a specific purpose
• User-focused - Starts with who benefits and why
• Context - Helps Claude understand the bigger picture
• Traceability - Each story has clear reasoning

Example story:

As a developer in a Ralph loop
I want to see my task context in a collapsible JSON card
So that I can quickly reference my context without switching windows

Acceptance Criteria:
- Card displays TIER 0 project context
- Card shows top 5 relevant golden rules for current domain
- JSON is syntax-highlighted (keys, values, strings colored differently)
- Card has 'Collapse all' button to minimize nested objects
- Card loads in <500ms
- Works offline (no external CDN dependencies)

Story Lifecycle

pending (waiting for work)
   ↓
in_progress (Ralph Loop assigned it)
   ↓
done ✓ (Ralph completed + tests passed)

OR blocked ✗ (Ralph encountered an issue)

Automatic transitions:

• Ralph Loop changes status to in_progress when starting work
• Status becomes done if implementation + tests succeed
• Status becomes blocked if tests fail or error occurs
• Manual update via /story update as needed

Commands Reference

/story new

Create a new story interactively.

First, you choose your path: [Q] Quick (default) or [S] Structured

Quick Path Prompts

1. Story ID (auto-suggest next available)
2. Path choice: [Q/S, default=Q]
3. User role (As a)
4. Desired action (I want to)
5. Business value (So that)
6. Title (auto-suggested from action)
7. Priority (1-3)
8. Files (comma-separated, optional)
9. Acceptance criteria (blank to finish, at least 1)

Structured Path Prompts

1. Story ID (auto-suggest next available)
2. Path choice: [S]
3. Problem statement (What problem does this solve?)
4. User role (As a)
5. Desired action (I want to)
6. Business value (So that)
7. Title (auto-suggested)
8. Priority (1-3)
9. Functional requirements (blank to finish)
10. Constraints & non-goals (blank to finish)
11. Success metrics (blank to finish, at least 1 recommended)
12. Files (comma-separated, optional)
13. Acceptance criteria (blank to finish, at least 1)
14. Generate subtasks? [Y/n, default=Y]
    • If yes: Automatically creates TASK-001, TASK-002... for each requirement

Output (Quick Path):

✓ Created story: [STORY-001] Your Story Title

Output (Structured Path):

✓ Created story: [STORY-006] Your Story Title
  Linked subtasks: 4

/story show

List all stories with visual status and brief info.

Output:

STORIES (5 total, 2 complete)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[ ] [P1] STORY-001: User Authentication
     Status: pending | Files: 2

[~] [P2] STORY-002: Dashboard UI
     Status: in_progress | Files: 4

[X] [P1] STORY-003: Database Migration
     Status: done | Files: 3

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Status icons: [ ] pending, [~] in_progress, [X] done, [!] blocked

/story view STORY-001

Show complete details for a single story.

Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STORY-001: User Authentication
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Description:
  As a developer, I want to implement JWT-based authentication,
  so that users can login securely.

Priority: 1 (High)
Status: pending

Acceptance Criteria:
  - Users can login with email/password
  - JWT tokens are issued on successful auth
  - Protected routes require valid token
  - Token expiration is enforced

Files:
  - src/auth/login.ts
  - src/auth/middleware.ts
  - tests/auth.test.ts

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

/story update STORY-001

Interactively modify a story's status, priority, or criteria.

Prompts:

• Status (pending/in_progress/done/blocked)
• Priority (1-3)
• New acceptance criteria (optional)

Output:

✓ Updated story STORY-001

/story list [OPTIONS]

Filter and display stories matching criteria.

Options:

--priority 1|2|3              # Filter by priority
--status pending|in_progress|done|blocked  # Filter by status
--files src/path/file.ts      # Find stories touching specific file

Examples:

/story list --priority 1                    # All high-priority stories
/story list --status in_progress            # What Ralph is currently working on
/story list --files src/components/Card.tsx # Stories affecting Card component

/story export

Generate markdown summary of all stories.

Output: Markdown file with:

• Summary stats (total, complete %, in progress, pending)
• Stories grouped by priority
• Each story shows: status, narrative, criteria, files

Redirect to file:

/story export > stories.md

Integration with Ralph Loop

How Stories Flow Through Ralph Loop

1. /story new         → Create story in narrative format
2. /prd validate      → Verify format (warns on issues)
3. /loop start        → Ralph picks next story from prd.json
4. Ralph implements   → Writes code
5. Code review step   → Catches issues
6. Simplify code      → Cleans up
7. Run tests          → Validates correctness
8. If pass:
   - Commit to git
   - Set "passes": true in prd.json
   - Log learnings to progress.txt
   - Pick next story → back to step 3
9. If fail:
   - Set status to "blocked"
   - Log failure analysis
   - Human review required

Story Status in Ralph Loop

Stories start as pending → Ralph changes to in_progress → ends as done (✓ tests passed) or blocked (✗ failed)

You can manually update status with /story update if needed.

How Ralph Processes Stories with Subtasks

When a story has subtasks (created with structured path):

1. Ralph processes subtasks in order (TASK-001, TASK-002...)
2. Each subtask is a separate, finite work item
3. Ralph marks each subtask in_progress → done individually
4. When all subtasks done → parent story marked done
5. If any subtask fails → parent story marked blocked

Why this prevents spiraling:

• Each subtask is too small to spiral on (one clear purpose)
• Ralph finishes TASK-001 completely before TASK-002
• Clear success criteria at the subtask level
• Parent story only marks done when all children done

Example flow:

STORY-007: Search Context Card
  ├─ TASK-001: Create feature branch [DONE]
  ├─ TASK-002: Search is case-insensitive [DONE]
  ├─ TASK-003: Highlights matching [DONE]
  ├─ TASK-004: Returns count [IN_PROGRESS]
  └─ TASK-005: Filters nested objects [PENDING]

Ralph is working on TASK-004. When done, moves to TASK-005. Once all complete, STORY-007 marked done.

Validation

Stories are validated for:

✅ Required fields:

• Unique ID
• Title
• Description with proper narrative format
• At least 1 acceptance criterion
• Valid status (pending, in_progress, done, blocked)
• Priority 1-3

⚠️ Warnings (don't block):

• Less than 3 acceptance criteria (recommend 3-5)
• Missing narrative format ("As a X, I want Y, so that Z")
• No files listed (sometimes OK for cross-cutting concerns)

Validate stories:

/prd validate    # Validates all stories (including format checks)

Best Practices

1. Clear User Role

✅ "As a developer debugging a failed loop" ❌ "As a user"

2. Specific Action

✅ "I want to see the exact JSON state that triggered the failure" ❌ "I want to see something"

3. Real Business Value

✅ "So that I can understand what went wrong without digging through logs" ❌ "So that I have a feature"

4. Testable Criteria

✅ "Card displays TIER 0 project context" ✅ "JSON is syntax-highlighted" ❌ "Card is nice" ❌ "UI is better"

5. Right Scope

• One story = one feature or user interaction
• If it takes >4 hours to implement, consider breaking it
• List affected files upfront (helps Ralph plan work)

6. Priority Guidance

• P1 (High) - Blocks other work or critical path
• P2 (Normal) - Important but not urgent
• P3 (Low) - Nice to have, can defer

Comparison: /story vs /prd

Aspect	/story	/prd
Input	Interactive prompts	Manual JSON editing
Format	Guided narrative	Free-form
Validation	Enforced	Optional
ID Prefix	STORY-XXX (user stories)	TASK-XXX (technical tasks)
Use case	Feature work	Project setup/management
Best for	Ralph Loop automation	Overall PRD management

When to use /story:

• Creating new user stories for Ralph Loop
• Iterating on features with clear user benefits
• Ensuring narrative format is followed

When to use /prd:

• Viewing/managing entire PRD
• Adding technical tasks (non-story work)
• Validating entire project structure

Both tools read/write the same prd.json - they're complementary!

Troubleshooting

Story not appearing after creation

1. Check: /story show lists it
2. Validate: /prd validate shows no errors
3. File: Verify prd.json was updated: tail prd.json

Ralph Loop not picking up story

1. Verify status is pending or in_progress
2. Run validation: /prd validate
3. Check story ID starts with STORY- or TASK-
4. View Ralph log: check progress.txt for errors

Can't update story status

1. Verify story ID: /story show
2. Valid status: pending, in_progress, done, blocked
3. Try: /story update STORY-001 (interactive mode)

See Also

• /prd - Full PRD management and validation
• /loop - Start Ralph Loop for autonomous execution
• prd.json - Raw data file (view with /story show)
• progress.txt - Learnings and execution log
• prompt.md - Ralph's work order (generated per iteration)

Examples

Example 1: Quick Path - React Component Story

$ /story new

Story ID [STORY-006]:
Path [Q/S, default=Q]: Q
User role (As a): developer in a React project
Desired action (I want to): implement a collapsible JSON card component
Business value (So that): display context at a glance without opening other windows
Title [Implement Collapsible JSON Card]:
Priority [1=high, 2=normal, 3=low, default=2]: 1
Files (comma-separated, optional): src/components/ContextCard.tsx, src/hooks/useContext.ts, tests/ContextCard.test.tsx
Add acceptance criteria (blank line to finish, need at least 1):
  - Component accepts JSON data as prop
  - Sections collapse/expand on click
  - JSON is syntax-highlighted
  - Works with deeply nested objects
  - Component is <500ms to render
  - No external dependencies
  (blank to finish)

✓ Created story: [STORY-006] Implement Collapsible JSON Card

Example 2: Structured Path - Complex Feature with Subtasks

$ /story new

Story ID [STORY-007]:
Path [Q/S, default=Q]: S

=== Problem Statement ===
What problem does this solve? Users can't easily search through large heuristics in the context card

Create narrative: 'As a X, I want Y, so that Z'
User role (As a): developer in Ralph loop with large knowledge base
Desired action (I want to): search the context card by domain or keyword
Business value (So that): I can find relevant heuristics without manual scrolling

Title [Search Context Card By Domain Or Keyword]:
Priority [1=high, 2=normal, 3=low, default=2]: 1

=== Functional Requirements ===
List what the system must do (blank to finish):
  Requirement: Search is case-insensitive
  Requirement: Highlights matching keys and values
  Requirement: Returns count of matches
  Requirement: Filters work with nested objects
  Requirement: Search input is sticky while scrolling
  Requirement: (blank to finish)

=== Constraints & Non-Goals ===
What should this NOT do? Any limits? (blank to finish):
  Constraint: Don't add external search libraries (keep it lightweight)
  Constraint: Don't modify the JSON structure for search purposes
  Constraint: (blank to finish)

=== Success Metrics ===
How do we measure success? (blank to finish, at least 1):
  Metric: Search returns results in <100ms
  Metric: All criteria work with 1000+ item datasets
  Metric: Works offline without external dependencies
  Metric: (blank to finish)

Files (comma-separated, optional): src/components/ContextCard.tsx, src/components/SearchFilter.tsx

Add acceptance criteria (blank line to finish, need at least 1):
  - Search box accepts text input
  - Results highlight in card
  - Count displayed: "X matches found"
  - Escape key clears search
  - (blank to finish)

Generate subtasks to prevent Ralph spiraling? [Y/n]: Y

=== Generating Subtasks ===
  - [TASK-001] Create feature branch
  - [TASK-002] Search is case-insensitive
  - [TASK-003] Highlights matching keys and values
  - [TASK-004] Returns count of matches
  - [TASK-005] Filters work with nested objects
  - [TASK-006] Search input is sticky while scrolling
✓ Generated 5 subtasks (plus feature branch)

✓ Created story: [STORY-007] Search Context Card By Domain Or Keyword
  Linked subtasks: 6

Example 2: Filter High-Priority Pending Work

$ /story list --priority 1 --status pending

[STORY-001] User Authentication
[STORY-005] Dashboard KPI Display
[STORY-009] Error Handling Framework

→ Ralph will process these in order

Example 3: Review Before Starting Ralph Loop

$ /story show
$ /prd validate    # Ensure all stories are valid
$ /loop            # Start Ralph Loop

Contributing

To improve the /story skill:

1. Use it regularly and note friction points
2. Suggest UX improvements to the prompts
3. Add new filters for /story list
4. Extend validation rules (in /prd validate)
5. Share story templates for common patterns