ralph

Ralph Issue Creator Skill

Convert Product Requirements Documents (PRDs) into GitHub Issues for Ralph to execute autonomously.

Your Job

1. Read the PRD from tasks/prd-[feature-name].md
2. Convert each user story into a GitHub Issue
3. Create issues using gh CLI with proper labels and ordering

Do NOT implement. Just create the issues.

Story Sizing - Critical Rule

Each story must be completable in ONE Ralph iteration (one context window).

Ralph operates with fresh context per iteration. Oversized stories result in incomplete work.

Right-sized stories:

• Add a database column with migration
• Create a single UI component
• Add one API endpoint
• Update server logic for one feature

Too large - split these:

• "Build the entire dashboard" → Split into individual components
• "Add authentication" → Split into: schema, login endpoint, logout endpoint, middleware, UI
• "Refactor the API" → Split into specific endpoints or layers

Priority Labels

Ralph processes issues by priority: P0 → P1 → P2 → no label (oldest first within each priority).

Use priority labels for urgency:

• P0: Critical/blocking - must be done first
• P1: High priority - important but not blocking
• P2: Normal priority - standard work
• No label: Low priority - backlog items

Dependency Ordering

Within the same priority, create issues in dependency order (Ralph processes oldest first):

1. Schema/database changes - Must exist before backend uses them
2. Backend/server logic - Must exist before UI calls them
3. UI components - Depend on backend being ready
4. Integration/summary views - Depend on all pieces existing

Rule: Earlier issues must NOT depend on later ones.

Acceptance Criteria Standards

Criteria must be verifiable, not vague.

Good criteria:

• "Add status column to tasks table with default 'pending'"
• "Endpoint returns 200 with JSON body containing 'id' and 'name'"
• "Button is disabled when input is empty"
• "Tests pass"

Bad criteria - avoid these:

• "Works correctly"
• "Good UX"
• "Handles edge cases"
• "Is fast"

Always include:

• "Tests pass" (for any testable code)
• "Typecheck passes" (for TypeScript projects)

Issue Format

Create each issue with this structure:

gh issue create \
  --title "US-001: [Story Title]" \
  --label "task" \
  --label "P1" \
  --body "$(cat <<'EOF'
## Description
As a [user type], I want [feature] so that [benefit].

## Acceptance Criteria
- [ ] Specific criterion 1
- [ ] Specific criterion 2
- [ ] Tests pass

## Context
[Any relevant context from the PRD]

## Dependencies
- Depends on: #[issue-number] (if applicable)
- Blocks: #[issue-number] (if applicable)
EOF
)"

Conversion Process

1. Read the PRD: Load tasks/prd-[feature-name].md

2. Identify stories: Extract all user stories (US-001, US-002, etc.)

3. Verify sizing: Each story must be one-iteration sized

   • If too large, stop and ask user to split in the PRD

4. Order by dependency: Determine creation order

5. Create issues: Use gh issue create for each story

   • Add task label (required for Ralph to find them)
   • Add priority label (P0, P1, or P2) based on urgency
   • Include acceptance criteria as checklist
   • Reference dependencies between issues

6. Report: List all created issues with numbers

Example Conversion

PRD User Story:

### US-001: Add task status field

**Description**: As a user, I want tasks to have a status so I can track progress.

**Acceptance Criteria**:

- [ ] Add 'status' column to tasks table
- [ ] Default value is 'pending'
- [ ] Valid values: pending, in_progress, completed
- [ ] Migration runs without errors

Created Issue:

gh issue create \
  --title "US-001: Add task status field" \
  --label "task" \
  --label "P1" \
  --body "## Description
As a user, I want tasks to have a status so I can track progress.

## Acceptance Criteria
- [ ] Add 'status' column to tasks table
- [ ] Default value is 'pending'
- [ ] Valid values: pending, in_progress, completed
- [ ] Migration runs without errors

## Context
This is a schema change that must be completed before any backend or UI work that uses the status field."

Pre-Creation Checklist

Before creating issues, verify:

• PRD exists at tasks/prd-[feature-name].md
• Each story is completable in one iteration
• Stories are ordered by dependency
• Priority labels assigned (P0, P1, P2) based on urgency
• Acceptance criteria are verifiable (not vague)
• "Tests pass" included where applicable
• No forward dependencies (earlier issues don't depend on later ones)

After Creation

Report the created issues:

Created issues for PRD: [feature-name]

1. #123 - US-001: Add task status field
2. #124 - US-002: Create status update endpoint
3. #125 - US-003: Add status dropdown to task form

Run Ralph to process: ./ralph/ralph.sh

If this command has been invoked after creating a plan, then write the plan route in the issue so that we don't loos that valuable context.