aiskillstore/backend-ralph-plan

Backend RALPH Plan Skill

Purpose

This skill creates two deliverables:

1. PLAN.md - Structured task index with quality tracking
2. RALPH-PROMPT.md - The prompt fed to /ralph-wiggum:ralph-loop

The key insight: Ralph works by feeding the same prompt repeatedly. Claude sees its previous work in files/git and iterates. RALPH-PROMPT.md becomes that prompt, instructing Claude to work through tasks with strict quality gates.

When to Use

• Backend Django features requiring rigorous quality control
• Multi-task implementations needing iterative, autonomous execution
• When you want continuous regression testing between tasks
• Projects where you'll walk away and let Ralph complete the work

When NOT to Use

• Quick prototypes or exploratory code
• Frontend projects (create frontend-ralph-plan if needed)
• Simple tasks that don't need iteration
• Plans where human judgment is needed at each step

The Two-Step Process

Step 1: This skill creates the plan

docs/plans/<slug>/
├── PLAN.md              # Task index with tracking
├── RALPH-PROMPT.md      # Prompt for ralph-loop
├── 001-<task>.md        # Task files
└── ...

Step 2: Run the plan

/plan-directory:run <slug>

That's it. This command:

1. Reads RALPH-PROMPT.md
2. Extracts the completion promise
3. Invokes /ralph-wiggum:ralph-loop automatically

Optional: /plan-directory:run <slug> --max-iterations 50

Required Inputs

| Input | Required | Description | |-------|----------|-------------| | Plan title | Yes | Human-readable name | | Plan slug | Yes | Directory name, kebab-case | | Task list | Yes | Tasks with names and scopes | | Django app path | Yes | e.g., optimo_surveys/ | | Module path | Yes | e.g., digest/ | | Test filter | Yes | Pytest -k filter |

Tooling Configuration

| Input | Default | Description | |-------|---------|-------------| | Lint command | ruff check | Prefix with .bin/ if needed | | Format command | ruff format | | | Type check | ty | Or mypy, pyright | | Test command | pytest | | | Test config | `` | e.g., --dc=TestLocalApp | | Django command | django | | | Coverage target | 90 | Minimum percentage | | Max iterations | 100 | Ralph loop limit |

Task Granularity Guidelines

Right-sized tasks for Ralph:

| Task Size | Checklist Items | Good For | |-----------|-----------------|----------| | Too small | 1-2 | Overhead exceeds value | | Ideal | 4-8 | Clear scope, achievable in one iteration | | Too large | 10+ | Gets stuck, split it |

Signs a task is too large:

• Requires multiple commits to feel "done"
• Has more than 8 checklist items
• Spans multiple unrelated concerns
• Would take a human more than 2-4 hours

Split large tasks by:

• Separating model/service/API layers
• Breaking by feature subset
• Isolating integration points

Completion Promise Format

The promise must be plan-specific, not generic:

ALL {{TASK_COUNT}} {{PLAN_SLUG_UPPER}} TASKS COMPLETE

Examples:

• ALL 4 USER-PREFERENCES TASKS COMPLETE
• ALL 11 MANAGER-DIGEST TASKS COMPLETE
• ALL 6 NOTIFICATION-SERVICE TASKS COMPLETE

This prevents Claude from lying with a generic "done" when tasks remain.

RALPH-PROMPT.md: The Key File

The prompt is iteration-aware. It tells Claude to:

1. Orient first - Check git log, read PLAN.md for current status
2. Don't repeat work - Skip what's already committed
3. Verify rigorously - Run all gates after each task
4. Commit progress - Git commit after each task completion
5. Handle blockers - Document, try alternatives, don't lie to exit

See references/ralph-prompt-template.md for the full template. See examples/user-preferences/ for a complete working example.

Git Integration

Each task completion includes a commit:

git commit -m "Complete 001 - Preferences Model

- Added JSONField to User model
- Created Pydantic schemas for validation
- 5 tests added, 94% coverage

Plan: user-preferences"

This is critical for Ralph because:

• Progress persists across iterations
• Claude can see what it did via git log
• Partial progress is never lost

Handling Complex Codebases

For large/unfamiliar codebases, add a warm-up task:

# 000 - Codebase Orientation

## Goal
Understand existing patterns before implementing.

## Checklist
- [ ] Read existing models in `{{APP_PATH}}`
- [ ] Identify service layer patterns
- [ ] Note testing conventions
- [ ] Document relevant existing code in Notes section

## Completion Criteria
- [ ] Notes section filled with findings
- [ ] No implementation (orientation only)

This prevents Claude from fighting existing patterns.

Escape Hatches

If Claude is genuinely stuck:

1. Blockers section in task file:

   ## Blockers
   - **Blocked by:** External API not available
   - **Attempted:** Mock implementation, local stub
   - **Needs:** API credentials or decision to defer
   

2. Skip to independent task if dependencies allow

3. Max iterations as ultimate safety net

The loop continues until genuine completion or max iterations. Claude should never lie to exit.

Workflow

1. Gather Inputs

Ask for all required inputs. Clarify:

• Exact paths (trailing slashes matter)
• Test filter that isolates this feature
• Non-standard tooling (.bin/ wrappers)

2. Analyze Dependencies

Before creating files:

1. Identify foundation tasks (no dependencies)
2. Map task dependencies
3. Determine critical path
4. Order to minimize blocking

3. Create Files

1. Create docs/plans/<slug>/ directory
2. Write PLAN.md with task index and tracking tables
3. Write each task file with standard sections
4. Write RALPH-PROMPT.md with all placeholders replaced

4. Replace Placeholders

In RALPH-PROMPT.md, replace:

• {{PLAN_TITLE}} → e.g., "User Preferences API"
• {{TASK_COUNT}} → e.g., "4"
• {{PLAN_SLUG}} → e.g., "user-preferences"
• {{PLAN_SLUG_UPPER}} → e.g., "USER-PREFERENCES"
• {{LINT_CMD}} → e.g., ".bin/ruff check"
• {{APP_PATH}} → e.g., "accounts/"
• {{MODULE_PATH}} → e.g., "preferences/"
• All other command/path placeholders

5. Verify Deliverables

Before delivering:

• [ ] PLAN.md has task index and tracking tables
• [ ] All task files have Goal, Scope, Checklist, Tests, Completion Criteria
• [ ] Task checklist items are 4-8 each (not too small, not too large)
• [ ] RALPH-PROMPT.md has NO remaining {{placeholders}}
• [ ] Execution order matches actual dependencies
• [ ] Completion promise includes task count and slug

Example

See examples/user-preferences/ for a complete working example:

• PLAN.md - 4-task plan with tracking
• RALPH-PROMPT.md - Iteration-aware prompt
• 001-preferences-model.md - Foundation task (model layer)
• 002-preferences-service.md - Service layer
• 003-api-endpoints.md - API layer
• 004-caching-layer.md - Performance optimization

Reference Files

• references/ralph-prompt-template.md - Full prompt template
• references/plan-template.md - PLAN.md structure
• references/quality-gates.md - Verification commands
• examples/user-preferences/ - Working example