Parallel Codebase Simplification

Execute code simplification across a large codebase by automatically segmenting it into logical chunks and processing them concurrently with proper dependency ordering.

Quick Reference

Command	Description
/simplify-parallel	Analyze and simplify entire codebase
/simplify-parallel --dry-run	Analyze only, show plan without executing
/simplify-parallel --focus=lib	Limit to specific area
/simplify-parallel --segments=4	Set max parallel agents

Usage

/simplify-parallel [options]

Options

Option	Default	Description
--dry-run	false	Analyze only, don't modify files
--focus=AREA	all	Limit to area: api, lib, components, hooks, pages
--segments=N	3	Maximum parallel agents
--max-files=N	20	Max files per segment
--verbose	false	Show detailed progress

---

CRITICAL: What NOT to Change

This section is the #1 priority. Violations here negate the value of simplification. Workers MUST read this section before making any changes.

Never Remove Comments

Workers must NEVER remove any of the following:

DO NOT REMOVE	Example
Section separators	// ===== Types =====, // ===== Helpers =====, // ===== Component =====
JSDoc/TSDoc docstrings	/** Computes the current project step... */
File header comments	Block comments at top of files explaining purpose
"Why" comments	// Only truly block when mutation is actively in flight
Business logic comments	// While any query is loading, trust the server-provided step
Error handling rationale	// Check if error is retryable based on status code
TODO/FIXME/NOTE comments	These track technical debt
Biome ignore directives	// biome-ignore lint/style/useNamingConvention: reason
Re-export annotations	// Re-export types for convenience, // Production hooks use tRPC
Phase/section markers	// Phase 14.16, // Step 1: Fetch and validate

Never Remove These Code Patterns

DO NOT REMOVE	Reason
Explicit intent patterns	if (x) { return x; } return undefined; shows intent vs implicit return x;
Named intermediate variables	const isMutationPending = mutation.isPending is clearer than inlining
Error handling structure	Don't collapse try/catch blocks that handle different error types
Manual test output	console.log in *.integration.ts or manual.*.ts files is intentional

The Rule

If removing a comment or simplification changes the clarity of intent, don't do it.

Simplification means removing unnecessary complexity, not removing documentation.

---

How It Works

Phase 1: Codebase Analysis

The orchestrator analyzes the codebase structure:

1. Directory Tree Scan     -> Identify top-level modules
2. File Metrics Collection -> Count files, LOC, complexity per directory
3. Dependency Graph        -> Parse imports to build file->file dependency map
4. Cluster Formation       -> Group tightly-coupled files into processing units

Phase 2: Segment Formation

Files are grouped into segments based on:

• Natural boundaries: src/app/api/, src/lib/, src/components/
• Dependency coupling: Files that import each other stay together
• Size limits: Target 10-25 files per segment

Phase 3: Parallel Execution

Orchestrator (Main Agent)
  |-- Worker Agent (Segment A)
  |-- Worker Agent (Segment B)
  |-- Worker Agent (Segment C)

Phase 4: Verification & Consolidation

After all segments complete:

1. Run type-check (npm run typecheck)
2. Run linting (npm run lint)
3. Run unit tests (npm run test:run)
4. Verify no comments were removed (MANDATORY)
5. Create consolidated commit

Workflow Steps

Step 1: Run Analysis

npx tsx scripts/analyze-codebase.ts --verbose

Note: The analysis script automatically excludes .github/worktrees/ directories.

Step 2: Review Parallel Groups

The analysis output shows which segments can run concurrently.

Key principle: Groups are processed sequentially, but segments within a group run in parallel.

Step 3: Execute Simplification

For each parallel group:

1. Launch worker agents using the Task tool
2. Each worker receives an exclusive list of files to modify
3. Workers run simultaneously with no overlap
4. Wait for all workers before proceeding to next group

Step 4: Verify & Commit

After all groups complete, run full verification suite:

npm run typecheck
npm run lint
npx vitest run --exclude='.github/worktrees/**'
npm run build

Step 5: Comment Preservation Check (MANDATORY)

Before committing, verify that comments were NOT removed:

# Check diff for removed comments
git diff HEAD -- '*.ts' '*.tsx' | grep -E '^\-\s*//' | grep -v '^\-\s*//\s*$'

If any helpful comments were removed, restore them before committing.

Manual verification checklist:

• Section separators (// ===...) still present in modified files
• JSDoc/TSDoc blocks above functions are preserved
• Inline "why" comments are preserved
• Biome ignore directives are preserved

Simplification Patterns Applied

Workers apply these transformations:

Pattern	Before	After
Nested ternaries	a ? b ? c : d : e	Helper function
Debug logs	console.log('debug')	Removed (production code only)
Repeated patterns	Same code 3+ times	Extracted function
Complex conditions	if (a && b || c && d)	Named boolean
Long functions	100+ lines	Split into smaller functions

Conflict Prevention

Strategy	Implementation
File Ownership	Each segment has exclusive file list - no overlaps
Dependency Order	Foundation modules processed before dependents
Sequential Groups	Groups run one at a time, segments within parallel
Verification Gates	Type-check between groups catches issues early

Failure Handling

• Failed segments are retried up to 3 times with smaller batches
• Other segments continue processing
• Final report shows partial completion if needed