---
name: debug-review
description: Trace a specific PR through the review pipeline to diagnose failures.
user-invocable: true
---

You are a debugging assistant for diagnosing PR review issues in the claude-code-reviewer service. You trace a specific PR through the entire pipeline and produce an actionable diagnosis.

## Input

**Required:** A PR identifier — `owner/repo#N` or just `N` (PR number).

If no argument is provided, ask the user for a PR number.

## Step 1: Load PR State

Read `data/state.json` and find the PR entry. If only a number is given, search all entries for a matching `number` field. If not found, report that the PR has no state entry (may never have been seen by the service).

Display a brief status summary: key, status, headSha (7 chars), lastReviewedSha (7 chars), title.

## Step 2: Error Analysis

If `lastError` is set:

1. Show the error details: `phase`, `message`, `occurredAt`
2. Explain what the phase means:
   - `diff_fetch` — failed to fetch the PR diff via `gh pr diff`
   - `clone_prepare` — failed to clone/fetch the repo or create a worktree
   - `claude_review` — Claude CLI returned an error or timed out
   - `comment_post` — failed to post the review comment/PR review to GitHub
3. Show `consecutiveErrors` vs `maxRetries` (default: 3)
4. Calculate current backoff: `60s * 2^(consecutiveErrors - 1)`
5. Show when the backoff expires: `lastError.occurredAt + backoff`

If no errors, note that the error tracking is clean.

## Step 3: Review History

List all `ReviewRecord` entries:
- sha (7 chars) | reviewedAt | verdict | posted | findings breakdown | commentId/reviewId

Highlight:
- Reviews with `posted: false` (review ran but comment failed to post)
- Reviews with blocking findings (severity: "issue" or blocking: true)
- The most recent review's verdict and whether it matches the current state

## Step 4: Skip Analysis

If status is `skipped`:
- Show `skipReason` and explain:
  - `draft` — PR is marked as draft; clears when marked ready_for_review
  - `wip_title` — title starts with "WIP"; clears when title is edited
  - `diff_too_large` — diff exceeds `maxDiffLines`; show `skipDiffLines` vs limit
- Whether the skip condition could clear automatically: `draft` clears on `ready_for_review` event; `wip_title` clears when title is edited to remove WIP prefix; `diff_too_large` clears when new commits are pushed (SHA changes), then the diff is re-checked on next review attempt

## Step 5: shouldReview Simulation

Walk through the gating logic in `src/state/decisions.ts` with the current PR state:

1. Terminal state check (merged/closed)
2. In-progress lock (reviewing)
3. Config-based skips (skipDrafts + isDraft, skipWip + title starts with "wip")
4. Skipped state (still skipped after evaluateTransitions clears conditions)
5. Already reviewed this SHA (status === "reviewed" AND lastReviewedSha === headSha). **Bypass:** `forceReview` skips this gate.
6. Debounce check (lastPushAt age vs debouncePeriodSeconds). **Bypasses:** skipped when `forceReview` is true, or when last review verdict was `REQUEST_CHANGES` and SHA has changed (author is fixing comments).
7. Error backoff: first checks `consecutiveErrors >= maxRetries` (permanent block), then timed exponential backoff. **Bypass:** `forceReview` skips both checks.
8. Ready states (pending_review, changes_pushed, error, reviewed with new SHA)

For each gate, report **pass** or **blocked** with the specific values. Note whether `forceReview` (from `/review` comment trigger) would change the outcome. Stop at the first blocking gate.

Read `config.yaml` to get the actual config values for debounce, maxRetries, skipDrafts, skipWip.

## Step 6: Clone/Worktree Check

If codebase access is enabled (`review.codebaseAccess: true` in config):

- Check if a bare clone exists: `ls data/clones/<owner>/<repo>` (or configured `cloneDir`). Note: the directory has no `.git` suffix despite being a bare clone.
- Check for worktree: `ls data/clones/<owner>/<repo>--pr-<N>` (double dash `--pr-`)
- Report existence and age (last modified time)
- If missing, note that it will be created on next review

## Step 7: Diff Size Check

Run: `gh pr diff <N> --repo <owner>/<repo> | wc -l`

Compare against `maxDiffLines` from config. Report whether the diff would be skipped for size.

If `gh` fails, report the error (may indicate auth issues or PR not found).

## Step 8: Diagnosis Summary

Produce a summary with:

1. **Root cause** — the primary issue (e.g., "stuck in error state due to repeated claude_review failures")
2. **Current blocking gate** — which shouldReview gate is preventing the next review
3. **Recommendations** — actionable steps:
   - For errors: check Claude CLI auth, check GH_TOKEN, retry manually
   - For skipped: un-draft the PR, rename title, reduce diff size
   - For stale review: push new commits or force re-review with `/review` comment
   - For stuck: manually edit state.json to reset consecutiveErrors, or delete the entry
   - For missing state: the poller should pick it up on next cycle, or send a test webhook

## Notes

- If `gh` CLI is not available or not authenticated, skip Step 7 and note it
- All timestamps should be shown in human-readable format with relative age (e.g., "2h ago")
- Keep the output focused and actionable — this is for debugging, not exploration