ralph-method

应用拉尔夫·威格姆方法模式,将任务分解为原子用户故事

📖 中文导读:应用拉尔夫·威格姆方法模式,将任务分解为原子用户故事 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: ralph-method description: Apply Ralph Wiggum Method patterns for decomposing tasks into atomic user stories user-invocable: false when_to_use: | Use this skill when: - Breaking down a feature or task into implementable user stories - Planning work for autonomous AI-assisted coding loops - Creating prd.json or story breakdown artifacts - Evaluating if a story is atomic enough for single-iteration completion - Generating Ralph Wiggum Method artifacts

Ralph Wiggum Method

The Ralph Wiggum Method is an autonomous AI coding loop that ships features while you sleep. It breaks complex tasks into atomic user stories that can each be completed in a single AI iteration.

Core Principles

  1. One iteration = One story = One commit
  2. Each story must be completable in a single AI iteration (5-30 minutes of work)
  3. Stories are ordered by dependency (infrastructure first, consumers last)
  4. Every story ends with build/test verification
  5. The loop runs autonomously until all stories pass

Story Atomicity Rules

A story is atomic when:

  • It can be committed independently without breaking the build
  • It leaves the codebase in a working state
  • It has clear, verifiable "done" criteria
  • It doesn't require human intervention mid-way
  • It can be code-reviewed as a single logical change

Story Decomposition Patterns

API Endpoint

Priority Story Purpose
1 Create schema/types Define data structures
2 Create service layer Business logic
3 Create route handler HTTP interface
4 Add integration test Verification

Database Change

Priority Story Purpose
1 Create migration file Schema change
2 Update model/entity Code representation
3 Update seed data Test data
4 Update consuming code Integration

React Component

Priority Story Purpose
1 Create component skeleton Structure
2 Add state/logic Behavior
3 Add styling Appearance
4 Add tests Quality

Refactoring

Priority Story Purpose
1 Add new implementation alongside old Parallel path
2 Migrate consumers one by one Gradual switch
3 Remove old implementation Cleanup

Configuration Change

Priority Story Purpose
1 Add environment variables Define config
2 Create/update config file Structure config
3 Update consuming code Use config

prd.json Schema

{
  "branchName": "ralph/feature-name",
  "taskDescription": "One-line summary of the task",
  "projectContext": {
    "framework": "e.g., Next.js, .NET",
    "testCommand": "e.g., npm test, dotnet test",
    "buildCommand": "e.g., npm run build, dotnet build"
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "Short descriptive title",
      "description": "What to implement in detail",
      "acceptanceCriteria": [
        "Specific, verifiable criterion 1",
        "Specific, verifiable criterion 2",
        "Build/test passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": "Hints, gotchas, references to existing code"
    }
  ]
}

Field Descriptions

  • branchName: Git branch for all work (format: ralph/<feature-name>)
  • taskDescription: One-line summary for quick context
  • projectContext: Build/test commands and framework info
  • userStories: Array of atomic stories in dependency order
    • id: Unique identifier (US-001, US-002, etc.)
    • title: Short title for commit messages
    • description: Full implementation details
    • acceptanceCriteria: Verifiable conditions for "done"
    • priority: Execution order (1 = first)
    • passes: Set to true when story is complete
    • notes: Additional context, gotchas, file references

Anti-Patterns to Avoid

Vague Stories

  • BAD: "Update all files"
  • GOOD: "Update UserController to use new AuthService"

Unbounded Scope

  • BAD: "Fix bugs as found"
  • GOOD: "Fix null reference in UserService.GetById"

Circular Dependencies

  • BAD: Story 3 depends on Story 5 which depends on Story 3
  • GOOD: Linear dependency chain

Too Large

  • BAD: "Implement entire authentication system"
  • GOOD: Split into: schema, service, middleware, routes, tests

Missing Verification

  • BAD: Story with no acceptance criteria
  • GOOD: Every story ends with "Build succeeds" or "Tests pass"

Story Sizing Guidelines

Size Time Examples
XS 5-10 min Add config value, create empty file, update import
S 10-20 min Create simple function, add basic test, update route
M 20-30 min Create service class, add migration, implement handler
L 30+ min TOO BIG - split into smaller stories

Verification Commands

Every story should end with verification. Common patterns:

# JavaScript/TypeScript
npm run build && npm test

# .NET
dotnet build && dotnet test

# Python
pytest && python -m py_compile src/*.py

# Go
go build ./... && go test ./...

Progress Tracking

The progress.txt file tracks completed stories:

# Progress: feature-name
# Total stories: 5

Current story: 3
Completed: 2

---
# Story log
[2025-01-10 10:00] US-001: Create user entity - PASSED
[2025-01-10 10:15] US-002: Add user repository - PASSED

Commit Message Format

story US-XXX: <title>

<description of what was done>

Example:

story US-001: Create user entity

Added UserEntity with id, email, and created_at fields.
Configured EF Core mapping in ApplicationDbContext.