| name | debug-pr |
| description | Debug why a PR or issue is stuck by cross-referencing orchestrator logs with GitHub state. Use when asked to check progress on a PR/issue or investigate why work isn't completing. |
| argument-hint | ["pr-or-issue-url-or-number"] |
Debug why a PR or issue is stuck by checking orchestrator logs against GitHub state.
Input
The user will provide a PR number, issue number, or GitHub URL. Extract the repo and number from it. If only a number is given, check recent orchestrator logs to identify the repo.
Step 1 — Check GitHub state
Gather current state from GitHub in parallel:
gh pr view <number> --repo <owner/repo> --json title,body,state,url — PR statusgh api repos/<owner/repo>/issues/<number>/comments --jq '.[-1]' — last issue/PR commentgh api repos/<owner/repo>/pulls/<number>/comments --jq '.[-1]' — last review comment
Note the last comment author, timestamp, and content. This is what the user sees.
Step 2 — Search orchestrator logs
Search today's orchestrator log for the PR and issue numbers:
grep -n "<pr_number>\|<issue_number>" logs/$(date -u +%Y-%m-%d)/orchestrator.log
Use Grep on logs/YYYY-MM-DD/orchestrator.log in the Millwright checkout.
Look for:
- Dispatch lines: "dispatching fix" or "unaddressed comment(s)" — did the orchestrator detect work to do?
- Spawn lines: "Spawned claude for" — was a worker actually launched?
- Error lines: stack traces,
Errno::ENOENT, permission errors between detection and spawn
- Status transitions: "moving to In review", "moving to Done"
If a dispatch was detected but no spawn follows, there is likely a crash between detection and spawn — read the lines immediately after the dispatch line.
Step 3 — Check worker logs
Worker logs are in logs/YYYY-MM-DD/ with these naming conventions:
pr-<number>.log — PR review comment workersci-fix-<number>.log — CI failure fix workersissue-<number>.log — issue dispatch workers
Check:
- File size — 0 bytes means the worker either crashed immediately or is still running
- File contents — look for errors, stack traces, or completion messages
- Process status — if the log is empty, check if the process is still alive:
ps aux | grep <pid>
The PID is logged in the orchestrator spawn line.
Step 4 — Diagnose
Cross-reference GitHub state with log state. Common failure modes:
| Symptom | Likely cause |
|---|
| Dispatch detected, no spawn line, stack trace | Orchestrator crash — bad path, missing binary, permission error |
| Spawn line exists, worker log is 0 bytes, process dead | Worker crashed on startup — bad env, missing dependency |
| Spawn line exists, worker log is 0 bytes, process alive | Worker is still running — just needs time |
| Spawn line exists, worker log has content but no push | Worker hit an error during execution — read the log |
| No dispatch detected at all | Dispatch lock may be active — check state/ for lock files, or PR has no actionable comments |
| "Working on this" comment but no result | Worker was spawned but failed silently — check worker log and process |
Step 5 — Report
Tell the user:
- What the orchestrator did (detected, dispatched, or missed)
- What the worker did (succeeded, failed, still running)
- The root cause if something went wrong
- A fix if applicable
