branch-review

name	branch-review
description	Multi-perspective code review for a branch before merging. Use when: reviewing a branch, preparing a PR, pre-merge review, auditing a feature branch, or when /branch-review is invoked. Spawns three constructive reviewer subagents (correctness, security, usability), then runs an adversarial gap analysis to find what they missed, and synthesizes all findings into a unified review report. All intermediate artifacts are persisted to .copilot/ so the process can be restarted from any step.
argument-hint	Branch name or merge target (e.g. 'main' or 'feature/foo -> main')

Branch Review

Perform a thorough multi-perspective code review of a branch before it is merged. Four independent reviewers examine the diff from competing viewpoints, and their findings are synthesized into one actionable report.

When to Use

• A feature branch is ready to merge and needs review
• Preparing a pull request
• Final quality gate before integration

Severity Levels

Findings use the same severity scale as the review-loop skill:

Severity	Meaning
critical	Correctness bug, security vulnerability, or data loss risk. Must fix.
high	Likely bug, race condition, or significant design flaw. Should fix.
medium	Code smell, unclear logic, missing edge case, or maintainability concern. Recommended fix.
low	Style nit, naming suggestion, minor improvement. Fix at discretion.

Persistence and Restart

Every intermediate artifact produced by this skill is written to disk under .copilot/reviews/<slug>/, where <slug> is a short kebab-case name derived from the branch under review (e.g. work-stealing-scheduler for a branch named feature/work-stealing-scheduler). This makes the process fully resumable: if any step fails, is interrupted, or produces an unsatisfactory result, you can re-run only the affected step using the on-disk artifacts from prior steps as input.

Directory layout

.copilot/reviews/<slug>/
├── 00-context.md                       # Step 2 output (shared context block)
├── 00-diff.patch                       # Step 1 raw diff
├── 00-changed-files.txt                # Step 1 file list
├── 10-review-correctness-lens.md       # Step 3 outputs (one per lens)
├── 10-review-security-lens.md
├── 10-review-usability-lens.md
├── 20-adversarial.md                   # Step 4 output
├── 30-synthesis.md                     # Step 5 output (deduped findings)
├── 40-report.md                        # Step 6 output (final unified report)
├── 50-fixes-iter1.md                   # Step 7 notes (per fix pass, optional)
├── 50-fixes-iter2.md
└── ...

Numeric prefixes preserve chronological order. The <slug> directory is created at step 1 and reused for the whole run. If the same branch is re-reviewed after fixes (step 8 loop-back), append a generation suffix (e.g. <slug>-r2/) rather than overwriting the prior review.

Restart contract

At the start of every step, check whether the corresponding output file already exists. If it does:

• Either reuse it (skip re-running the step), or
• Explicitly overwrite it (re-run the step from scratch).

Ask the user which to do if the choice is non-obvious. Never silently discard an existing artifact.

When the user asks to "restart from step N", load all artifacts numbered below N into context and re-run from step N onward.

Procedure

1. Gather the Diff

Determine the branch and its merge target (default: main) and derive the slug. Create .copilot/reviews/<slug>/ if it does not already exist.

Collect the diff using one of these methods, in order of preference:

1. git diff <merge-target>...<branch> -- . ':!*.lock' — full diff against the merge base. Save to 00-diff.patch.
2. get_changed_files — if the working tree has uncommitted changes that are part of the review.

Also collect the list of changed files and save to 00-changed-files.txt:

git diff --name-only <merge-target>...<branch>

Read the full current content of every changed file so reviewers have both the diff and the surrounding context.

2. Build the Context Block

Assemble a context block that every reviewer will receive and write it to .copilot/reviews/<slug>/00-context.md. This file must be self-contained: any subagent reading it should have everything it needs without further file lookups (beyond the diff/changed-files artifacts referenced by path). Include:

• Branch and merge target — branch name, base, commit range.
• Diff — the full unified diff (or a reference to 00-diff.patch if large, with key hunks inlined).
• Changed files — list from 00-changed-files.txt plus full current content of each modified file (or excerpts with line ranges if very large).
• Related tests — content of test files that cover the changed code, if identifiable.
• Project conventions — brief summary of relevant conventions from copilot-instructions.md (style, commenting, error handling, etc.).
• Prior audits — pointers to any prior review artifacts the user has flagged as already-covered (so reviewers know what is in/out of scope).

Keep the context block identical across all four reviewers to ensure a fair comparison.

3. Spawn Three Constructive Reviewer Lens Subagents

Launch three subagents in parallel, each using a named lens agent operating in review mode. Each receives the context block (by path) and must return findings in the severity-tagged format defined above.

#	Agent	Focus
1	correctness-lens	Logic errors, broken invariants, test gaps
2	security-lens	Injection, overflows, trust boundary violations
3	usability-lens	Naming, complexity, conventions, maintainability

Each subagent prompt must include:

• A directive to read .copilot/reviews/<slug>/00-context.md as its context

• An instruction to operate in review mode

• A directive to write the resulting findings to .copilot/reviews/<slug>/10-review-<lens>.md and return a brief confirmation plus the file path

• These instructions:

  Review the diff and changed files from the perspective described above. For each issue found, report it in this exact format:

  [SEVERITY] Short title

  • Location: file path and line number(s)
  • Problem: what is wrong and why it matters
  • Suggestion: concrete fix or remediation

  where SEVERITY is one of: critical, high, medium, low.

  If you find no issues from your perspective, state that explicitly. Do NOT fabricate issues. Only report genuine problems. Order findings by severity (critical first).

After the subagents return, verify all three 10-review-*.md files exist before continuing.

4. Adversarial Gap Analysis

After the three constructive reviewers return, spawn a fresh adversarial-lens subagent operating in review mode. This step runs sequentially — the adversarial reviewer receives the existing findings so it can focus on what the others missed.

The adversarial subagent prompt must include:

• A directive to read .copilot/reviews/<slug>/00-context.md and all three .copilot/reviews/<slug>/10-review-*.md files

• A directive to write its findings to .copilot/reviews/<slug>/20-adversarial.md

• These instructions:

  You are the adversarial reviewer. The findings in the 10-review-*.md files were produced by three constructive reviewers (correctness, security, usability). Your job is to find what they missed.

  Focus on:

  • Code sections covered by NO existing finding (overlooked areas)
  • Issue categories not represented in the existing findings
  • Cross-component interactions no single lens would catch
  • Unchecked assumptions and untested preconditions
  • Silent divergences with no test coverage
  • Fragile coupling where changing one thing silently breaks another

  For each issue found, report it in this exact format:

  [SEVERITY] Short title

  • Location: file path and line number(s)
  • Problem: what is wrong and why it matters
  • Suggestion: concrete fix or remediation

  where SEVERITY is one of: critical, high, medium, low.

  If the existing findings are comprehensive and you find no gaps, the file must contain exactly: "No additional issues found." Do NOT duplicate issues already reported. Only report NEW problems. Order findings by severity (critical first).

5. Deduplicate and Synthesize

Read all four reviewer outputs (10-review-*.md and 20-adversarial.md) and write a synthesized findings list to .copilot/reviews/<slug>/30-synthesis.md:

1. Merge duplicates. If multiple reviewers flag the same issue, keep the most detailed version and note which perspectives flagged it (higher confidence).
2. Resolve conflicts. If reviewers disagree (e.g., correctness wants inlining but maintainability wants extraction), note both sides and flag the trade-off for the user.
3. Verify critical/high findings. Before presenting critical or high findings, attempt to verify them — trace the code path, run relevant tests, or construct a minimal reproduction. Mark any finding you cannot verify as [unverified].

Each synthesized finding should retain its severity tag and a "Flagged by" attribution listing the contributing lenses.

6. Present the Report

Assemble the final report at .copilot/reviews/<slug>/40-report.md and present it to the user. The report must contain these sections, in order:

1. Summary — one-paragraph overview: number of findings by severity, overall assessment (e.g., "ready to merge with minor fixes" or "has blocking issues").

2. Positive observations — bullet list of things the reviewers agreed were done well (design choices, test quality, documentation, etc.). Keep it brief but genuine — this provides signal about what to preserve during remediation.

3. Findings — Critical / High — a Markdown table with columns: #, Severity, Title, Location, Flagged by, Status. Below the table, expand each row with the full problem description and suggested fix.

4. Findings — Medium — same table + expansion format.

5. Findings — Low — same table + expansion format.

6. Trade-offs — any unresolved disagreements between reviewers, with both sides stated.

7. Remediation plan — a numbered, ordered list of concrete steps to address the findings. Group related fixes into a single step where sensible. Each step should name the finding(s) it addresses and briefly describe what to do. Order by priority: blocking issues first, then medium, then low.

8. Action prompt — ask the user which findings to address. Options:

   • Fix all (follow the remediation plan)
   • Select specific findings by number
   • Dismiss specific findings
   • Ask for clarification

7. Apply Fixes

For each approved finding:

1. Implement the fix (or the user's alternative if provided).
2. Confirm each fix briefly as it is applied.
3. Run relevant tests after each fix to verify no regressions.

Record a short summary of the pass to .copilot/reviews/<slug>/50-fixes-iter<i>.md (incrementing i for each re-review pass) noting which findings were addressed, which were deferred, and any test results. This makes it possible to resume mid-remediation if the session is interrupted.

If a fix is ambiguous or touches architecture, ask the user for guidance and record the decision in the same 50-fixes-iter<i>.md file.

8. Check Exit or Re-review

After all approved fixes are applied:

All approved fixes have been applied and tests pass. Should I run another review pass on the updated diff, or is the branch ready to merge?

• If the user wants another pass → create a new generation directory (e.g. <slug>-r2/) and go to step 1 with the updated diff. The prior review's artifacts remain on disk for reference.
• If the user is satisfied → exit.

Guidelines

• Fresh context per pass. Each review pass spawns new subagents with no memory of prior passes, preventing anchoring bias.
• Do not auto-fix without approval. Always present findings and wait for the user to decide.
• Scope to the diff. Reviewers should focus on changed code. Pre-existing issues in unchanged code are out of scope unless the change makes them worse.
• Keep it bounded. If a re-review returns only low-severity findings, suggest exiting the loop.
• Test after fixing. Run the test suite (or at minimum the relevant subset) after applying fixes to catch regressions early.