code-review

What this skill does

# Interactive Code Review

Run the full 5-agent code review pipeline on a diff (PR or local), surface every finding regardless of confidence score, and walk the user through each one with an apply/modify/defer/dismiss decision.

This is intentionally different from `/code-review:code-review`, which filters findings by confidence (≥80) and posts results as a PR comment. This skill keeps every finding and lets the developer make the call per item.

## Why this exists

Filtered, comment-only review is great for sign-off, but it discards findings that may matter and gives the developer no easy way to act on them. This skill assumes the developer is in the loop and wants to triage each finding with full context.

## Step 1 — Detect input mode

Parse the invocation arguments:

- If args contain a numeric token → **PR mode** with that PR number. Fetch the diff via `gh pr diff <N>`.
- If args contain `--local` → **force local mode** (skip auto-detection).
- Otherwise auto-detect:
  1. Check that `gh` is installed and the working directory is inside a GitHub repo. If either check fails, fall back to local mode silently.
  2. Run `gh pr view --json number 2>/dev/null`. If it returns a number, that's the open PR for the current branch → **PR mode** with that number.
  3. If no PR is found → **local mode**.

For local mode, detect the base branch by trying `main`, then `master`, then `develop`, in that order. Use the first one that exists locally or on the remote (`git rev-parse --verify <name>` or `git rev-parse --verify origin/<name>`). If none exist, ask the user via AskUserQuestion which branch to diff against.

Print a one-line banner so the user can sanity-check the detected mode before the heavy work begins. Examples:

```
📍 PR #42 review mode (auto-detected)
📍 Local diff review mode (main..HEAD, 12 files)
```

## Step 2 — Pre-flight

Compute the diff:

- PR mode: `gh pr diff <N>`
- Local mode: `git diff <base>..HEAD`

Then:

- If the diff is empty, exit with a friendly message: `No changes to review.` and stop.
- If the diff exceeds ~5000 lines, warn the user and confirm via AskUserQuestion before proceeding. Large diffs cost a lot of agent runs; the user should opt in.
- Dispatch a single Haiku agent to collect the **paths** (not contents) of relevant CLAUDE.md files: the repo root CLAUDE.md (if present) and any CLAUDE.md inside directories whose files were modified. The reviewers will read these directly when they need them.
- Read the **user's global CLAUDE.md** (typically `~/.claude/CLAUDE.md`) once and extract any CLI tool conventions and house style rules. These travel with every subagent prompt below — see *Subagent dispatch conventions*.

## Subagent dispatch conventions

Subagents inherit nothing from the user's CLAUDE.md by default. Every dispatch prompt in Steps 3, 4, and 6 MUST include the following baseline so subagents behave consistently and don't trip safety warnings:

- **Absolute working directory** — the absolute path of the target repo. Especially important for monorepos where directory names repeat (e.g. `<root>/imwebme/packages/packages/clay-ai-poc/...` is correct even though it looks like a typo).
- **CLI tool conventions from the user's CLAUDE.md** — if the user's CLAUDE.md prefers specific replacements (e.g. `fd` over `find`, `rg` over `grep`, `eza` over `ls`, `bat` over `cat`), restate those rules in the subagent prompt. Subagents that violate them trip the harness's security warning system.
- **Strict output format** — when expecting JSON, end the prompt with "Return ONLY the JSON, no prose." Subagents are chatty by default and will narrate unless told not to.
- **Absolute paths only** — never use relative paths inside subagent prompts; subagents may resolve them against an unexpected CWD.

Build a small reusable context block once after the Pre-flight step and prepend it to each subagent prompt.

## Step 3 — Five parallel review agents (Sonnet)

Dispatch all five reviewers in parallel — one message, five Agent tool calls. Each reviewer returns a flat list of findings matching this shape:

```typescript
type Finding = {
  file: string;        // path relative to repo root
  line_range: string;  // e.g. "42-47"
  category: "bug" | "claude-md" | "history" | "comments" | "past-prs";
  description: string; // one paragraph
  evidence: string;    // quoted code or doc snippet
};
```

Example output:

```json
[
  {
    "file": "src/auth.ts",
    "line_range": "42-47",
    "category": "bug",
    "description": "Missing null check on token before accessing expires field.",
    "evidence": "if (token.expires < Date.now()) { ... }"
  }
]
```

| # | Reviewer role | Category tag | Notes |
|---|---|---|---|
| 1 | CLAUDE.md compliance | `claude-md` | Pass the CLAUDE.md paths from Step 2. Verify each cited rule actually appears in those files before flagging. |
| 2 | Shallow bug scan | `bug` | Read only the changed lines plus minimal surrounding context. Focus on real bugs that will bite at runtime. Skip nitpicks. |
| 3 | Git blame & history | `history` | Read `git log -p` and `git blame` for the modified regions. Flag changes that conflict with documented past intent. |
| 4 | Inline comment guidance | `comments` | Read inline comments and JSDoc/TSDoc near the changes. Flag changes that violate directives written there. |
| 5 | Past-PR comment patterns | `past-prs` | **PR mode only.** Read recent PR comments on the modified files via `gh pr list --state merged` + `gh pr view <N> --comments`. Skip entirely in local mode. |

Each reviewer must ignore these false-positive classes (same as the official pipeline):

- Pre-existing issues unrelated to this diff
- Things a linter, typechecker, or CI step would catch
- Changes outside the modified line ranges
- Pedantic style nitpicks not called out in CLAUDE.md or inline comments
- Changes that look intentional in context (refactors, deletions)
- Issues silenced explicitly in the code (lint-ignore, eslint-disable, etc.)

## Step 4 — Confidence scoring (parallel Haiku)

For every finding from Step 3, dispatch one Haiku agent in parallel that returns a single integer score on the official 0/25/50/75/100 rubric:

- **0** — Not confident at all. False positive or pre-existing issue.
- **25** — Somewhat confident. Might be real, might be a false positive; couldn't verify.
- **50** — Moderately confident. Real issue but probably a nitpick or low-impact in context.
- **75** — Highly confident. Real issue likely to bite in practice, or directly mentioned in a relevant CLAUDE.md.
- **100** — Absolutely certain. Confirmed real, will happen frequently.

Attach the score to the finding as metadata. **Do not filter.** The goal is to inform the user's decision in Step 8, not to drop anything.

## Step 5 — Normalize the finding list

This step runs in the **main agent**, not a subagent — sort stability matters and delegating it produces non-deterministic ordering across runs.

- Dedupe near-duplicates: findings on the same `file` whose `line_range` overlaps (or is within 3 lines) and whose descriptions describe the same issue → keep the one with the highest score, merge the others' evidence into the kept finding.
- Sort: `score` descending, ties broken by `file` ascending, then by the numeric start of `line_range` ascending. Apply this order explicitly in the main agent so identical inputs always produce the same display order.
- If the resulting list has more than 30 findings, ask the user via AskUserQuestion: `View all`, `Top 30 only` (drop the rest for this run), or `Abort`.

## Step 6 — Pre-analysis (parallel Haiku)

For every surviving finding, dispatch one Haiku agent in parallel that:

1. Uses Read to load the relevant lines of the file as they exist right now.
2. Returns a structured pre-analysis matching this shape:

```typescript
type PreAnalysis = {
  validity_assessment: "seems valid" | "partially valid" | "questionable" | "likely false positive";
  suggested_fix: {
    before: string;     // curre