/pr-shepherd

name: pr-shepherd
description: Monitor a PR through to merge — handle CI failures, review comments, and thread resolution automatically until all checks pass

pr-shepherd

Use when a PR has been created and needs to be monitored through to merge - handles CI failures, review comments, and thread resolution automatically until all checks pass and all threads are resolved.

**IMPORTANT**: This skill is designed for the **agent working in a worktree**, NOT the orchestrator. The agent handles its own PR monitoring so the orchestrator remains free for other work.

Coordination Mode Note

This skill supports both coordination modes:

• **Task Mode** (default): Runs as a single long-running `Task()` with `run_in_background: true`. Orchestrator checks via `TaskOutput(block: false)`.
• **Team Mode**: Runs as a persistent `shepherd` teammate in the `issue-{number}` team. Sends async status updates via `SendMessage` (CI failure, review comments, all-green, PR merged). Orchestrator can respond with instructions (e.g., "defer that comment, create an issue instead"). Responds to `shutdown_request` for graceful exit.

All monitoring, fixing, and review handling logic is identical in both modes. See `./guides/agent-coordination.md` for mode detection.

---

When to Activate

Activate this skill when ANY of these conditions are true:

• Agent just created a PR with `gh pr create`
• User asks to "shepherd", "monitor", or "see through" a PR
• User invokes `/pr-shepherd <pr-number>`
• User asks to "watch this PR" or "handle this PR until it's merged"
• Orchestrator spawned you with instructions to shepherd a PR
• **Automatic**: `bin/create-pr-with-shepherd.sh` was used (outputs shepherd instructions)

Automatic Activation via Wrapper Script

When `bin/create-pr-with-shepherd.sh` creates a PR, it outputs shepherd instructions:

==========================================
  PR Shepherd Active for PR #123
==========================================

The pr-shepherd skill will:
  - Monitor CI/CD status
  - Auto-fix lint, type, and test issues
  - Handle review comments
  - Resolve threads after addressing feedback
  - Report when PR is ready to merge

To manually invoke shepherd later:
  /pr-shepherd 123

When you see this output, **immediately invoke the pr-shepherd skill** with the PR number shown.

Announce at Start

"I'm using the pr-shepherd skill to monitor this PR through to merge. I'll watch CI/CD, handle review comments, and fix issues as they arise."

For Orchestrators: Spawning Agents with PR Shepherding

When spawning an agent to work in a worktree, include PR shepherding in the task prompt:

Work in worktree at /path/to/worktree on branch feature/xyz.

Task: [describe the implementation task]

After creating the PR:
1. Use the pr-shepherd skill to monitor it through to merge
2. Handle CI failures and review comments autonomously
3. Only escalate to orchestrator for complex issues requiring user input
4. Report back when PR is ready to merge or if blocked

Run in background so I can continue other work.

**Key principle**: The agent owns its PR lifecycle. The orchestrator spawns and forgets, checking back via `AgentOutputTool` when needed.

State Machine

The agent operates in one of these states:

MONITORING → FIXING → MONITORING → WAITING_FOR_USER → FIXING → MONITORING → DONE

| State | What Happens | Exit When | | ------------------ | ------------------------------------------- | ---------------------------------------------- | | `MONITORING` | Poll CI and reviews every 60s in background | CI fails, new comments, all done, or need help | | `FIXING` | Fix issues using TDD, run local validation | Local validation passes OR need user guidance | | `HANDLING_REVIEWS` | Invoke `handling-pr-comments` skill | Comments handled OR need user input | | `WAITING_FOR_USER` | Present options, wait for user decision | User responds | | `DONE` | All CI green + all threads resolved | Exit successfully |

Phase 1: Initialize

# Get PR info
PR_NUMBER=$(gh pr view --json number -q .number 2>/dev/null)
OWNER=$(gh repo view --json owner -q .owner.login)
REPO=$(gh repo view --json name -q .name)

# If no PR on current branch, check if number was provided
if [ -z "$PR_NUMBER" ]; then
  echo "No PR found for current branch. Provide PR number."
  exit 1
fi

echo "Shepherding PR #$PR_NUMBER"

Phase 2: Monitoring Loop (Background)

Run GTG every 60 seconds as the **single source of truth** for PR readiness:

Primary Check: GTG (Good-To-Go)

GTG consolidates CI status, comment classification, and thread resolution into one call. Use it instead of separate API queries.

# Primary readiness check — structured JSON output
GTG_RESULT=$(gtg $PR_NUMBER --repo "$OWNER/$REPO" --format json \
  --exclude-checks "Merge Ready (gtg)" \
  --exclude-checks "CodeRabbit" \
  --exclude-checks "Cursor Bugbot" \
  --exclude-checks "claude" 2>&1)

STATUS=$(echo "$GTG_RESULT" | jq -r '.status')
ACTION_ITEMS=$(echo "$GTG_RESULT" | jq -r '.action_items[]?' 2>/dev/null)
CI_STATE=$(echo "$GTG_RESULT" | jq -r '.ci_status.state')

**GTG statuses:**

| Status | Meaning | Agent Action | | -------------------- | ---------------------------------- | ----------------------------------------- | | `READY` | All CI green, all threads resolved | → DONE | | `ACTION_REQUIRED` | Actionable comments need fixes | → HANDLING_REVIEWS (use `action_items`) | | `UNRESOLVED_THREADS` | Review threads still open | → HANDLING_REVIEWS | | `CI_FAILING` | One or more CI checks failing | → FIXING