Arness Batch Simplify

Post-merge cross-feature quality pass that finds duplication and consolidation opportunities across independently implemented features. Uses the same 3-reviewer pattern as regular simplify but with cross-feature context so reviewers can identify duplicated utilities, inconsistent patterns, and shared logic that emerged from parallel development.

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

Pipeline position:

arn-code-batch-merge -> **arn-code-batch-simplify** -> (optional: review-implementation -> document-project -> ship)

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.

Workflow

Step 0: Ensure Configuration

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.md and follow its instructions. Extract from ## Arness:

• Plans directory (default: .arness/plans)
• Code patterns path (default: .arness)
• Template path (default: .arness/templates)

Hold these values for the remainder of the workflow.

Step 1: Load Pattern Documentation

Load pattern documentation from the code patterns directory:

1. code-patterns.md (required)
2. testing-patterns.md (required)
3. architecture.md (required)
4. ui-patterns.md (if it exists)
5. security-patterns.md (if it exists)

If any required pattern doc 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 all loaded pattern documentation for use throughout the workflow.

Step 2: Collect Batch Scope

Scan the plans directory for CHANGE_RECORD.json files across all feature subdirectories:

1. For each CHANGE_RECORD.json found, check:

   • commitHash is populated (feature was committed)
   • The feature has been merged — check gh pr view if nextSteps contains a PR URL, or verify the feature branch was merged into main via git branch --merged main

2. For each merged feature's CHANGE_RECORD.json, collect:

   • filesModified — files that were changed
   • filesCreated — files that were added
   • projectName — the feature name
   • ceremonyTier — the ceremony level used
   • changePath — path to the feature's plan directory

3. Build the unified file list: union of all filesModified + filesCreated across all merged features, deduplicated. Exclude files that no longer exist on disk (verify with test -f).

4. Build the overlap map: for each file that appears in 2+ features, record which features touch it. These are priority review targets.

Exit conditions:

• If zero merged features found: inform the user "No recently merged batch features found. Run /arn-code-batch-merge first." and exit.
• If the unified file list is empty: inform the user "No files to review — all features were merged but produced no file changes." and exit.

Step 3: Present Scope

Display the batch scope summary:

Cross-Feature Simplification Scope:

| Feature | Tier | Files |
|---------|------|-------|
| F-003 Auth | thorough | 12 |
| F-005 API | standard | 5 |
| F-008 Settings | thorough | 8 |

Total unique files: [N] (across [M] features)
Files touched by 2+ features: [K] (priority review)

Ask (using AskUserQuestion): "Proceed with cross-feature simplification?"

1. "Yes" (Recommended)
2. "Skip" — exit

If the user selects "Skip", exit gracefully.

Step 4: Dispatch Parallel Reviewers

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-batch-simplify/references/cross-feature-prompts.md for the extended reviewer prompt templates.

Build the {cross_feature_context} block from the data collected in Step 2 — listing each feature's name, its files, and its change record path.

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. Note: arn-code-simplify-reviewer is shared with arn-code-simplify since both skills perform the same conceptual review work.

1. Code Reuse Reviewer — fill the cross-feature-prompts.md template with the file list, pattern documentation, and cross-feature context. Instruct the agent to focus on duplicated logic, missed utilities, and copy-paste patterns, with special attention to utilities created independently by different features.

2. Code Quality Reviewer — fill the template. Instruct the agent to focus on unnecessary complexity, dead code, unclear naming, and overly nested logic, with special attention to inconsistent approaches to the same pattern across features.

3. Efficiency Reviewer — fill the template. Instruct the agent to focus on N+1 patterns, redundant computations, suboptimal data structures, and unnecessary allocations, with special attention to redundant API clients, validators, or error handlers across features.

Each agent receives:

• {files_to_review}: the unified file list
• {code_patterns}: content of code-patterns.md
• {testing_patterns}: content of testing-patterns.md
• {architecture}: content of architecture.md
• {cross_feature_context}: the cross-feature context block

Reviewer agent tools: Each reviewer agent should be granted only read-only tools: Read, Grep, Glob.

30-file cap with batching: If more than 30 files in the unified list, batch by grouping related files. Prioritize files touched by 2+ features in the first batch. Dispatch the three reviewers for each batch sequentially (batch 1 complete, then batch 2, etc.).

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 three reviewers fail, inform the user that cross-feature simplification analysis could not be completed. Suggest retrying.

Step 5: Merge and Present Findings

1. Collect findings from all three reviewers.

2. 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.

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

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

5. Tag each finding based on its affectedFeatures array:

   • Cross-feature finding: affectedFeatures contains 2+ features
   • Single-feature finding: affectedFeatures contains exactly 1 feature

6. Collect all patternsPreserved entries from all reviewers.

7. Present findings grouped by cross-feature vs single-feature:

   Cross-Feature Findings (spanning 2+ features):

   • SIM-001 [reuse/medium]: "validateApiResponse() duplicated in auth and API layers" Affected: F-003 (src/lib/auth-api.ts), F-005 (src/lib/api-client.ts) Suggested: Extract to shared utility
   • SIM-002 [quality/medium]: "Inconsistent error handling — F-003 uses try/catch, F-005 uses .catch()" Affected: F-003 (src/lib/auth-api.ts), F-005 (src/routes/api.ts) Suggested: Standardize on try/catch per code-patterns.md

   Single-Feature Findings:

   • SIM-003 [quality/low]: "Unused import in settings controller" Affected: F-008 (src/controllers/settings.ts)
   • SIM-004 [efficiency/small]: "Redundant database query in auth middleware" Af