agentleFS
Sign inStart free
DogaOztuzunDogaOztuzun/branchdeck/.claude/skills/pr-shepherd/SKILL.md

pr-shepherd

Skill18 starsChanged 7 months agoMITView on GitHub

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.

  • Commits and pushes

We split this skill into the rules it gives an agent

17 rules. 0 are common, 7 are distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

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

    line 15
  2. Very specific:

    Use these values in all gh commands below.

    line 21
  3. Very specific:

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

    line 25
  4. Very specific:

    Read PR status: gh pr checks <number> --repo <repo>

    line 29
  5. Very specific:

    Read review comments: gh pr view <number> --repo <repo> --comments

    line 30
  6. Very specific:

    Read inline review comments: gh api repos/<owner>/<repo>/pulls/<number>/comments

    line 31
  7. Distinctive:

    Search codebase for relevant patterns

    line 32
  8. Distinctive:

    Check recent git history: git log --oneline -20

    line 33
  9. Distinctive:

    MEDIUM: test logic, small refactor, dependency version bump

    line 36
  10. Very specific:

    Write .branchdeck/analysis.json with your findings:

    line 38
  11. Very specific:

    Read approved_plan from .branchdeck/analysis.json (the human may have edited the plan)

    line 76
  12. Distinctive:

    Follow the project's code standards (see CLAUDE.md)

    line 79
  13. Distinctive:

    Run the project's check suite (see CLAUDE.md for commands)

    line 80
  14. Distinctive:

    If CI still fails, analyze the new failure and fix it (up to 3 attempts)

    line 88
  15. Very specific:

    When done, update analysis.json: set resolved: true

    line 89
  16. Distinctive:

    Do nothing. End your session.

    line 93
  17. Very specific:

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

    line 97

“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free