self-review-branch

name	self-review-branch
description	Reviews a full branch for correctness, idioms, comments, optimization balance, and testing — via parallel subagents per focus area. Use before requesting external review or merging.

Self-Review Branch

Use before requesting external review or merging. Works on the current branch (assumes a diff target, e.g. main or the fork's base branch).

Workflow

DIFF → EARLY EXIT → FAN OUT (subagents) → SYNTHESIZE → HANDOFF

0. Setup

Detect the base branch (merge target):

BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' \
  || git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||' \
  || echo "main")

If the diff is empty, exit early — nothing to review:

git diff "$BASE" --quiet && echo "No changes against $BASE — nothing to review." && exit 0

Get the diff once and make it available to all subagents. Detect relevant file extensions from the repo:

EXTS=$(git ls-files | awk -F. '{print $NF}' | sort -u | tr '\n' ' ')
rtk git diff "$BASE" -- *.$EXTS > /tmp/branch-diff.txt

rtk is optional token-saving shorthand — fall back to plain git diff if unavailable.

1. Fan-out: Subagents per Focus Area

Dispatch one subagent per focus area. Each subagent gets the diff file and a focused task. All run in parallel — they share no mutable state.

Agent task	What it checks
Correctness & idioms	Semantic correctness, modern idioms, no outdated patterns, no unsafe or footguns without justification. YAGNI: does every abstraction earn its keep?
Comments & doc	Comments explain why not what (that's the code's job). No LLM boilerplate ("Here we iterate..."), no obsolete comments, no exposition of alternatives — that belongs in the commit message or ticket. Every comment justifies its existence.
Optimization & pragmatism	Cheap optimizations present, expensive ones absent or justified. Complexity has a documented rationale. Code doesn't paint into a corner but also doesn't future-proof against ghosts. Readability > cleverness unless measured.
Testing strategy	Tests cover our logic, not frameworks/dependencies. No trivial-coverage tests (passthroughs, vendored error types). Lean toward unit tests with minimal mocks. If it's an integration or e2e test, the runtime dependency must earn its cost. No redundant or combinatorial test bloat — prefer one case with multiple asserts over 10 parameterized variants.

Example dispatch shape (adapt to available subagent tool):

subagent review_diff_correctness: "Review /tmp/branch-diff.txt for correctness and idioms..."
subagent review_diff_comments: "Review /tmp/branch-diff.txt for comment quality..."
subagent review_diff_optimization: "Review /tmp/branch-diff.txt for optimization balance..."
subagent review_diff_testing: "Review /tmp/branch-diff.txt for testing strategy..."

Collect all outputs when they complete.

2. Synthesis

Merge the findings into a ranked report:

CRITICAL (must fix before merge)
├─ correctness issues
└─ bugs or semantic errors

MAJOR (fix or document rationale)
├─ idiom or style violations
├─ unjustified abstractions (YAGNI)
├─ testing over- or under-scope
└─ missing cheap optimizations

MINOR (would improve but won't block)
├─ comment hygiene
├─ readability polish
└─ test organization

Cross-check findings against the diff:

• CRITICAL: verify the exact diff hunk — don't trust blindly.
• MAJOR: spot-check for plausibility.
• MINOR: pass through — even if wrong, they're low-impact.

Add a final section to the report with unresolved questions or ambiguities that need a human decision.

Principles for the Report

• One sentence per finding — the diff line reference carries the detail.
• Don't narrate the agent process — skip "Agent X found that...". Findings stand on their own.
• Explicit empty labels — use No issues found. instead of leaving a section blank.
• CRITICAL findings must include the diff hunk or file:line — no ambiguous "there's an issue somewhere".

Handoff

Present the full report to the user. If the report was saved to a file (e.g. /tmp/review-report.md), mention the path. No further action — the report replaces the manual self-review pass.

If all sections are clean, state clearly: No issues found — branch is ready for merge.