PR Shepherd Skill

Start the watcher immediately after the PR is created. The script self-backgrounds, writes a log under tmp/, and exits once CI is green and all review threads are resolved.

./build/scripts/pr-watch.sh <PR_NUMBER>
# e.g.
./build/scripts/pr-watch.sh 574
./build/scripts/pr-watch.sh 574 --interval 10   # poll every 10 minutes

Monitor progress:

tail -f tmp/pr-watch-<PR_NUMBER>.log

The script invokes claude -p with structured context whenever:

• A CI check-run fails (logs included in the prompt).
• A new unresolved review thread appears from an external reviewer.

It exits cleanly and logs PR #NNN is ready when all checks pass and all threads are resolved.

If pr-watch is not suitable, run this skill directly and follow the Detailed Instructions below.

See Detailed Instructions for the full loop behaviour.

Before starting the loop, ask the user for the polling interval:

How long should I wait between checks? (default: 10 minutes)

Accept any value in minutes. Use 10 minutes if the user does not specify. Convert to seconds for sleep (e.g. 5 minutes → sleep 300).

The skill then runs a loop at that interval:

1. Check CI status immediately — if the build is already red, fix it before waiting.
2. Wait the chosen interval for CI and reviewers to produce additional feedback.
3. Fetch and address all open review comments.
4. Check CI status again.
   • Green: loop exits — PR is ready.
   • Still running: wait another interval and repeat from step 3.
   • Red: investigate failures, apply fixes, push, then wait and repeat.

Before the first sleep, check whether CI is already red. A push can immediately trigger a pre-existing failure (e.g. a broken dependency or a lint check that fires on the new code). Do not silently wait through a known-broken build.

gh pr checks

• If any check has already failed, go directly to Step 5 and fix it before sleeping.
• If checks are pending or all green, proceed to Step 2.

After confirming CI is not already red, pause for the chosen interval to allow CI to complete and reviewers to post comments.

sleep <interval_in_seconds>

Retrieve all unresolved review comments on the PR:

gh pr view --comments
gh api repos/{owner}/{repo}/pulls/{pr_number}/comments

For each open comment:

1. Read the comment carefully and understand the requested change.
2. Apply the fix in the relevant source file(s).
3. Stage and commit the change:

git add <modified-files>
git commit -m "[component] Address review comment: <brief description>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"

1. Push all accumulated commits once all comments in the current batch are addressed:

git push

1. Required: reply to each review comment on GitHub, referencing the fix commit. Do not skip this step — the reviewer must be able to see what changed and in which commit.

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \
  -X POST -f body="Fixed in commit <sha> — <brief description of what was changed>."

1. Required: resolve each review thread on GitHub using the GraphQL API. Threads must be marked resolved so the PR dashboard shows no outstanding comments. First, get the thread IDs:

gh api graphql -f query='
{
  repository(owner: "{owner}", name: "{repo}") {
    pullRequest(number: {pr_number}) {
      reviewThreads(first: 50) {
        nodes {
          id
          isResolved
          comments(first: 1) { nodes { databaseId body } }
        }
      }
    }
  }
}'

Then resolve each unresolved thread:

gh api graphql -f query="mutation {
  resolveReviewThread(input: {threadId: \"<thread_id>\"}) {
    thread { isResolved }
  }
}"

Important: never amend existing commits — always create new commits for fixes. This preserves the review history.

Query the current state of all CI checks on the PR:

gh pr checks

Interpret the result:

When one or more checks are red:

1. Identify the failing check:

gh run list --branch <branch-name>
gh run view <run-id> --log-failed

1. Read the failure output carefully. Common categories:
   • Compilation errors: fix the offending source files.
   • Test failures: fix or update the failing tests.
   • Linting / formatting: apply the required formatting fixes.
   • Schema validation: re-run validate_schemas.sh locally and fix warnings.
2. Apply the fixes, commit, and push:

git add <modified-files>
git commit -m "[component] Fix CI failure: <brief description>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
git push

1. Return to Step 2 (wait the chosen interval) and repeat the loop.

The loop terminates when gh pr checks reports all checks as passed. At that point inform the user:

All CI checks are green. The PR is ready to review and merge.