Review Branch

Review Current Branch

Overview

Launch the branch-reviewer agent to perform a comprehensive review of all changes on the current git branch against a base branch (default main). Produces a report under .mz/reviews/.

The agent runs a two-wave analysis: Wave A is a 5-lens parallel fan-out (bugs, security, architecture, performance, maintainability) with full repo context; Wave B is a 3-researcher blinded adversarial pass (production reliability, security adversary, ops/SRE) dispatched in a separate message with only the raw diff. Wave B is always-on — there is no opt-out — and surfaces "Blind Spots" that Wave A missed because of confirmation bias. Wave B's blinded prompts are shared with audit depth:deep via plugins/mz-dev-pipe/skills/audit/references/blinded_lenses.md (single source of truth, no duplication).

When to Use

Triggers: "review branch", "review my changes", "check my branch", "what did I change", "branch review".

When NOT to use

• You want to review a GitHub PR — use github-review-pr instead.
• The current branch is main or master — nothing to diff.
• The user wants a scoped review of a single file — read and review it directly.

Arguments

• $ARGUMENTS[0] (optional) — Base branch to diff against. Defaults to main.

Core Process

Phase 0: Setup

1. task_name = _review_branch_ where ` is today's date (underscores) and is the current branch name (snake_case, max 20 chars); on same-day collision append v2, v3`.
2. Create .mz/task//.
3. Write state.md with schema_version: 2, Status: running, Phase: 0, Started: , BaseBranch: , Branch: .
4. Emit a visible setup block: task_name, base branch, current branch, report dir.

1. Validate branch state

Verify the current branch is not main or master:

git branch --show-current

If on main/master, inform the user there is nothing to review and update state.md to Status: aborted.

2. Launch the branch-reviewer agent

Dispatch Agent(branch-reviewer) in the foreground with the following prompt:

Review the current branch against .
Analyze all changes file-by-file for bugs, architecture issues, codebase consistency, missing functionality, and test coverage.
Run the always-on blind audit (Wave B) per Phase 3.6: dispatch the 3 blinded adversarial researchers in a SEPARATE assistant message after Phase 3.5 returns, reading the prompts from plugins/mz-dev-pipe/skills/audit/references/blinded_lenses.md, and cross-reference per Phase 3.7. The Blind Spots section is mandatory whenever wave_b_completed >= 1.
Use researcher agents for domain research if the implementation topic is complex.
Save the report to .mz/reviews/ using the naming convention: _review_branch_.md (append _v2, _v3 etc. if a report with the same base name already exists).

Update state.md to Phase: 2 before dispatch and Phase: 3 after the agent returns.

3. Report to user

Once the agent completes:

• Show the path to the generated report file
• Print a brief summary of the verdict and key findings (critical bugs, missing tests, etc.)
• If the agent found critical issues, highlight them explicitly

Techniques

Techniques: delegated to the branch-reviewer agent — see its agent definition for diff-walking, test-coverage, and architecture-consistency checks.

Common Rationalizations

N/A — collaboration/reference skill, not discipline.

Red Flags

• You reviewed diff output without checking out or reading the branch's actual file contents.
• You skipped running (or at least reading) the tests that the branch changed.
• The report references files or symbols that do not exist on the branch.

Verification

Output the report path (.mz/reviews/_review_branch_.md), confirm the file exists, and print the verdict line plus the top critical findings.

Error Handling

• Empty / invalid base-branch argument → escalate via AskUserQuestion; never guess.
• Missing tooling (git, gh) → detect before dispatch; if absent, escalate via AskUserQuestion with the exact missing command.
• Empty agent result (report file missing or empty) → retry the dispatch once with the same prompt; if it fails again, escalate via AskUserQuestion with the failure mode.
• Never guess — on any ambiguity (unknown base branch, detached HEAD, no diff) escalate via AskUserQuestion rather than proceed silently.

State Management

State persists to .mz/task//state.md with schema_version: 2 as its first line. This is a single-dispatch skill (setup → dispatch → report in one turn), so the phase_complete / what_remains progress-ledger fields are not required. On reading a schema_version: 1 or unversioned file, add schema_version: 2 and log the upgrade.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DoctorMozg
• Source: DoctorMozg/claude-pipelines
• License: MIT

Install and usage instructions live in the source repository linked above.