version: "1.0.1" 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.

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.

2b. Extension integration (if available)

If the submit_review and resolve_review_item tools are registered (self-review extension loaded), call submit_review with the structured findings after cross-checking. This renders a collapsible TUI card that tracks issue state across the session.

Call signature:

submit_review({
  issues: [
    {
      severity: "critical" | "major" | "minor",
      section: "correctness" | "comments" | "optimization" | "testing",
      file: "path/relative/to/repo/root",
      line?: 42,
      explanation: "One sentence describing the issue",
      suggestion?: "Brief fix suggestion",
    },
    // ...
  ],
  summary: "One-line summary of the review results",
})

The tool assigns each issue an id. As you fix issues (e.g. in a follow-up turn), call resolve_review_item({ issueId, note? }) to mark them resolved. The TUI card updates live — active issues in red/yellow, resolved ones dimmed with a checkmark.

Continue to section 3 for the handoff even when using the extension. The submit_review call replaces writing a plain report file, but still present the summary verbally.

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

Without the extension: 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.

With the extension (submit_review called): The TUI card is the persistent review. Verbally summarise the outcome — "2 critical, 3 major issues found" — and point the user at the card. No text report is needed.

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