Pr Workflow

---
description: Guide Claude agents through the complete pull request lifecycle, from pre-PR validation through to successful merge
---

# PR Workflow Command

Guide Claude agents through creating and managing a pull request from start to finish, with autonomous monitoring and iterative fixes until the PR is ready to merge.

## Critical Constraints - Session Statelessness

**IMPORTANT:** You are operating in a stateless session. Each Claude Code session is isolated. Every GitHub issue gets a fresh Claude Code context.

**You CANNOT:**
- Track issues across sessions
- Remember to do something later
- Follow up on tasks in the future
- Promise to handle something "in a follow-up"

**You MUST NOT say things like:**
- "I'll track this in a follow-up issue"
- "I'll remember to fix this later"
- "I'll handle this in a subsequent PR"

## PR Comment Response Decision Framework

When addressing review comments, choose ONE of these options:

### Option 1: Implement Now (Preferred)
**When:** The change is small-ish and worth doing.
**Action:**
1. Implement the fix immediately
2. Commit with reference: `🩹 fix: address review feedback - {description}`
3. Reply: "Fixed in commit {sha}: {brief description}"

### Option 2: Defer with Issue (Expensive - use sparingly)
**When:** Change is large AND worth doing AND not critical to current PR.
**Action:**
1. Create GitHub issue NOW: `gh issue create --title "..." --body "..."`
2. Add to same milestone: `gh issue edit <num> --milestone "<milestone>"`
3. Add as sub-issue: `gh sub-issue add <parent> <new-issue>`
4. Reply: "Created #XYZ to track this. Not addressing in this PR because {reason}."
5. Optionally add `// TODO(#XYZ): description` code comment

**Only if:**
- Change is large enough to justify separate PR overhead
- Not critical to current PR's functionality
- PR is mature (many comments already resolved, not early review phase)

### Option 3: Disagree / Won't Fix
**When:** Suggestion is nitpicky, negligible, or you disagree with premise.
**Action:** Reply explaining why this won't be addressed. Be professional and concise.

**NEVER use for:**
- Test failures or errors (MUST be fixed)
- Security concerns
- Critical functionality issues

## Arguments

Arguments are passed via `$ARGUMENTS` in the format:

[issue-number]

**Optional:**
- `issue-number`: The GitHub issue number to create a PR for (defaults to extracting from current branch)

## User Input

```text
$ARGUMENTS

If arguments are provided, parse the issue number. Otherwise, extract from the current branch name.

Tmux Status Helper

Throughout the workflow, update tmux window name to reflect current phase.

!# Helper function to update tmux status
# Usage: update_tmux_status <emoji> <prefix> <number>
# Examples:
#   update_tmux_status "💻" "i" "483"  -> 💻i483 (coding on issue #483)
#   update_tmux_status "🔧" "pr" "485" -> 🔧pr485 (maintaining PR #485)
update_tmux_status() {
  local EMOJI="$1"
  local PREFIX="$2"
  local NUMBER="$3"

  if [ -n "$TMUX" ]; then
    TMUX_NAME="${EMOJI}${PREFIX}${NUMBER}"
    tmux rename-window "$TMUX_NAME" 2>/dev/null
  fi
}

# Phase emojis:
# 🔍 = gathering information
# 💻 = coding
# ⏳ = waiting for tests
# ❓ = waiting for user (need more info)
# 🚀 = submitting pr
# 🔧 = pr maintenance
# 🧹 = cleanup

# Prefix conventions:
# i = issue number (e.g., i483 for issue #483)
# pr = pull request number (e.g., pr485 for PR #485)

Overview

This command provides highly autonomous PR management, reducing cognitive load by:

• Validating environment and branch setup
• Analyzing all commits (not just the latest) for comprehensive PR description
• Creating PR with proper formatting and milestone
• Continuously monitoring CI/CD checks
• Detecting and guiding through rebase needs
• Resolving PR review comments in parallel
• Iteratively fixing issues until all checks pass

Workflow Phases

Phase 1: Pre-PR Validation

Goal: Ensure environment is properly configured before creating PR.

Actions:

1. Check working directory:

   pwd | grep -q "wip/" && echo "✅ In worktree" || echo "❌ Not in wip/ worktree"
   

   • MUST be in a wip/ worktree, not /workspace
   • If not in worktree, STOP and instruct user to use git-worktrees skill

2. Verify branch naming convention:

   BRANCH=$(git branch --show-current)
   # Should match: m<id>-p<id>-i<num>-<slug> or variants
   

   • Extract issue number: ISSUE_NUM=$(echo "$BRANCH" | grep -oP 'i\K[0-9]+' || echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
   • If no issue number in branch, STOP and ask user which issue this PR fixes

3. Verify issue exists and is open:

   gh issue view "$ISSUE_NUM" --json state,title,milestone
   

   • If issue is closed, WARN and ask user to confirm
   • Store milestone information for later (will add to PR)

4. Check for uncommitted changes:

   git status --porcelain
   

   • If there are uncommitted changes, STOP and ask user to commit them first

5. Verify branch has commits:

   # Check if branch has commits ahead of base
   git rev-list --count origin/main..HEAD
   

   • If count is 0, the PR would be empty and should be prevented
   • STOP and inform user the branch has no new commits

6. Verify remote branch exists or can be pushed:

   git push -n origin $(git branch --show-current) 2>&1
   

   • Dry-run push to check if branch can be pushed
   • If fails, investigate and resolve

7. Check if PR already exists:

   gh pr list --head $(git branch --show-current) --json number,title,url,state
   

   • If PR exists and is OPEN: Skip to Phase 4 (CI/CD Monitoring Loop)
   • If PR exists and is CLOSED: Warn user and ask whether to create new PR
   • If PR exists and is MERGED: Inform user and stop (branch should be cleaned up)
   • If no PR exists: Continue to Phase 2

Validation Summary:

• ✅ In