pr-watch

PR Watch

Monitor the current branch's PR autonomously — detect and respond to CI failures, review comments, and merge conflicts. Consumes zero LLM tokens while waiting.

Assumptions

• The current branch has an open PR. If not, stop with: "No open PR on this branch."
• The working directory is the repo being monitored.

Commit Discipline

Commit and push after every logical fix. Never batch unrelated fixes. Formatting/lint fixes from dev_checks get their own commit.

Workflow

1. Capture Baseline

PR=$(gh pr view --json number --jq .number)
REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
PREV_COMMENTS=$(gh pr view $PR --json comments --jq '.comments | length')
PREV_REVIEWS=$(gh pr view $PR --json reviews --jq '.reviews | length')

Confirm the PR is open. If merged or closed, report status and stop.

Report: "Watching PR #N — polling every 60s for CI, reviews, comments, and conflicts."

2. Launch Background Monitor

Start a background poll loop (run_in_background: true Bash command):

PR=<number>
PREV_COMMENTS=<baseline>
PREV_REVIEWS=<baseline>
ITER=0; MAX_ITER=120

while [ "$ITER" -lt "$MAX_ITER" ]; do
    sleep 60
    ITER=$((ITER + 1))

    CI=$(gh pr checks $PR --json state --jq '.[].state' 2>/dev/null | sort -u)
    if echo "$CI" | grep -q "FAILURE"; then
        echo "ALERT:CI_FAILURE"
        gh pr checks $PR
        exit 0
    fi

    NEW_COMMENTS=$(gh pr view $PR --json comments --jq '.comments | length')
    if [ "$NEW_COMMENTS" -gt "$PREV_COMMENTS" ]; then
        echo "ALERT:NEW_COMMENTS count=$NEW_COMMENTS prev=$PREV_COMMENTS"
        exit 0
    fi

    NEW_REVIEWS=$(gh pr view $PR --json reviews --jq '.reviews | length')
    if [ "$NEW_REVIEWS" -gt "$PREV_REVIEWS" ]; then
        echo "ALERT:NEW_REVIEW"
        exit 0
    fi

    MERGEABLE=$(gh pr view $PR --json mergeable --jq '.mergeable')
    if [ "$MERGEABLE" = "CONFLICTING" ]; then
        echo "ALERT:MERGE_CONFLICT"
        exit 0
    fi

    STATE=$(gh pr view $PR --json state --jq '.state')
    if [ "$STATE" = "MERGED" ] || [ "$STATE" = "CLOSED" ]; then
        echo "INFO:PR_$STATE"
        exit 0
    fi

    DECISION=$(gh pr view $PR --json reviewDecision --jq '.reviewDecision')
    ALL_PASS=$(gh pr checks $PR --json state --jq '.[].state' 2>/dev/null | sort -u)
    if [ "$DECISION" = "APPROVED" ] && ! echo "$ALL_PASS" | grep -qE "FAILURE|PENDING"; then
        echo "INFO:READY_TO_MERGE"
        exit 0
    fi
done
echo "INFO:TIMEOUT"

3. Handle Alerts

When the monitor exits, act on the signal, then restart from step 2 with updated baselines.

ALERT:CI_FAILURE

1. Identify failed runs: gh pr checks $PR
2. Fetch logs: gh run view <run_id> --log-failed
3. Diagnose — read relevant source files
4. Fix, run tests locally, commit and push
5. Restart monitor

ALERT:NEW_COMMENTS

1. Fetch new comments:

   gh pr view $PR --json comments --jq '.comments | .[-<delta>:] | .[] | "@\(.author.login): \(.body[0:500])"'
   

2. Fetch inline review comments:

   gh api repos/$REPO/pulls/$PR/comments --jq '.[] | "\(.path):\(.line // .original_line) — \(.user.login): \(.body)"'
   

3. Address each (see "Addressing Feedback")
4. Restart monitor

ALERT:NEW_REVIEW

1. Fetch review:

   gh pr view $PR --json reviews --jq '.reviews[-1] | "@\(.author.login) (\(.state)): \(.body)"'
   

2. APPROVED — report to user, check if all checks pass
3. CHANGES_REQUESTED / COMMENTED — fetch inline comments and address
4. Restart monitor

ALERT:MERGE_CONFLICT

1. Merge base branch:

   BASE=$(gh pr view $PR --json baseRefName --jq '.baseRefName')
   git fetch origin $BASE && git merge origin/$BASE
   

2. Resolve conflicts, run tests, commit and push
3. Restart monitor

INFO:PR_MERGED / INFO:PR_CLOSED

Report status. Stop monitoring.

INFO:READY_TO_MERGE

Report: "PR #N is approved and all checks pass. Ready to merge." Continue monitoring — never merge autonomously.

INFO:TIMEOUT

Report timeout (~2 hours). Suggest re-running /pr-watch to restart.

Future: Webhook Mode

Polling is a stopgap. The long-term plan is ephemeral Cloudflare Worker webhooks — spin up a temporary endpoint, register it with GitHub, relay events to the local session, tear it down when the PR closes. When that infra exists, replace the poll loop with it.

4. Addressing Feedback

For each comment:

• CI failures: diagnose from logs, fix, test locally, commit and push
• Substantive code feedback: make the change, test, commit and push each fix separately
• Questions or style preferences: ask the user — do not guess
• Acknowledged nitpicks: reply on the PR thread

After all items:

1. Run the project's test suite
2. Run dev_checks if available: "$(git rev-parse --show-toplevel)/scripts/dev_checks.sh"
3. Formatting fixes from dev_checks get their own commit

Team Context

When operating as a teammate, use SendMessage to notify the lead of changes:

• "PR #194: CI failed — fixing flaky test in auth_test.go"
• "PR #184: now CONFLICTING — resolving merge conflict"
• "PR #187: approved, all checks green — ready to merge"