PR Workbench Skill — Design Spec

Date: 2026-03-28 Status: Approved

---

Purpose

A linear checklist skill for picking up an open PR, syncing it with the dev branch, reviewing changed files, making additional changes, validating, and pushing. The skill stops at push — merging to dev is handled manually through GitHub's PR interface.

Trigger Patterns

Invoke when the user:

• Asks to "work on a PR", "pick up PR #X", "review and push PR"
• Provides a GitHub PR URL to work on
• References finishing, finalizing, or preparing a PR for merge

Skill Type

Linear checklist — sequential steps where each depends on the previous. No branching logic or subagent orchestration. The "work phase" loop is handled naturally by conversation flow.

Steps

Step 1: Fetch PR Details

• Use GitHub MCP (pull_request_read) or gh pr view to retrieve:
  • PR title, description, status (draft/ready), mergeable state
  • Changed files list
  • Base and head branch refs
  • Check run status
• Present a brief summary to the user before proceeding

Step 2: Checkout & Merge Dev

• Checkout the PR's head branch (if not already on it)
• git fetch origin dev
• git merge origin/dev --no-edit
• If merge conflicts: stop and report the conflicting files. Wait for user guidance — do not auto-resolve.
• If clean merge: report how many commits were merged in

Step 3: Code Review

• Get the list of files changed in the PR (get_files or git diff)
• Review the changed files plus any code they import or affect (blast radius)
• Focus on:
  • Correctness and logic errors
  • Security concerns
  • Adherence to project conventions (CLAUDE.md rules)
  • Potential issues introduced by the dev merge
• Present findings as a summary with actionable items
• If no issues found, say so and move on

Step 4: Work Phase (Loop)

• User directs additional changes, fixes, or new features
• This step repeats as many times as needed
• The skill serves as a reminder that validation and push haven't happened yet
• When the user indicates they're done with changes, proceed to Step 5

Step 5: Validate

• Run npm run validate
• All checks must pass (currently 12)
• If failures: report which checks failed, fix the issues, and re-run
• If passes: confirm and proceed to push

Step 6: Push

• git push origin <branch-name>
• If PR is in draft status, mark as ready: gh pr ready <number>
• Confirm the push succeeded and report the PR URL
• Remind the user they can merge via GitHub's PR interface when ready

File Structure

.gemini/skills/pr-workbench/
  skill.md          — Main skill definition with frontmatter and checklist
.github/skills/pr-workbench/
  skill.md          — Mirror copy

Naming

• Skill name: pr-workbench
• File: skill.md with YAML frontmatter (name, description)

Conventions

• Follows existing skill format: Markdown with YAML frontmatter
• Mirrored to both .gemini/skills/ and .github/skills/ directories
• Uses kebab-case naming consistent with other skills
• No scripts or references subdirectories needed — this is a simple checklist skill

Out of Scope

• Merging to dev (user handles via GitHub UI)
• Creating new PRs (covered by existing commit-push-pr skill)
• PR review for other people's PRs (covered by review-pr skill)