decompose-file

---
namespace: aiwg
name: decompose-file
platforms: [all]
description: Analyze large source files and produce decomposition plans, optionally executing refactoring with import updates and test verification

---

# decompose-file

Analyze a large source file and produce a concrete decomposition plan, optionally executing the refactoring with import updates and test verification.

## Triggers


Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

- "this file is too large" → file decomposition trigger
- "split into modules" → modular decomposition

## Purpose

When `/codebase-health` identifies files exceeding agent-friendly thresholds (300 LOC warning, 500 LOC error), this skill provides guided decomposition. It analyzes file structure, identifies logical groupings, maps internal dependencies, proposes a split plan, and optionally executes the refactoring.

The doc-splitter skill handles documentation splitting. This skill handles source code splitting — a fundamentally different problem requiring dependency analysis, import rewiring, and test verification.

## Behavior

When triggered, this skill:

1. **Analyze file structure**:
   - Parse the file to identify logical sections (classes, function groups, export clusters)
   - Measure each section's size in LOC
   - Identify the file's primary language and applicable parsing strategy
   - Report current file size vs. agent-friendly thresholds

2. **Map internal dependencies**:
   - Trace references between identified sections
   - Identify shared state (module-level variables, constants)
   - Detect circular dependency risks in proposed splits
   - Catalog all exports and their consumers

3. **Propose split plan**:
   - Assign each section to a proposed output file
   - Name output files descriptively (no generic names)
   - Ensure each output file is under the warning threshold (300 LOC)
   - Include shared dependencies in the most logical location
   - Add a purpose statement for each proposed file

4. **Show dependency graph**:
   - Visualize which proposed modules depend on which
   - Verify no circular dependencies exist
   - Show import direction between new modules

5. **Execute refactoring** (if `--execute` or user approves):
   - Create new files with proper imports
   - Update the original file to re-export if needed for backward compatibility
   - Find and update all import statements across the codebase
   - Add module-level purpose statements to each new file
   - Run tests to verify no breakage

## Analysis Strategies

### Language-Specific Parsing

| Language | Strategy | Boundaries |
|----------|----------|------------|
| TypeScript/JavaScript | AST via function/class/export declarations | `export`, `class`, `function`, `const` |
| Python | AST via `ast` module | `class`, `def`, top-level assignments |
| Go | Package-level function/type declarations | `func`, `type`, `var` blocks |
| Rust | `mod`, `fn`, `struct`, `impl` blocks | Module and impl boundaries |
| Java | Class and method declarations | `class`, `interface`, `enum` |

### Heuristic Fallback

For unsupported languages or when AST parsing is unavailable:

1. **Blank line groups** — consecutive blank lines often separate logical sections
2. **Comment blocks** — section header comments (`// --- Section Name ---`)
3. **Indentation changes** — top-level declarations at zero indentation
4. **Export clusters** — groups of exports at file end

## Decomposition Plan Format

```
Decomposition Plan for src/extensions/registry.ts (847 lines)

Current Structure:
  1. Imports and type definitions (lines 1-45)
  2. ExtensionRegistry class (lines 47-320)
     2a. Constructor and initialization (lines 47-85)
     2b. register() — registers an extension (lines 87-145)
     2c. lookup() — finds extension by name (lines 147-210)
     2d. listByType() — returns extensions of a type (lines 212-260)
     2e. unregister() — removes an extension (lines 262-320)
  3. Validation functions (lines 322-480)
     3a. validateExtension() (lines 322-390)
     3b. validateManifest() (lines 392-440)
     3c. checkDependencies() (lines 442-480)
  4. Discovery helpers (lines 482-620)
  5. Deployment logic (lines 622-847)

Proposed Split:

  1. src/extensions/registry.ts (185 lines)
     — ExtensionRegistry class (core registration, lookup, list, unregister)
     — Imports from: validation, discovery, deployment

  2. src/extensions/extension-validator.ts (160 lines)
     — validateExtension(), validateManifest(), checkDependencies()
     — No internal dependencies

  3. src/extensions/extension-discovery.ts (140 lines)
     — discoverExtensions(), globForType(), resolveExtensionPath()
     — Imports from: extension-validator

  4. src/extensions/extension-deployer.ts (227 lines)
     — deployToProvider(), buildProviderConfig(), writeDeploymentFiles()
     — Imports from: registry, extension-validator

Dependency Graph:
  registry → extension-validator
  registry → extension-discovery
  registry → extension-deployer
  extension-discovery → extension-validator
  extension-deployer → registry, extension-validator

Circular Dependencies: NONE ✓

All proposed files under 300 LOC warning threshold ✓
```

## Arguments

| Argument | Required | Default | Description |
|----------|----------|---------|-------------|
| `<file-path>` | Yes | — | File to decompose |
| `--max-lines <n>` | No | 300 | Target max lines per output file |
| `--dry-run` | No | true | Show plan without executing |
| `--execute` | No | false | Execute the plan automatically |
| `--language <lang>` | No | auto-detect | Override language detection |
| `--strategy <type>` | No | auto | `function`, `class`, or `responsibility` |
| `--preserve-exports` | No | true | Maintain backward-compatible re-exports |

## Execution Workflow

When `--execute` is used:

```
┌─────────────────────────────────────────────┐
│ 1. ANALYZE                                   │
│    • Parse file structure                    │
│    • Identify logical sections               │
│    • Map dependencies                        │
└──────────────┬──────────────────────────────┘
               ▼
┌─────────────────────────────────────────────┐
│ 2. PLAN                                      │
│    • Propose split into N files              │
│    • Verify no circular dependencies         │
│    • Show plan to user                       │
└──────────────┬──────────────────────────────┘
               ▼
┌─────────────────────────────────────────────┐
│ 3. EXECUTE                                   │
│    • Create new files with content           │
│    • Add purpose statements                  │
│    • Update original file (re-exports)       │
└──────────────┬──────────────────────────────┘
               ▼
┌─────────────────────────────────────────────┐
│ 4. REWIRE                                    │
│    • Find all imports of original file       │
│    • Update to point to new modules          │
│    • Handle re-exports for compat            │
└──────────────┬──────────────────────────────┘
               ▼
┌─────────────────────────────────────────────┐
│ 5. VERIFY                                    │
│    • Run tests                               │
│    • Check for import errors                 │
│    • Report pass/fail                        │
└─────────────────────────────────────────────┘
```

## Usage Examples

### Dry Run (Default)

```
User: "decompose src/extensions/registry.ts"

Skill analyzes the file and produces:
- Current structure map with line ranges
- Proposed split into 4 files
- Dependency graph
- Verification: no circular dependencies

Output shows the plan without making changes.
```

### Execute with Verification

```
User: "/decompose-file src/extensions/registry.ts --execute"

Skill:
1. Analyzes and shows plan
2. Creates 4 new files
3. Updates registry.ts to re-export for compatibility
4. Finds 23 files importing from registry.ts
5. Updates imports to point to specific modules
6. Runs test suite: 247 passed, 0 failed ✓

Output:
"Decomposition complete. 1 file (847 lines) → 4 files (avg 178 lines).
 All tests passing. 23 import statements updated."
```

### Custom Strategy

```
User: "/decompose-file src/services/user-service.ts --strategy class --max-lines 200"

Skill splits by class boundaries, targeting 200 lines per output file.
```

## Error Handling

### File Too Small

```
File src/utils/helper.ts is 85 lines — below the warning threshold (300).
No decomposition needed. Use --max-lines to override if desired.
```

### Circular Dependencies Detected

```
⚠ Proposed split would create circular dependency:
  module-a → module-b → module-a

Suggestions:
1. Extract shared code into a common module
2. Merge module-a and module-b sections
3. Use dependency injection to break the cycle

Adjusted plan: [shows revised plan]
```

### Tests Fail After Split

```
🚫 Tests failed after decomposition.

Failures:
  test/unit/registry.test.ts:42 — Cannot find module './registry'

Root cause: Import path not updated in test file.
Fix: Updating test imports...

Re-running tests: 247 passed, 0 failed ✓
```

## Integration

This skill uses:
- `agent-friendly-code` rule: Target thresholds for output file sizes
- `agent-generation-guardrails` rule: Prevents creating new large files during split
- `executable-feedback` rule: Runs tests after execution to verify no breakage
- `anti-laziness` rule: Does not skip the split because it is complex
- `/codebase-health` command: Identifies candidates for decomposition

## Output Locations

- Decomposition plan: `.aiwg/working/decompose-{filename}-{date}.md`
- New source files: Same directory as original file (or user-specified)

## References

- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/agent-friendly-code.md — Threshold definitions
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/agent-generation-guardrails.md — Runtime guardrails
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/executable-feedback.md — Test after changes
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/commands/codebase-health.md — Identifies candidates
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/code-chunker/SKILL.md — Navigate large files before splitting