pr-shepherd

name	pr-shepherd
description	Analyze and fix failing GitHub PRs. Check .branchdeck/analysis.json to determine current state. If no analysis exists, analyze the PR. If analysis is approved, execute the fix plan.

PR Shepherd Workflow

You are shepherding a GitHub PR to get it ready to merge.

Get PR context

Read .branchdeck/pr-context.json for the PR you're working on:

• repo: the GitHub repo (e.g., "owner/repo")
• number: the PR number
• branch: the PR branch name
• base_branch: the target branch (e.g., "main")

Use these values in all gh commands below.

Determine your phase

Check if .branchdeck/analysis.json exists in the current worktree.

If it does NOT exist → Analyze

1. Read PR status: gh pr checks <number> --repo <repo>
2. Read review comments: gh pr view <number> --repo <repo> --comments
3. Read inline review comments: gh api repos/<owner>/<repo>/pulls/<number>/comments
4. Search codebase for relevant patterns
5. Check recent git history: git log --oneline -20
6. Classify confidence:
   • HIGH: lint/format, unused imports, single-file assertion, known pattern
   • MEDIUM: test logic, small refactor, dependency version bump
   • LOW: architecture, multi-file rewrite, security, unknown pattern
7. Write .branchdeck/analysis.json with your findings:

   {
     "pr": { "repo": "<repo>", "number": <number>, "branch": "<branch>" },
     "confidence": "HIGH|MEDIUM|LOW",
     "failures": [
       {
         "check_name": "<CI check name>",
         "error_summary": "<one-line summary>",
         "root_cause": "<what actually went wrong>",
         "fix_approach": "<how to fix it>"
       }
     ],
     "reviews": [
       {
         "reviewer": "<username>",
         "comment": "<review comment>",
         "proposed_response": "<how you'd address it>"
       }
     ],
     "plan_steps": [
       {
         "description": "<what to do>",
         "file": "<file path>",
         "change_type": "modify|create|delete"
       }
     ],
     "affected_files": ["<file1>", "<file2>"],
     "reasoning": "<brief explanation of your analysis>",
     "approved": false,
     "approved_plan": null,
     "resolved": false
   }
   

8. End your session. A human will review your analysis.

If it exists with approved: true → Fix

1. Read approved_plan from .branchdeck/analysis.json (the human may have edited the plan)
2. Execute each plan step in order
3. Follow the project's code standards (see CLAUDE.md)
4. Run the project's check suite (see CLAUDE.md for commands)
5. Stage, commit, push:

   git add <affected files>
   git commit -m "fix: <concise summary>"
   git push
   

6. Verify CI: gh pr checks <number> --repo <repo> --watch
7. If CI still fails, analyze the new failure and fix it (up to 3 attempts)
8. When done, update analysis.json: set resolved: true

If it exists with approved: false → Wait

Do nothing. End your session. The human hasn't reviewed yet.

Troubleshooting

If gh commands fail with 403/404, verify authentication: gh auth status