--- name: gza-code-review-interactive description: Review changes on current branch and output a structured review. Optionally post to PR with --pr flag, or apply non-blocking follow-ups inline with --apply-followups. allowed-tools: Bash(git:*), Bash(gh:*), Bash(uv run:*), Read, Edit, Write, Glob, Grep, Agent, AskUserQuestion version: 2.4.0 public: true ---

# Interactive Code Review

Review committed changes on the current feature branch and output a structured review.

Requires being on a non-main branch with commits ahead of main. If not, stop and tell the user: "Switch to a feature branch with commits to review. This skill reviews committed changes on feature branches (git diff main...HEAD)."

## Arguments

- `--pr` — Post the review as a PR comment (requires an existing PR on the branch) - `--apply-followups` — After the review, apply all non-blocking follow-ups inline without prompting. Has no effect if the verdict is `CHANGES_REQUESTED` (blockers exist) or if the review reports no follow-ups. Without this flag, the skill prompts the user interactively before applying. - No arguments — Just output the review locally, no PR interaction. If follow-ups exist, prompt the user once at the end (see Step 6).

## Process

### Step 1: Verify branch state

1. Check current branch: `git branch --show-current` - If on `main` or `master`, stop and tell the user to switch to a feature branch 2. Check for uncommitted changes: `git status --porcelain` - If there are uncommitted changes, warn the user but proceed with reviewing committed changes 3. Check if branch has commits ahead of main: `git log main..HEAD --oneline` - If no commits ahead, stop and tell the user there's nothing to review

### Step 2: Find PR (only if --pr flag is set)

1. Look up existing PR: `gh pr view --json number,url,title 2>/dev/null` 2. If no PR exists, stop and tell the user to create one first (do NOT create a PR automatically) 3. Capture the PR number and URL

### Step 3: Capture review context in the parent session

Capture canonical ask context before spawning the reviewer: - If the caller already provided a `## Review scope:` section, pass it through unchanged, along with any `## Original plan context (out of scope except for the review scope):` section. - Otherwise, if the caller already provided exactly one canonical ask section (`## Original plan:` or `## Original request:`), pass that section through unchanged. - Otherwise, try to resolve ask context from the branch's linked gza task chain (`uv run gza show <TASK_ID>` / `uv run gza log <TASK_ID>` is preferred once you identify the task for this branch). - If linked ask content exists but is unavailable on this machine, pass an explicit unavailable-content marker section (for example, `## Original plan:` followed by `(plan task <TASK_ID> exists but content unavailable on this machine - flag as blocker)`). - If no retrievable plan or request exists for this branch, pass no ask section and let the reviewer state: `No plan or request provided.`

Then capture the committed diff: - If the caller already provided diff context, use that as-is and do not reconstruct it. Otherwise, collect the committed branch diff once in the parent session: ```bash git diff main...HEAD ``` Pass this diff to the subagent as `## Implementation diff context`.

### Step 4: Run the review

Spawn a **general-purpose Agent** subagent to perform the review. Give it this prompt (include the captured diff context):

---

You are reviewing a pull request. Your job is to read the project review guidelines, examine the diff, and produce a structured review.

**Step 1**: Read `REVIEW.md` from the project root for review guidelines and criteria.

**Step 2**: Start with a repo-rules/learnings pass: compare the diff and behavior against AGENTS.md, REVIEW.md, project docs, and `.gza/learnings.md`; call out violations or regressions explicitly. Keep this review stack-agnostic. If project verification instructions are missing, state that explicitly in assumptions/risks.

**Step 3**: The provided diff is authoritative - do not use git commands to reconstruct, re-derive, or expand it. You may read unchanged source files when surrounding context is needed to judge correctness.

**Step 3.5**: When you need to verify behavior that isn't visible in the diff (e.g., whether a CLI command exists, how a called function works, what a referenced method does), use the Read, Grep, or Glob tools to check the current codebase. Do not guess or assume — verify.

**Step 3.7**: If `## Review scope:` is present, grade ask-adherence against that section only and use any original-plan-context section only for boundaries/contracts. Otherwise, review the diff against the provided canonical ask context (`## Original plan:` or `## Original request:`). If ask content is marked unavailable, call that out as a blocker. If neither ask section is provided, state `No plan or request provided.`

**Step 4**: Write a structured review with these sections:

```markdown ## Summary

<Provide 3-5 bullets summarizing the review> <Then answer this checklist with exactly 6 bullets in `Yes/No - ...` form and one short evidence clause each:> <- Did I check the diff against AGENTS.md and `.gza/learnings.md` and flag any violations/regressions?> <- Did I check for silent broad-exception fallbacks that mask errors while changing user/agent-visible state?> <- Did I check for misleading output (contradictory UI/prompt/context signals)?> <- Was a `## Review scope:` section provided, and if so did I grade ask-adherence against that scope while treating sibling slices as non-blocking unless they break an explicit contract? Otherwise, was an `## Original plan:` or `## Original request:` section provided, and did I verify ask-adherence against it while calling out intentional deviations? If neither was provided, did I state "No plan or request provided."?> <- Did I require targeted regression tests that match each failure mode (not generic "add tests")?> <- If config, CLI, or operator-facing behavior changed, did I verify docs/help/release-note impact?>

## Blockers

<Use ### B1, ### B2, ... for blockers. If none, write "None."> <Each blocker should include Evidence:, Open-state citation:, Impact:, Required fix:, Required tests:> <Class-of-issue enumeration: when one blocker is an instance of a repeated code-surface pattern (lookup table, classifier, dispatcher, schema/field mapping, multi-field validator, or parallel per-field/per-type handling), audit for analogous gaps before writing the blocker. The audit boundary is the affected file plus any other files in the same module (the same depth-3 path under `src/`) that were touched by the diff, plus any obvious same-module sibling of the affected file.> <Report all still-open gaps for that same class in one blocker, with every affected `path:line` or `path:start-end` citation included in `Open-state citation:` regardless of file, and a `Required fix:` that closes the whole class.> <Do not create one blocker per field, branch, case, table row, or file unless the required fixes are materially different.> <Do not expand the audit beyond the same module, and do not expand isolated one-off defects - this rule applies only after you have found a repeated-pattern blocker shape.> <Reserve BLOCKER for: correctness defects, behavior regressions, repository/rules violations, missing observability for user/agent-visible fallbacks, and misleading output/contradictory signals.> <Treat unexplained deviations from the provided review scope, plan, or request as BLOCKER.> <If `## Review scope:` is present, grade ask-adherence against that section only. Use any original plan context section only to understand boundaries and integration contracts.> <Do not raise blockers solely because deferred sibling slices from the original plan are not implemented; only raise blockers when in-scope work is missing/broken or the diff violates an explicit integration contract described in the review scope or plan context.> <Treat silent broad-exception fallbacks as BLOCKER when they can alter user/agent-visible state without clear warning/error surfacing.> <Treat misleading output (UI/prompt/context contradictions) as BLOCKER when it can cause incorrect operator or agent decisions.> <If config/CLI/operator-facing behavior changed, missing or incorrect docs/help/release-note updates are BLOCKER when they can mislead operators.> <Use FOLLOWUP for actionable low-risk debt that should be tracked but should not block merge.> <For each blocker, give a clear closure condition so an improve task can resolve all blockers in one pass.> <For class-of-issue blockers, the closure condition must cover every enumerated instance across all cited paths, not just the first example.> <Every BLOCKER must be falsifiable: `Evidence:` and `Open-state citation:` must show the current still-open state, and `Required fix:` must describe the concrete change needed to close it.> <Do not write a `BLOCKER` unless you can cite the current code or current diff proving the issue is still open.> <Prior review text, improve lineage, or task history are not sufficient evidence for a blocker.> <Improve-lineage context may justify a narrow current-source anti-regression check for repeated blocker shapes the latest improve was expected to close, but it is only a pointer to inspect the current code/diff. It is not independent blocker evidence and must not substitute for current proof on this diff.> <Review current code, diff, and scope only.> <Do not run or evaluate `verify_command`; verification is handled elsewhere.> <Do not create blockers because verification failed, timed out, was skipped, or was unavailable.> <If code has a test-quality issue, cite the concrete code/test issue directly rather than runner verify status.> <Severity shorthand: `BLOCKER` means merge-blocking; `FOLLOWUP` means non-gating but task-worthy; `NIT` is omitted from canonical output.> <Do not add a per-finding `Severity:` line; the `## Blockers` and `## Follow-Ups` sections are the severity field.> <Derive the final verdict from the findings:> <cannot classify safely -> `NEEDS_DISCUSSION`> <Borderline cases must include a one-sentence rubric justification in `Impact:`, `Required fix:`, or `Recommended follow-up:`> <A broad exception that can mask visible state or swallow a user/agent-visible failure is a `BLOCKER`.> <An adjacent-path coverage sweep that would strengthen confidence without proving the current slice unsafe is a `FOLLOWUP`.> <Open-state citation must contain one or more current-source references in `path:line` or `path:start-end` form; backticked citations and comma-separated multiple citations are allowed.>

## Follow-Ups

<Use ### F1, ### F2, ... for non-blocking actionable follow-ups. If none, write "None."> <Each follow-up should include Evidence:, Impact:, Recommended follow-up:, Recommended tests:> <Do not include NIT findings in canonical output.>

## Questions / Assumptions

<Bullet list of open questions/assumptions. If none, write "None.">

## Verdict

<Brief justification> <Verdict is derived from the findings: no blockers/no follow-ups -> APPROVED; no blockers/at least one follow-up -> APPROVED_WITH_FOLLOWUPS; any blocker -> CHANGES_REQUESTED; cannot classify safely -> NEEDS_DISCUSSION.> Verdict: APPROVED|APPROVED_WITH_FOLLOWUPS|CHANGES_REQUESTED|NEEDS_DISCUSSION ```

Do not rename, omit, or reorder these sections.

If a PR number is provided, post the review as a PR comment: ```bash gh pr comment <PR_NUMBER> --body "<review content>" ```

Use a heredoc for the body to handle multi-line content properly.

If no PR number is provided, just output the review directly.

---

Pass the authoritative diff context (`## Implementation diff context`), the `## Review scope:` section when available, otherwise the canonical ask context section (exactly one of `## Original plan:` or `## Original request:` when available), and the PR number (if `--pr` was used and a