| 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:
git diff <merge-target>...<branch> -- . ':!*.lock' — full diff against
the merge base. Save to 00-diff.patch.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:
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:
- Merge duplicates. If multiple reviewers flag the same issue, keep the
most detailed version and note which perspectives flagged it (higher
confidence).
- 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.
- 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:
-
Summary — one-paragraph overview: number of findings by severity, overall
assessment (e.g., "ready to merge with minor fixes" or "has blocking issues").
-
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.
-
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.
-
Findings — Medium — same table + expansion format.
-
Findings — Low — same table + expansion format.
-
Trade-offs — any unresolved disagreements between reviewers, with both
sides stated.
-
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.
-
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:
- Implement the fix (or the user's alternative if provided).
- Confirm each fix briefly as it is applied.
- 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.
