name

review-worktree

description

Exhaustive read-only code review of staged, unstaged, and untracked Git worktree changes before commit. Use when the user asks to review uncommitted changes, review the whole worktree, audit local diffs, inspect staged/unstaged/untracked files, or run a thorough parallel subagent code-review workflow focused on correctness, regressions, security/privacy, data integrity, API compatibility, tests, and integration risk.

Review Worktree

Run a comprehensive read-only review of every uncommitted change in the current Git repository. Account for staged, unstaged, and untracked non-ignored files before giving a verdict.

Non-Negotiables

• Stay read-only: do not edit, format, stage, unstage, revert, commit, install dependencies, or mutate source files.
• Treat untracked non-ignored files as first-class review targets.
• Do not ignore generated-looking files unless you verify they are generated and irrelevant.
• Prefer repository evidence over generic best practices.
• Report real risks only. Do not pad with style nits or speculative concerns.
• If evidence is missing, say exactly what is missing and how to verify it.

Step 1: Build Complete Change Inventory

Start at the Git root. Read nearby project instructions first when present, especially AGENTS.md, CLAUDE.md, CONTRIBUTING.md, or subsystem docs.

Collect inventory with safe commands:

git rev-parse --show-toplevel
git status --short --branch --untracked-files=all
git diff --stat
git diff --cached --stat
git diff --name-status
git diff --cached --name-status
git ls-files --others --exclude-standard

When useful, run the bundled helper:

python3 /path/to/review-worktree/scripts/worktree_inventory.py

Then inspect actual diffs and untracked file contents:

git diff --cached -- <paths>
git diff -- <paths>
sed -n '1,220p' <untracked-file>

Use rg/rg --files for surrounding context, callers, imports, routes, config references, tests, fixtures, migrations, and docs affected by the change.

Step 2: Cluster Review Areas

Group changed files into logical areas by feature, package, subsystem, runtime path, or risk surface. Make every changed file belong to exactly one primary area, even if it also has cross-cutting risks.

For each area, capture:

1. Changed files
2. Behavioral intent inferred from the diff
3. Main runtime path or owner
4. Likely risk categories
5. Tests or validation already present

Step 3: Parallel Review Gate

Launch subagents only when the user explicitly invoked this skill, asked for subagents, asked for delegation, or asked for a parallel review. If subagents are unavailable or not authorized, run the same perspectives locally and state that in the final review.

Use up to 6 read-only subagents. Prefer one subagent per logical area when changes touch multiple subsystems. If there are fewer areas than perspectives, assign specialist perspectives to remaining agents.

Required perspectives to cover across the first wave:

• correctness and behavior regressions
• security, privacy, auth, permissions, secrets, injection, data exposure
• data model, migrations, persistence, caching, concurrency, transactions
• API contracts, integrations, backwards compatibility, error handling
• tests, validation gaps, flaky behavior, missing edge cases
• maintainability, architecture fit, duplication, dead code, observability

Subagent prompt shape:

Read-only review. Do not edit, format, stage, unstage, revert, commit, install dependencies, or mutate files.

Review this assigned area of the uncommitted worktree:
- Repository: <git root>
- Area: <name>
- Changed files: <files>
- Relevant inventory: <brief status/diff summary>
- Perspective: <area or specialist perspective>

Inspect the changed diff, surrounding code, call sites, tests, config, and docs needed to verify behavior. Treat staged, unstaged, and untracked files as in scope when assigned.

Return only distilled findings with evidence. For each finding include severity P0-P3, file/line, what is wrong, why it matters, concrete code/diff evidence, minimal suggested fix, test/validation, and confidence. If no material issue is found, state the area checked and residual risk.

Do not duplicate work between agents. Continue local non-overlapping inspection while agents run. Wait for all agents before synthesis. Run a second targeted pass only if first-wave results reveal unresolved cross-cutting risk.

Step 4: Review Method

For every changed file:

1. Read the diff and enough surrounding code to understand intent.
2. Search for callers, imports, routes, public APIs, config references, tests, fixtures, migrations, and docs.
3. Compare changed behavior against existing local conventions.
4. Red-team failure modes: bad input, missing permissions, stale caches, concurrency, partial failure, old clients, deployment drift, and unusual runtime state.
5. Check tests for changed behavior and failure modes. Do not assume passing tests prove safety.

Safe validation commands may be run only if they are standard for the repo and do not update snapshots, generated files, lockfiles, databases, or external services. If a command may mutate state, do not run it; report it as recommended instead.

Severity

• P0: must fix before commit; likely build break, data loss, security issue, production outage, irreversible migration problem, or severe regression.
• P1: should fix before commit; likely correctness bug, broken user flow, unsafe edge case, missing permission check, bad API contract, or important test gap.
• P2: worth fixing; moderate bug risk, confusing behavior, maintainability risk, incomplete validation, weak observability, or brittle test coverage.
• P3: optional; minor improvement only if it materially reduces future risk.

Verdict rules:

• BLOCK COMMIT: any P0, or multiple P1s that make the change unsafe as a unit.
• FIX FIRST: one or more P1s or important unresolved evidence gaps.
• OK TO COMMIT WITH NOTES: no P0/P1; only P2/P3 notes or validation caveats.

Final Output

Start with exactly one verdict: BLOCK COMMIT, FIX FIRST, or OK TO COMMIT WITH NOTES.

Then provide:

1. Top findings, sorted by severity and confidence. For each finding include severity, file reference with line number when possible, what is wrong, why it matters, concrete evidence, minimal suggested fix, test or validation that would catch it, and which subagent/perspective found it.
2. Coverage matrix with changed file or area, reviewing agent/perspective, risk level, tests found or missing, and validation run or recommended.
3. Cross-cutting risks for security/privacy, data integrity/migrations, API compatibility, concurrency/caching, deployment/config, and observability/errors.
4. Validation with commands run, results, commands not run and why, and the smallest useful validation before committing.
5. False-positive discipline: areas checked where no material issue was found.

Stop only after every staged, unstaged, and untracked non-ignored change has been accounted for.