ralph claude skill

ralph.md

name	description	argument-hint	allowed-tools
ralph	Implement a GitHub issue or PR end-to-end - fetch, plan, code, test, and open a PR	<issue-number-or-url>	Bash(gh issue view *) Bash(gh pr view *) Bash(gh pr create --repo *) Bash(git checkout *) Bash(git branch *) Bash(git add *) Bash(git commit *) Bash(git push *) Bash(git status) Bash(git diff *) Bash(git log *) Bash(make test) Bash(make dist)

Ralph - GitHub Issue & PR Implementer

Implement a GitHub issue or PR end-to-end: fetch, plan, code, test, and open a PR.

Usage

/ralph <issue-or-pr>

The parameter can be:

• An issue number (e.g., 27) - fetches from the current repository
• A full GitHub issue URL (e.g., https://github.com/runs-on/action/issues/21)
• A full GitHub PR URL (e.g., https://github.com/runs-on/cache/pull/42)

PR as source: When given a PR URL, Ralph uses the PR's description and comments as the specification, allowing you to re-implement the feature/fix in your own way. This is useful when someone submits a PR but you want to take a different approach.

Important: The branch and PR are always created in the current repository, even if the issue/PR is fetched from a different repo. This supports workflows where issues are tracked in a separate repository from where the code lives.

Allowed Tools

This skill has pre-approval (via frontmatter allowed-tools) to run the following commands without asking for user confirmation:

• gh issue view *
• gh pr view *
• gh pr create --repo * (must use --repo flag to avoid targeting upstream forks)
• git checkout *, git branch *, git add *, git commit *, git push *
• git status, git diff *, git log *
• make test, make dist

Workflow

When invoked, follow these steps in order:

Step 1: Parse Input and Fetch the Issue or PR

First, determine the type and source from the input:

For Issue URLs (contains /issues/):

• Extract repo = owner/repo and issue_number from the URL
• Fetch with: gh issue view <number> --repo <repo> --json title,body,comments,labels

For PR URLs (contains /pull/):

• Extract repo = owner/repo and pr_number from the URL
• Fetch with: gh pr view <number> --repo <repo> --json title,body,comments,labels

For plain numbers (e.g., 27):

• Use the current repository
• Fetch with: gh issue view <number> --json title,body,comments,labels

Display a summary to the user:

• Title
• Description (body)
• Labels
• Key points from comments (if any)
• For PRs: Note that this is being used as a specification source, not the actual PR to merge

Step 2: Create a Branch

Based on the issue content, create an appropriately named branch:

• Use fix/short-description for bug fixes (issues with labels like "bug", "fix", "bugfix", or descriptions indicating a bug)
• Use feature/short-description for new features or enhancements
• Use chore/short-description for maintenance tasks
• Use docs/short-description for documentation changes

The branch name should:

• Be lowercase
• Use hyphens to separate words
• Be concise but descriptive (3-5 words max)
• Reference the issue number if helpful (e.g., fix/27-login-error)

Create and checkout the branch:

git checkout -b <branch-name>

Step 3: Plan the Implementation

Analyze the codebase and create a detailed implementation plan:

1. Identify the files that need to be modified or created
2. Understand the existing code patterns and conventions
3. List the specific changes needed
4. Consider edge cases and potential issues

Present the plan to the user and ask for confirmation before proceeding.

Step 4: Implement the Changes

After user confirmation, implement the planned changes:

• Follow existing code style and conventions
• Write clean, maintainable code
• Add necessary comments only where the logic isn't self-evident
• Handle error cases appropriately

Step 5: Run Tests

Look for test commands in the repository:

1. Check package.json for test script
2. Check for Makefile with test target
3. Check for common test runners (pytest, go test, cargo test, etc.)
4. Check for CI configuration files that indicate test commands

If a test command is found, run it and report results. If tests fail, attempt to fix the issues.

Step 6: Build Distribution (if applicable)

Check if the repository has a make dist target:

grep -E "^dist:" Makefile

If the dist target exists, run it to rebuild any distributed binaries or generated files:

make dist

This is an org-wide convention for projects that include compiled binaries, generated JavaScript files, or other build artifacts that need to be committed alongside source changes. The make dist command typically:

• Rebuilds binaries for all target platforms
• Regenerates any templated files
• Stages and commits the rebuilt artifacts

If make dist fails, investigate and fix the issue before proceeding.

Step 7: Commit and Push

After successful implementation (and passing tests if applicable):

1. Stage the source code changes:

   git add <specific-files>

2. Create a commit with a descriptive message referencing the source:

   git commit -m "Fix/Feature: Description
   
   Fixes org/repo#<issue_number>"

   • Use the full org/repo#number format if the issue is from a different repository
   • Use just #number if the issue is in the same repo
   • For PRs as source: Reference the original PR for context (e.g., "Reimplements org/repo#42")

3. If make dist was run in Step 6, it will have created an additional commit with the rebuilt binaries. This is expected.

4. Ask the user if they want to push and create a PR.

5. If confirmed, push and create the PR in the current repository (not the issue source repo). Always use --repo to explicitly target the correct repository:

   git push -u origin <branch-name>
   gh pr create --repo <owner/repo> --title "<title>" --body "<body>"

   The PR body should:

   • Reference the issue with the full repo path if from a different repo (e.g., "Fixes org/issues-repo#27")
   • Or use "Closes #<issue_number>" if the issue is in the same repo
   • For PRs as source: Reference the original PR (e.g., "Alternative implementation of #42" or "Reimplements runs-on/cache#42")
   • Summarize the changes made
   • Include a test plan if applicable

Important Notes

• Branches and PRs are always created in the current working repository, even when the issue/PR source comes from a different repo (via URL).
• When creating PRs with gh pr create, always use the --repo flag to explicitly specify the target repository (e.g., gh pr create --repo runs-on/cache). This prevents accidentally creating PRs against an upstream fork when the repo has multiple remotes configured.
• When using a PR as source, you're reimplementing the feature/fix described in that PR—not merging it.
• Always ask for user confirmation before implementing changes
• If the issue/PR is unclear or ambiguous, ask clarifying questions
• If the implementation seems complex, break it into smaller steps and confirm each
• Never force push or make destructive git operations without explicit permission
• When referencing cross-repo issues/PRs, always use the full owner/repo#number format in commits and PR descriptions