Ralph Planning Skill

MANDATORY: Skill Loaded Confirmation

You MUST output this as your FIRST action after reading state:

[RALPH-SKILL] Loaded: .github/skills/planning/SKILL.md for phase {N} ({phase_name})

If you don't output this, the loop may not recognize skill loading occurred.

Loaded: planning skill (phases 1-3). Objective: Complete ONE phase, update state, create signal file, yield signal, exit.

You're in a planning phase. This skill guides you through discovery, specification, and planning.

Phase Detection

Check state.json phase to determine your specific task:

Phase 1: Context Discovery

Goal

Understand the codebase well enough to write a meaningful spec and plan.

Discovery Checklist

1. •

   Project Structure

   • •Scan directory tree
   • •Identify main entry points
   • •Note package manager (npm, pip, cargo, etc.)
2. •

   Technology Stack

   • •Framework(s) in use
   • •Language version
   • •Key dependencies
3. •

   Existing Patterns

   • •Code organization conventions
   • •Naming patterns
   • •Test structure
4. •

   Context Packs

   • •Check for .context-packs/ directory
   • •Load relevant context if available
5. •

   Related Code

   • •Find code related to the user's request
   • •Identify files that will need changes
   • •Note dependencies between components

Discovery Output

Document findings in your event log:

# Event: {N} - Discovery - Codebase Analysis

**Timestamp**: {ISO-8601}
**Phase**: discovery (1)
**Session**: {session_id}

## Project Overview
- Type: {web app, CLI, library, etc.}
- Language: {language} {version}
- Framework: {framework} {version}

## Relevant Components
- {path/to/component1} - {what it does}
- {path/to/component2} - {what it does}

## Patterns Observed
- {Pattern 1}
- {Pattern 2}

## Integration Points
- {Where new code will connect}

## Risks/Considerations
- {Potential issues to address}

## State Changes
- Previous: phase=intake, status=in_progress
- Current: phase=spec, status=in_progress

## Next Action
Write specification based on discovery findings

Discovery Notes Artifact

MANDATORY: Create .ralph-stm/runs/{session}/discovery-notes.md during Phase 1.

This captures what context packs and specs may miss - actual code patterns observed.

Template:

# Discovery Notes for {session_id}

## Context Pack Gaps
<!-- Things discovered that aren't documented -->
- [Gap 1]: Found in [file path], not documented

## Patterns Discovered
<!-- Implementation patterns from exploration -->
- [Pattern name]: [Description], see [file path]

## Test Locations
<!-- Test files relevant to this feature -->
- [Component]: [test file path]

## Architecture Decisions Not Captured
<!-- Decisions evident from code but not documented -->
- [Decision]: [Evidence from code]

## Convention Snapshot

| Convention | Observed Pattern | Source Files | Notes |
|------------|------------------|--------------|-------|
| Variable naming | | | |
| Method naming | | | |
| Comments style | Yes/No/Partial | | |
| Error handling | | | |
| Logging style | | | |

## Test Infrastructure

| Aspect | Observed | Location |
|--------|----------|----------|
| Framework | | |
| Mocking library | | |
| Base test class | | |
| Test utilities | | |
| Naming convention | | |

Why: Discovery notes bridge the gap between codebase exploration and implementation. They capture insights that would otherwise be lost between invocations.

Deep Exploration Protocol

During Phase 1, explore the codebase systematically:

A. Pattern Discovery (Required)

• •Find 2-3 similar implementations to what you'll create
• •Read actual source files, not just directory structure
• •Note patterns the codebase uses (error handling, logging, validation)

B. Test Discovery (Required)

• •Locate ALL test files for components you'll modify
• •Understand test patterns (unit, integration, component)
• •Find test utilities and helpers
• •Note test data setup patterns

C. Interface Discovery (If modifying existing code)

• •Find all callers/consumers of code you'll modify
• •Check for interface contracts (APIs, events, shared types)
• •Identify potential breaking change risks

D. Convention Discovery (Required - fill Convention Snapshot)

• •Open 3-5 similar files to what you'll create
• •Document observed conventions in discovery notes
• •Note any INCONSISTENCIES within the codebase
• •Record the MAJORITY pattern for each convention

Transition

After discovery, update state to Phase 2 (spec), create signal file, and exit with yield signal.

Phase 2: Specification Writing

Goal

Create a clear, testable specification that captures what needs to be built.

Spec Structure

Write to .ralph-stm/runs/{session}/spec.md:

# Specification: {Feature Name}

## Overview
{Brief description of what this feature does}

## User Request
{Original user request verbatim}

## Requirements

### Functional Requirements
1. {Requirement 1}
2. {Requirement 2}
...

### Non-Functional Requirements
- Performance: {constraints}
- Security: {considerations}
- Compatibility: {requirements}

## Acceptance Criteria

### AC1: {Criterion Name}
**Given** {precondition}
**When** {action}
**Then** {expected result}

### AC2: {Criterion Name}
**Given** {precondition}
**When** {action}
**Then** {expected result}

{Continue for all criteria}

## Constraints
- {Constraint 1}
- {Constraint 2}

## Out of Scope
- {What this does NOT include}

## Dependencies
- {External dependency 1}
- {Existing code dependency}

## Open Questions
- {Any remaining ambiguities - should be minimal}

Specification Principles

1. •

   Testable Criteria

   • •Every acceptance criterion must be verifiable
   • •Use Given/When/Then format for clarity
2. •

   Scope Boundaries

   • •Explicitly state what's out of scope
   • •Prevents scope creep during execution
3. •

   Minimal Assumptions

   • •Document assumptions clearly
   • •Make reasonable defaults for minor decisions
4. •

   Connection to Codebase

   • •Reference actual files/components discovered
   • •Ground requirements in reality

Handling Ambiguity

Transition

After spec complete, update state to Phase 3 (planning), create signal file, and exit with yield signal.

Phase 3: Implementation Planning

Goal

Create a phase-based plan that guides execution. NOT micro-tasks—logical phases.

Plan Structure

Write to .ralph-stm/runs/{session}/plan.md:

# Implementation Plan: {Feature Name}

## Overview
{How this feature will be implemented}

## Prerequisites
- {Any setup needed before starting}

## Implementation Phases

### Phase 1: {Phase Name}
**Objective**: {What this phase achieves}
**Scope**:
- {Component/file 1}
- {Component/file 2}
**Approach**: {How to implement}
**Verification**: {How to know it's done}

### Phase 2: {Phase Name}
**Objective**: {What this phase achieves}
**Scope**:
- {Component/file 1}
- {Component/file 2}
**Approach**: {How to implement}
**Verification**: {How to know it's done}

{Continue for all phases}

## Testing Strategy
- {Unit tests}
- {Integration tests}
- {Manual verification}

## Risk Analysis

| Risk | Likelihood | Impact | Detection | Mitigation |
|------|------------|--------|-----------|------------|
| {What could go wrong} | Low/Med/High | Low/Med/High | {How to detect} | {How to prevent/recover} |

Common risks to consider:
- Breaking existing functionality
- Missing edge cases
- Performance degradation
- Security implications
- Test coverage gaps

## Rollback Plan
{How to undo if needed}

## Total Phases: {N}

Planning Principles

1. •

   Phase-Based, Not Task-Based

   • •Each phase = logical unit of work
   • •One phase per execution invocation
   • •NOT "create file X, modify line Y"
2. •

   Dependency Order

   • •Plan phases in dependency order
   • •Earlier phases don't depend on later ones
3. •

   Verification Built-In

   • •Each phase has clear completion criteria
   • •Tests run as part of phases when appropriate
4. •

   Appropriate Granularity

   • •Small feature: 2-4 phases
   • •Medium feature: 4-8 phases
   • •Large feature: 8-15 phases
   • •Too many phases = too granular

Example Phase Breakdown

For "Add JWT authentication to API":

Transition

After plan complete:

1. •Update state.json with total_plan_phases count
2. •Create signal file
3. •Transition to Phase 4 (approval)
4. •Exit with yield signal

State Update Reminder

CRITICAL: Before exiting, you MUST update state.json with:

Always Update

• •updated_at: Current ISO-8601 timestamp
• •last_task: Brief description of what you did
• •last_event_id: Increment if you wrote an event

Update on Phase Change

• •phase: New phase name
• •phase_id: New phase number
• •status: Current status
• •checkpoint.resume_hint: What to do next

After Discovery (Phase 1 → 2)

{
  "phase": "spec",
  "phase_id": 2,
  "updated_at": "{timestamp}",
  "last_task": "discovery-complete",
  "last_event_id": 1,
  "checkpoint": {
    "can_resume": true,
    "resume_hint": "Write specification based on discovery findings"
  }
}

After Spec (Phase 2 → 3)

{
  "phase": "planning",
  "phase_id": 3,
  "updated_at": "{timestamp}",
  "last_task": "spec-complete",
  "last_event_id": 2,
  "checkpoint": {
    "can_resume": true,
    "resume_hint": "Create implementation plan based on spec"
  }
}

After Planning (Phase 3 → 4)

{
  "phase": "approval",
  "phase_id": 4,
  "status": "waiting_for_user",
  "updated_at": "{timestamp}",
  "last_task": "plan-complete",
  "last_event_id": 3,
  "total_plan_phases": {N},
  "checkpoint": {
    "can_resume": true,
    "resume_hint": "Waiting for user approval of spec and plan"
  }
}

Phase Completion Reminder

Before exiting, you MUST:

1. •Update state.json with all required fields
2. •Create signal file: signals/phase-{N}-complete.signal
3. •Write event log
4. •Output yield signal
5. •Exit immediately - do NOT start next phase

Signal File Format

Path: .ralph-stm/runs/{session}/signals/phase-{N}-complete.signal

{
  "phase_id": {N},
  "phase_name": "{name}",
  "completed_at": "{ISO-8601}",
  "next_phase": {N+1},
  "skill_loaded": ".github/skills/planning/SKILL.md",
  "artifacts_created": ["discovery-notes.md", "events/001-discovery-complete.md"]
}

Yield Signal

Output before every exit:

[RALPH-YIELD]
phase_completed: {N}
next_phase: {N+1}
status: {in_progress|waiting_for_user}
signal_file: .ralph-stm/runs/{session}/signals/phase-{N}-complete.signal
work_done: {brief description}
[/RALPH-YIELD]

Quality Checklist

Before transitioning out of planning phases:

Discovery Complete?

• • Project structure understood
• • Tech stack identified
• • Relevant code located
• • Patterns documented
• • Discovery notes created (.ralph-stm/runs/{session}/discovery-notes.md)
• • Convention snapshot filled
• • Risks noted
• • Event log written
• • Signal file created
• • State updated
• • Yield signal output

Spec Complete?

• • All requirements listed
• • Acceptance criteria testable
• • Scope clearly bounded
• • Dependencies identified
• • Written to spec.md
• • Event log written
• • Signal file created
• • State updated
• • Yield signal output

Plan Complete?

• • Phases in dependency order
• • Each phase has clear objective
• • Each phase verifiable
• • Testing strategy included
• • Written to plan.md
• • total_plan_phases updated
• • Event log written
• • Signal file created
• • State updated
• • Yield signal output

Remember

• •You're gathering information and creating documents
• •Don't implement yet—that's Phase 5
• •Be thorough but not exhaustive
• •Document decisions in event logs
• •Output [RALPH-SKILL] confirmation as first action
• •Create signal file before exit
• •One complete phase per invocation, then exit
• •Always update state.json before exit
• •Always output yield signal before exit