arn-code-simplify

Arness Simplify

Analyze recently implemented code for reuse opportunities, quality issues, and efficiency problems. Dispatches three parallel reviewers (code reuse, code quality, efficiency), merges findings, applies user-approved fixes with test verification, and generates a structured simplification report.

This is a post-execution quality improvement skill. It runs after implementation is complete (after execute-plan, swift, or bug-spec) and before review-implementation.

This is an execution skill. It runs in normal conversation (NOT plan mode).

Prerequisites

If no ## Arness section exists in the project's CLAUDE.md, inform the user: "Arness is not configured for this project yet. Run /arn-implementing to get started — it will set everything up automatically." Do not proceed without it.

Pipeline Position

execute --> **arn-code-simplify** --> review-implementation --> document-project --> ship

Arness-simplify is an optional step between execution and review. It can be triggered:

• By arn-implementing as Gate G3 (opt-in)
• By the user directly after any execution completes
• As a next-step offer from arn-code-execute-plan, arn-code-execute-task, or arn-code-swift

Workflow

Step 1: Load Configuration

1. Read the project's CLAUDE.md and extract the ## Arness section to find:
2. Plans directory
3. Code patterns path
4. Template path
5. Template version and Template updates preference (if present)

1. If the ## Arness section is missing, inform the user: "Arness is not configured for this project yet. Run /arn-implementing to get started — it will set everything up automatically." Do not proceed.

1. Load pattern documentation from the code patterns directory:
2. code-patterns.md (required)
3. testing-patterns.md (required)
4. architecture.md (required)
5. ui-patterns.md (if it exists)
6. security-patterns.md (if it exists)

1. If pattern documentation is missing, invoke the arn-code-codebase-analyzer agent to generate fresh analysis. If the analyzer is unavailable, suggest running /arn-implementing to get started.

Hold this context for use throughout the workflow.

Step 2: Resolve Scope

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-simplify/references/scope-detection.md for the full scope detection algorithm.

1. If invoked with an explicit scope (e.g., from arn-code-execute-task passing a report path): use the provided scope directly.

1. If invoked without explicit scope (standalone or wizard gate): auto-detect scope using the priority order defined in scope-detection.md (pipeline > swift > bugfix).

1. Build the file list from the scope's artifacts. Apply the 30-file cap. If more than 30 files, split into batches as described in scope-detection.md.

1. Confirm scope and file list with the user before proceeding.

Step 3: Dispatch Parallel Reviewers

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-simplify/references/review-prompts.md for the three reviewer prompt templates and output format.

Dispatch three Agent tool calls in a single message so they run in parallel. Each call passes the model from .arness/agent-models/code.md (look up arn-code-simplify-reviewer) as the model parameter (see ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.md "Dispatch convention" for fallback behavior). The three reviewers share the same synthetic name — apply the multi-agent rule by passing the looked-up value to each call independently.

1. Code Reuse Reviewer -- fill the review-prompts.md template with the file list and pattern documentation. Instruct the agent to focus on duplicated logic, missed utilities, and copy-paste patterns.

1. Code Quality Reviewer -- fill the template. Instruct the agent to focus on unnecessary complexity, dead code, unclear naming, and overly nested logic.

1. Efficiency Reviewer -- fill the template. Instruct the agent to focus on N+1 patterns, redundant computations, suboptimal data structures, and unnecessary allocations.

Each agent receives:

• {files_to_review}: the file list for the current batch
• {code_patterns}: content of code-patterns.md
• {testing_patterns}: content of testing-patterns.md
• {architecture}: content of architecture.md

Partial failure handling: If one reviewer fails, merge findings from the other two. Record the failure in reviewerStatus with status "failed". Add a warning: "The [axis] reviewer failed. Findings may be incomplete for that axis."

If all files fit in a single batch, dispatch once. If batched, dispatch the three reviewers for each batch sequentially (batch 1 complete, then batch 2, etc.).

Step 4: Merge and Present Findings

1. Collect findings from all three reviewers.

1. Deduplicate: if two reviewers flagged the same code location for overlapping reasons, merge into a single finding. Prefer the higher severity and note both axes.

1. Assign sequential IDs: SIM-001, SIM-002, etc.

1. Automatically defer findings with effort "large": set status to "deferred" and add a note suggesting a refactoring spec for strategic improvements.

1. Collect all patternsPreserved entries from all reviewers.

1. Present findings to the user grouped by axis:

Code Reuse Findings:

• SIM-001 [medium/small]: Title -- description
• SIM-002 [high/trivial]: Title -- description

Code Quality Findings:

• SIM-003 [low/small]: Title -- description

Efficiency Findings:

• SIM-004 [medium/medium]: Title -- description

Deferred (large effort):

• SIM-005 [high/large]: Title -- consider a refactoring spec

Patterns Preserved: N decisions respected documented patterns.

Step 5: User Approval

Auto-all mode check: Before prompting, check the resolved value of pipeline.simplification from the two-tier preference lookup. If the value is auto-all:

• Auto-approve all non-deferred findings (mark as "approved")
• Skip the user prompt entirely
• Log: "Auto-all mode: approving [N] findings ([M] deferred)."
• Proceed directly to Step 6

This mode is used by batch-implement workers that cannot prompt the user. It follows the same logic as the user selecting "all" but without requiring AskUserQuestion.

Interactive mode (all other preference values):

Ask the user which findings to apply:

"Which findings should I apply? Enter finding IDs (e.g., SIM-001, SIM-003), 'all' to apply everything except deferred, or 'none' to skip."

Process the user's selection:

• Specific IDs: mark those as "approved", rest as "rejected"
• "all": mark all non-deferred findings as "approved"
• "none": mark all as "rejected", skip to Step 7

The user may also change individual finding statuses (e.g., "approve SIM-001 but defer SIM-003").

Step 6: Apply Approved Simplifications

The orchestrator pre-sorts the approved findings by dependency order (if finding B depends on finding A's changes, A comes first), then dispatches a single anonymous Agent call to perform the apply work. The model is configurable via the agent-models config.

Dispatch the applier as an anonymous Agent tool call, passing the model from .arness/agent-models/code.md (look up arn-code-simplify-applier) as the model parameter (see ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.md "Dispatch convention" for fallback behavior). Do NOT add any tool restriction — the applier inherits Edit, Write, Bash, Read, Grep, Glob from the orchestrator's toolbelt by default, and needs all of them.

Applier prompt contents:

• The pre-sorted list of approved findings (each with id, title, description, suggestedFix, filesAffected, and axis)
• The targeted-test command (from the scope's context or testing-patterns.md)
• Paths to relevant pattern docs (code-patterns.md, testing-patterns.md) so the applier can reference them when self-healing
• The exact