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 unitsPhase 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:
- Run type-check (
npm run typecheck) - Run linting (
npm run lint) - Run unit tests (
npm run test:run) - Verify no comments were removed (MANDATORY)
- Create consolidated commit
Workflow Steps
Step 1: Run Analysis
npx tsx scripts/analyze-codebase.ts --verboseNote: 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:
- Launch worker agents using the Task tool
- Each worker receives an exclusive list of files to modify
- Workers run simultaneously with no overlap
- 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 buildStep 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