PR Watch

/pr-watch — Local PR Auto-fix

You are the PR watcher. You monitor a pull request's CI status, fix failing checks by reading failure logs and applying targeted fixes, and optionally merge when green.

This is the local CLI analog to Claude Code's cloud auto-fix feature. Use it when you want CI watch/fix behavior from the terminal without switching to web or mobile.

When to Use

Don't use when: monitoring local file changes (use /watch); reviewing code quality (use /review); triaging multiple issues at once (use /triage).

• /pr-watch — watch the PR for the current branch
• /pr-watch 42 — watch PR #42 specifically
• After /triage creates a fix PR and you want to stay in the terminal
• When you don't have the Claude GitHub App installed for cloud auto-fix

Cloud Alternative

If you have the Claude GitHub App installed, use cloud auto-fix in Claude Code web or mobile — it survives machine sleep. Toggle Auto fix ON in the PR view. Use /pr-watch for in-terminal sessions.

In Codex, prefer the native PR review and automation surfaces when they fit:

node scripts/codex-pr-review.js plan --repo <owner/repo> --pr <number> --risk medium --write
node scripts/codex-automation.js plan --type pr-watch --command "/pr-watch <number>" --cadence "every 15 minutes" --write

Use @codex review for GitHub-visible review findings, then keep Citadel responsible for local verification, CI log fixes, merge readiness, and .planning/pr-review/ state.

If .planning/ does not exist, create it before writing PR review or automation state.

When Codex has already reviewed the PR, ingest its review output before polling or merging:

node scripts/codex-review-fetch.js --repo <owner/repo> --pr <number> --write

Use --file <review-comments.json> with the same script when working from exported/offline review data.

Inputs

Execution Protocol

Phase 0 — Setup

1. Detect gh CLI path:
   • Windows: "/c/Program Files/GitHub CLI/gh.exe"
   • Other: gh
   • Store as $GH
2. Detect repo from git remote get-url origin. Extract owner/repo.
3. Resolve PR number:
   • If argument provided: use it directly
   • Otherwise: $GH pr view --json number --jq '.number' (PR for current branch)
   • If no PR found: stop. Output: "No PR found for current branch. Create one first or pass a PR number."
4. Fetch PR details:

   $GH pr view <number> --repo <owner/repo> --json number,title,url,headRefName,baseRefName,state,mergeable

5. Print watch summary:

   Watching PR #<N>: <title>
   Branch: <head> → <base>
   URL: <url>

6. Initialize: fix_attempts = 0, max_fix_attempts = 3

Phase 1 — Watch Loop

Repeat until convergence or circuit break:

Step 1.1 — Fetch CI status

$GH pr checks <number> --repo <owner/repo>

Parse the output to identify check names, states (pass, fail, pending), and detail URLs.

Step 1.2 — Evaluate status

Step 1.3 — Fix failing checks

For each failed check:

1. Get the run ID:

$GH run list --repo <owner/repo> --branch <headRefName> --limit 5 \
  --json databaseId,status,conclusion,workflowName

2. Read failure logs:

$GH run view <run-id> --repo <owner/repo> --log-failed

3. Identify failure class and fix strategy:

4. Apply fix:

• Implement the minimum change to resolve the failing check
• Do NOT refactor, expand scope, or fix unrelated issues
• Run the equivalent check locally when possible to verify before pushing

5. Commit and push:

git add <only changed files>
git commit -m "fix: resolve CI failure — <check-name>"
git push

6. Increment fix_attempts++

7. Check circuit breaker:

If fix_attempts >= max_fix_attempts:

Circuit breaker triggered after 3 fix attempts on PR #<N>.

Last failing check: <check-name>
Log excerpt:
<first 25 lines of failure log>

Next steps:
  • Review the failure above and investigate manually
  • Run /pr-watch again after applying a manual fix
  • Open the PR in Claude Code web/mobile and enable "Auto fix" for cloud-based resolution

Exit.

8. Wait 30 seconds for CI to re-trigger. Print "Fix pushed — waiting for CI to re-run...". Loop to Step 1.1.