Simplify Code

Review code for scope, reuse, quality, efficiency, clarity, and altitude issues, then fix them.

Step 1: Determine the Scope

Determine what to review:

• If a specific diff command was provided (e.g., git diff --cached), use that.
• If a file list or directory was provided, review those files directly (read the full files, not a diff).
• If neither was provided, determine the appropriate diff command (e.g., git diff, git diff --cached, git diff HEAD) based on the current git state. When the branch is an open pull request, resolve its base with gh pr view --json baseRefName --jq '.baseRefName', run git fetch origin <base-branch>, and diff against origin/<base-branch>...HEAD: a local branch of the same name can sit behind the remote, which puts the merge base before an already-merged pull request and pulls merged work into the scope. If there are no git changes, review the most recently modified files mentioned in the conversation.

State the resolved file list before launching the agents: add --name-only to a diff command, or list the files for a file or directory scope.

Step 2: Launch Six Review Agents in Parallel

Launch all six agents below with spawn_agent / wait_agent using inherited model defaults, issuing every call in one batch. Do not issue one and await its result before issuing the rest. Pass the scope from Step 1 to each agent. Every sub-agent's prompt must direct it to treat the shared working tree and its git index as read-only and to reach its findings by reading and reasoning; fixes happen in Step 3. Every sub-agent's prompt must also direct it to search the repository with a tool that skips gitignored files, such as git grep --untracked, and to open or search a gitignored path only when its prompt or a file its prompt directs it to read names it, or when a dependency's installed source is needed to verify a claim, never one holding local configuration or credentials. For an empirical check that verifies a finding, the agent works in a copy of the checkout created at a uniquely named path of its own under $TMPDIR. Refer to that copy by absolute path in every command and join chained steps with &&, so a failed step cannot leave the rest running in the shared checkout. Give that copy its own dependency install rather than reaching the shared tree's install by any route. When its own install is not possible, the check is left unrun and reported as such. Before reporting, the agent deletes that copy, its dependency install included, as a command of its own, and confirms the path no longer exists. A copy it could not delete is named by path in its report. HEAD stays where it is: read other refs with git show <ref>:<path> rather than git checkout or git switch. Direct each agent to write its full findings to a file named for its review followed by a random tag, under $TMPDIR, and to return that path with its report, so a compaction before Step 3 leaves the findings recoverable.

Confine the sub-agent's prompt to what to review, plus the conventions and factual properties that bear on it. Pass a property of the existing code as a fact the sub-agent weighs, such as "the retry loop guards a dependency known to fail intermittently". Leave out any statement that tells the sub-agent what verdict to reach about that property, such as "the duplication here is intentional for readability, judge against that", because it binds the sub-agent to accept the very property the review exists to assess.

Agent 1: Scope Review

Review the changes for code that should not exist:

1. Unrequested machinery: an abstraction with one implementation, a configuration point with one caller, a factory for one product, a wrapper that only delegates, scaffolding for an anticipated requirement. Recommend deletion rather than simplification.
2. Unreachable defensive code: a branch, guard, retry, or fallback for a state the surrounding code's own constraints rule out. When the callers cannot produce the input, the handling for it is dead on arrival.
3. Reinvented standard library or platform feature: hand-rolled logic the language's standard library or the target platform already ships, or a new dependency for what an already-installed one covers. Name the replacement.
4. Tests in the wrong shape: a production export, flag, or hook that exists only for a test to call, with no production caller and no public contract behind it. Recommend removing it and driving the test through a boundary production code already uses. For a test that repeats another test's contract, recommend folding its cases into that test. For an assertion on implementation (source text, import or export lists, private call shapes) that breaks under a behavior-preserving refactor, recommend rewriting it against observable behavior, unless it is the cheapest guard on a user-facing name, key, or path. Recommend these remedies rather than deleting a test outright.

Trace the callers of any code proposed for deletion and confirm nothing depends on the behavior being removed. Input validation at trust boundaries, error handling that prevents data loss, security controls, accessibility affordances, and anything the request explicitly asked for outrank the four checks above.

Agent 2: Code Reuse Review

For each change:

1. Search for existing utilities and helpers that could replace newly written code. Look for similar patterns elsewhere in the codebase — common locations are utility directories, shared modules, and files adjacent to the changed ones.
2. Flag any new function that duplicates existing functionality. Suggest the existing function to use instead.
3. Flag any inline logic that could use an existing utility — hand-rolled string manipulation, manual path handling, custom environment checks, and similar patterns are common candidates.

Agent 3: Code Quality Review

Review the same changes for hacky patterns:

1. Redundant state: state that duplicates existing state, cached values that could be derived, reactive subscriptions that could be direct calls
2. Parameter sprawl: adding new parameters to a function instead of generalizing or restructuring existing ones
3. Copy-paste with slight variation: near-duplicate code blocks that should be unified with a shared abstraction
4. Leaky abstractions: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
5. Stringly-typed code: using raw strings where constants, enums, or dedicated types already exist in the codebase
6. Unnecessary wrapper nesting: container elements or wrapper layers that add no structural or layout value

Agent 4: Efficiency Review

Review the same changes for efficiency:

1. Unnecessary work: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns
2. Algorithmic complexity: nested iterations, repeated linear searches replaceable by sets/maps, missing early exits
3. Missed concurrency: independent operations run sequentially when they could run in parallel
4. Hot-path bloat: new blocking work added to startup or per-request hot paths
5. Refresh cadence: work triggered more often than its result can change, such as refetching rarely changing data on every event, request, or timer tick
6. Unnecessary existence checks: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error
7. Memory: unbounded data structures, missing cleanup, resource leaks
8. Overly broad operations: reading entire files when only a portion is needed, loading all items when filtering for one

Agent 5: Clarity and Standards Review

Review the same changes for clarity, standards, and balance:

1. Project standards: coding conventions not followed — import sorting, naming conventions, component patterns, error handling patterns, module style. Beyond the auto-loaded instruction files, walk each directory that is an ancestor of a changed file, from the project root down, and read its AGENTS.override.md when one is present, otherwise its AGENTS.md — a directory's file governs only the files at or below it, and an override replaces that directory's AGENTS.md rather than adding to it. Flag a violation only when you can quote the exact rule and cite what breaks it: the offending line, or the location where a required element is missing. Name the file the rule came from
2. Unnecessary complexity: deep nesting, unclear variable or function names, nested conditionals 3+ levels deep (ternary chains like a ? x : b ? y : ..., nested if/else, or nested switch — flatten with early returns, guard clauses, a lookup table, or an if/else-if cascade), redundant boolean comparisons (e.g., x == true instead of x)
3. Unclear code: choose clarity over brevity — explicit code is better than overly compact code. Consolidate related logic, but not at the cost of readability
4. Over-simplification: overly clever solutions that are hard to understand, too many concerns combined into single functions or components, "fewer lines" prioritized over readability (dense one-liners), helpful abstractions removed that were aiding code organization
5. Dead weight: code no longer reached by any path, and variables, imports, or parameters the change orphaned
6. Unnecessary comments: comments explaining WHAT the code does, narrating the change, or referencing the task/caller — delete; keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds)

Agent 6: Altitude and Fix-Depth Review

Review the same changes for whether each is implemented at the right depth:

1. Special case on shared infrastructure: a narrow branch, flag, or conditional bolted onto a shared mechanism to handle one case, where generalizing the mechanism would remove the need for the special case. Name the generalization.
2. Shallow fix at the symptom: a change applied at one call site that the same shape will require again at the next similar site. Prefer addressing the shared root.
3. Wrong layer: logic placed in a caller, wrapper, or leaf when it belongs in the shared layer all paths flow through, or pushed into shared infrastructure when it is specific to one caller.

Step 3: Fix Issues

Wait for all six agents to complete. Aggregate their findings, reading each agent's findings file at the path it returned when its report is no longer in context. Delete any copy of the checkout an agent named as left behind, and name in the outcome report one that still remains. Then apply each fix directly, skipping only findings that are wrong. When a deletion recommendation and a refactor recommendation land on the same code, the deletion wins. When two agents agree the code should change but propose opposing remedies, prefer the remedy whose measurement reports a result concrete enough to re-run over one resting on reading; a bare claim to have measured ranks no higher than reading. Where neither reports one, apply the narrower remedy and state what the other proposed.

When a recommendation rests on a factual premise that reading the code in question cannot settle — what a platform API returns at runtime, or what a value measures once the system runs — establish that premise before implementing it rather than taking the agent's assertion, using the cheapest check that settles it: a targeted search or count over the source, the implementation behind the premise (the platform's or dependency's own source, or an open-source counterpart of the component checked against the shipped binary as installed on this machine where the two may differ), or a measurement from a surface already running in this session. When the premise is that a guard, check, or rule is redundant and the evidence is a comparison of runs with and without it, those runs must include the inputs it exists for, built on purpose where the condition it protects is hardest to meet. Runs that never reach those inputs leave the premise unsettled. When nothing available settles it, skip the finding and name the unverified premise as its reason. Reading alone cannot catch a false premise: the recommendation is coherent, the change lands cleanly, and the checks pass, leaving a change that cannot do what it was made to do.

A finding that would revise an interface or shape the user already approved is not a false positive. Output its technical detail as text, then use request_user_input to let the user decide, naming what the revision would change and what reversing the earlier decision costs. Place the genuinely best option first and append (Recommended) to its label, judging "best" on technical merit alone, independent of how closely it conforms to the earlier decision. When merit cannot settle it, say so instead of forcing a pick. Present the consultation option in place of Note for later, keeping the question at three options:

• Apply — make the change
• Keep the approved shape — leave as-is
• Get a second opinion — run the $consult-claude skill for the soundest shape on technical merit alone, independent of the earlier decision, carrying back what changing it costs. Then apply, keep, or note the finding with that answer in hand

A freeform answer asking to record the finding without changing the code runs the $note-improvement skill to capture it.

Once this round's fixes have landed, including any resolved at a gate, make one pass over the agents' findings: any whose verdict depended on code the fixes changed, moved, added, or deleted gets decided again against the current tree, keeping resolutions the user already chose.

Report the outcome as a table, one row per finding, keeping every cell to a single line:

Where Outcome is one of:

• Fixed — the fix was made
• Escalated — name the resolution the user chose: fixed, kept, or noted for later
• Skipped — name the reason

Where one criterion recurs across many sites, or many sites fall within one file, a single row may cover that group. Name the directory or file cluster it spans and the count. Every Skipped and Escalated finding keeps its own row with its reason, since those are the rows a reader acts on.

Keep the report to the table. Add prose only where an escalation's resolution changed what the other fixes look like. When the table would be empty, report one line stating the code was already clean instead.

Then call update_plan to mark this step completed and continue with the next step of the active workflow.