/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

bash

/story new

You'll be prompted for:

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

View Stories

bash

/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

bash

/story update STORY-001

Interactively change: status, priority, acceptance criteria

Export

bash

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

code

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:

code

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

code

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

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

Structured Path Prompts

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

Output (Quick Path):

code

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

Output (Structured Path):

code

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

`/story show`

List all stories with visual status and brief info.

Output:

code

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:

code

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

code

✓ Updated story STORY-001

`/story list [OPTIONS]`

Filter and display stories matching criteria.

Options:

bash

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

bash

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

bash

/story export > stories.md

Integration with Ralph Loop

How Stories Flow Through Ralph Loop

code

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

•Ralph processes subtasks in order (TASK-001, TASK-002...)
•Each subtask is a separate, finite work item
•Ralph marks each subtask in_progress → done individually
•When all subtasks done → parent story marked done
•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:

code

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:

bash

/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

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

Ralph Loop not picking up story

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

Can't update story status

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

Examples

Example 1: Quick Path - React Component Story

bash

$ /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

bash

$ /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

bash

$ /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

bash

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

Contributing

To improve the /story skill:

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

/story - Interactive User Story Management

What It Does

Quick Start

Create a Story

View Stories

Update Story

Export

Two Paths: Quick vs Structured

Quick Path (Default)

Structured Path (Prevents Ralph Spiraling)

Story Format

Story Lifecycle

Commands Reference

/story new

Quick Path Prompts

Structured Path Prompts

/story show

/story view STORY-001

/story update STORY-001

/story list [OPTIONS]

/story export

Integration with Ralph Loop

How Stories Flow Through Ralph Loop

Story Status in Ralph Loop

How Ralph Processes Stories with Subtasks

Validation

Best Practices

1. Clear User Role

2. Specific Action

3. Real Business Value

4. Testable Criteria

5. Right Scope

6. Priority Guidance

Comparison: /story vs /prd

Troubleshooting

Story not appearing after creation

Ralph Loop not picking up story

Can't update story status

See Also

Examples

Example 1: Quick Path - React Component Story

Example 2: Structured Path - Complex Feature with Subtasks

Example 2: Filter High-Priority Pending Work

Example 3: Review Before Starting Ralph Loop

Contributing

`/story new`

`/story show`

`/story view STORY-001`

`/story update STORY-001`

`/story list [OPTIONS]`

`/story export`

Comparison: `/story` vs `/prd`