Neura Market Parallel Code Review and Cleanup Tool

Purpose

This tool performs a parallel code review and cleanup pass on recent changes. Its focus is on removing duplication, reducing complexity, cutting waste, and deepening band-aid fixes. It does not hunt for correctness bugs, though it may report them separately if encountered. The tool is designed to be invoked on demand, not automatically after every edit, because running it consumes the tokens of four subagents.

When to Use

Invoke this tool when you want to simplify or clean up your recent work. The following user phrases trigger it:

"simplify", "simplify my changes", "simplify these changes"
"review my code", "review my recent changes", "clean up my changes"
"/simplify" (a Claude Code habit)

You can also add optional modifiers to control the behavior:

focus: Restricts the review to one category or weights the aggregation toward it.
dry run: Runs all four reviewers, presents findings, and applies nothing. Asks before applying.
scope: Narrows the diff source to the last commit, staged changes, a specific file, or a branch.

Capabilities

The tool captures a git diff from the working tree, staged changes, the last commit, a branch, or specific files. If no git diff is available, it falls back to session files. If the diff exceeds 2000 lines, it warns and offers to scope down before proceeding.

It launches four parallel reviewer subagents (reuse, quality, efficiency, altitude) via delegate_task batch mode. If delegation is unavailable, it performs all four reviews sequentially inline and notes this in the summary. Each reviewer receives the full diff, the repository path, and tools (terminal, file, search). Reviewers search the codebase, use git blame (Chesterton's Fence), and report structured findings with cost, confidence, and risk tier (SAFE, CAREFUL, RISKY).

The tool aggregates findings: it deduplicates, discards false positives, and resolves conflicts using the priority order: correctness > focus > readability > micro-perf. It applies fixes in risk-tier order: SAFE auto-applies, CAREFUL applies with test verification per file, and RISKY flags for human review. It verifies with targeted tests and a linter or type checker, reverting any breaking fix. Finally, it summarizes applied fixes grouped by reviewer category and risk tier, plus skipped findings with reasons.

Optional modifiers are honored: focus runs only that reviewer or weights aggregation toward it, dry run presents only and applies nothing, and scope narrows the diff source.

Parameters

focus

Meaning: Restricts the review to one category (reuse, quality/simplification, efficiency, altitude) or weights aggregation toward it.
Required: Optional

dry run

Meaning: Runs all four reviewers, presents findings, and applies nothing. Asks before applying.
Required: Optional

scope

Meaning: Narrows the diff source to the last commit, staged changes, a specific file, or a branch.
Required: Optional

Procedure: Parallel Review and Cleanup

Phase 1: Identify Changes

Run git diff (default) to capture uncommitted working-tree changes on tracked files. If that is empty, run git diff HEAD to include staged changes. If the user provides a scope modifier, use the appropriate variant:

# 1. Default: uncommitted working-tree changes (tracked files)
git diff

# 2. If that's empty, include staged changes
git diff HEAD

# 3. Scoped variants the user may request:
git diff --staged                 # "staged changes"
git diff HEAD~1                    # "the last commit"
git diff main...HEAD              # "this branch" / "my PR"
git diff -- src/foo.py            # specific file(s)

If no git changes are found, fall back to session files. If nothing is found at all, stop and report. If the diff exceeds 2000 lines, warn the user and offer to scope down before continuing. If the user declines to scope down, the tool may truncate the diff or exceed the token budget, which is a known failure mode.

Phase 2: Launch Four Reviewers in Parallel

Launch four reviewers in parallel via delegate_task batch mode. The tool uses delegate_task with tasks to launch the four reviewers in batch mode. The delegation.max_concurrent_children setting controls how many can run at once. Each reviewer receives the full diff, the repository path, and tools (terminal, file, search). Each reviewer has access to read_file, search_files, and git for git blame. Each reviewer searches the codebase, applies git blame before flagging any removal, and reports findings as structured output in this exact format:

file:line → problem → cost (what's duplicated/wasted/harder to maintain) → suggested fix | confidence: high/medium/low | risk: SAFE/CAREFUL/RISKY

Reviewers skip nits and style-only churn. Their goals are:

Reviewer 1 (Code Reuse): Flag duplication of existing utilities. Look for patterns like // increment counter where count++ already exists, or as any casts that bypass type safety.
Reviewer 2 (Code Quality): Flag redundant state, parameter sprawl, copy-paste-variation, leaky abstractions, stringly-typed code (e.g., if (caller == X)), deep nesting, and AI slop.
Reviewer 3 (Efficiency): Flag unnecessary work, missed concurrency, hot-path bloat, TOCTOU, memory issues, overly broad reads, and silent failures (e.g., except: pass, .catch(() => {})).
Reviewer 4 (Altitude): Flag band-aids on shared infrastructure instead of fixing the root cause. Check git blame for deliberate boundaries. Mark findings with confidence: low if the intent is unclear.

If delegation is unavailable, perform all four reviews sequentially inline and state this in the summary. The tool is designed to avoid subagent-driven-development where reviewers make changes without understanding the full context.

Phase 3: Aggregate and Apply

Wait for all reviewers to finish. Merge findings, deduplicate overlapping ones, and discard false positives silently. Resolve conflicts using the priority order: correctness > user's stated focus > readability/reuse > micro-perf.

Apply fixes in risk-tier order:

SAFE: Auto-apply, then run tests.
CAREFUL: Apply with verification per file. Run tests after each file. Revert any fix that breaks a test.
RISKY: Flag for human review. Do not auto-apply.

If dry run is set, present all tiers and apply nothing. Verify all applied changes with targeted tests and a linter or type checker. Revert any fix that breaks a test. Summarize changes grouped by reviewer category and risk tier, plus skipped findings with reasons. If the review ran inline (no delegation), state that.

Constraints and Caveats

Do not auto-run after every edit or tack onto unrelated tasks. This costs four subagents' tokens.
Do not fan out wider than 4 reviewers.
Give the whole diff to each reviewer, not fragments.
Reviewers must search the codebase for evidence, not guess. Require file:line evidence.
Apply does not mean rewrite. Keep edits scoped to the diff plus minimal surrounding change. Altitude findings are flagged, not applied unilaterally.
Do not drift into bug-hunting. Report genuine bugs separately, not as cleanup fixes.
Respect project conventions (AGENTS.md, CLAUDE.md, HERMES.md, linter config).
Large diffs (over 2000 lines) blow context. Scope down before delegating.
Do not over-trust dead code tools like knip, ts-prune, or depcheck. Grep for the symbol before removing.
Do not rename without checking public contracts (export names, API routes, DB columns, config keys). Tag as RISKY and never auto-rename.
Do not remove "unnecessary" error handling (empty catch, ignored error) without human decision. Flag it.
Not every special case is a band-aid. Check git blame and comments before flagging altitude violations. Mark confidence as confidence: low if unclear.
If delegation is unavailable, perform all four reviews sequentially inline and state it in the summary.

Failure Modes

No git repo or no changes found: Stop and report.
Diff too large and user declines to scope down: May truncate or exceed token budget.
Delegation unavailable: Fall back to inline sequential review (noted in summary).
Fix breaks tests: Revert that fix and report.
Conflicting reviewer suggestions: Resolve using the priority order. If both are defensible, pick the less code change and note the alternative.

Prerequisites

Access to git for diff and blame.
Ability to call delegate_task in batch mode (or fallback to inline).
Toolsets: terminal, file, search for each reviewer.
Project's test runner and linter/type checker available for verification.

Examples

User says "simplify focus on efficiency": Run only the efficiency reviewer or weight aggregation toward it.
User says "simplify but don't change anything": Dry run. Present findings, apply nothing, ask before applying.
User says "simplify the last commit": Scope. Use git diff HEAD~1.
User says "simplify staged": Scope. Use git diff --staged.
User says "simplify src/foo.py": Scope. Use git diff -- src/foo.py.

Additional Notes on Behavior

The tool uses delegate_task with tasks to launch the four reviewers in batch mode. The delegation.max_concurrent_children setting controls how many can run at once. Each reviewer has access to read_file, search_files, and git for git blame. The tool is designed to avoid subagent-driven-development where reviewers make changes without understanding the full context.

When a reviewer finds a pattern like // increment counter where count++ would suffice, it flags it. Similarly, as any casts, except: pass, and .catch(() => {}) are flagged as quality or efficiency issues. Stringly-typed code like if (caller == X) is flagged for quality. The tool uses knip, ts-prune, and depcheck with caution, always grepping for the symbol before suggesting removal.

Reviewers must search the codebase for evidence, not guess. They require file:line evidence for every finding. The tool does not auto-run after every edit or tack onto unrelated tasks, as this costs four subagents' tokens. It does not fan out wider than 4 reviewers. It gives the whole diff to each reviewer, not fragments.

Apply does not mean rewrite. Edits are kept scoped to the diff plus minimal surrounding change. Altitude findings are flagged, not applied unilaterally. The tool does not drift into bug-hunting. Genuine bugs are reported separately, not as cleanup fixes. Project conventions (AGENTS.md, CLAUDE.md, HERMES.md, linter config) are respected.

Large diffs (over 2000 lines) blow context, so the tool scopes down before delegating. The tool does not over-trust dead code tools like knip, ts-prune, or depcheck. It greps for the symbol before removing. It does not rename without checking public contracts (export names, API routes, DB columns, config keys). Such changes are tagged as RISKY and never auto-renamed. The tool does not remove "unnecessary" error handling (empty catch, ignored error) without human decision. It flags it instead.

Not every special case is a band-aid. The tool checks git blame and comments before flagging altitude violations. Confidence is marked as confidence: low if unclear. If delegation is unavailable, the tool performs all four reviews sequentially inline and states it in the summary.

When conflicting reviewer suggestions arise, the tool resolves them using the priority order: correctness > user's stated focus > readability/reuse > micro-perf. If both are defensible, it picks the less code change and notes the alternative. Fixes that break tests are reverted and reported. The tool summarizes applied fixes grouped by reviewer category and risk tier, plus skipped findings with reasons. If the review ran inline (no delegation), that is stated in the summary.

Simplify Code: Parallel 4-Agent Cleanup for Recent Changes