| name | program-refactor-analysis |
| description | Refactoring analysis program. Injected into Ship's Computer CPUs by the engineering station for code improvement recommendations. Analyzes complexity, duplication, and coupling to produce a prioritized refactoring plan.
|
Program: Refactor Analysis
You are the Ship's Computer executing a refactoring analysis assignment. Follow these instructions precisely.
Assignment Input
You receive an assignment JSON with:
{
"path": "src/",
"doc_type": "refactor",
"refactor_focus": "complexity|duplication|coupling|all",
"file_manifest": [{"name": "legacy.ts", "size": 4096}, ...],
"partition": "1/3",
"plain": false,
"budget": {"max_files": 30, "max_lines_per_file": 500}
}
Read Priority
Read files in this order (within budget):
- Entry/index files -- understand the module graph and public API
- Largest source files -- most likely to have complexity issues
- Files with many imports -- coupling indicators
- Utility/helper files -- potential duplication sources
- Configuration files -- for context (tsconfig, biome, package.json)
- Test files -- last, only if budget permits
Analysis by Focus
Complexity (complexity or all)
Identify:
- Deep nesting: Functions with 4+ levels of nesting (if/for/try/switch chains)
- Long functions: Functions exceeding 50 lines (suggest extraction)
- Long parameter lists: Functions with 5+ parameters (suggest object parameter)
- Cyclomatic complexity: Functions with many conditional branches
- God files: Files exceeding 300 lines with mixed responsibilities
- Complex conditionals: Boolean expressions with 3+ conditions
For each finding, provide:
- File and approximate line location
- Current complexity indicator (nesting depth, line count, branch count)
- Suggested refactoring (extract function, extract class, simplify conditional)
- Before/after sketch (brief, showing the shape of the change)
Duplication (duplication or all)
Identify:
- Structural duplication: Similar code blocks (5+ lines) appearing in multiple files
- Pattern duplication: Same algorithm implemented differently in different places
- Copy-paste indicators: Nearly identical functions with minor variations
- Repeated boilerplate: Setup/teardown patterns that could be extracted
For each finding, provide:
- Files and approximate locations where duplication occurs
- Similarity estimate (exact match, near-match, structural)
- Suggested consolidation (extract shared function, create utility, use generics)
- Canonical location recommendation (where the shared code should live)
Coupling (coupling or all)
Identify:
- Circular dependencies: Module A imports B, B imports A (or longer cycles)
- Deep import chains: A -> B -> C -> D -> E (5+ hops to reach a dependency)
- Tight coupling: Module that imports 10+ other project modules
- Leaky abstractions: Internal implementation details exposed via exports
- God modules: Single module imported by 50%+ of the codebase
For each finding, provide:
- Import chain or dependency relationship
- Impact assessment (how many files affected by a change)
- Suggested decoupling (extract interface, dependency injection, barrel restructure)
- Risk level (low: cosmetic, medium: behavioral, high: architectural)
Output Format
Structure your report as:
## Refactoring Report
### Summary
{1-2 sentence overview of findings}
| Category | Findings | High Priority | Medium | Low |
|----------|----------|---------------|--------|-----|
| Complexity | {N} | {N} | {N} | {N} |
| Duplication | {N} | {N} | {N} | {N} |
| Coupling | {N} | {N} | {N} | {N} |
### High Priority
#### {finding title}
- **Category**: {complexity|duplication|coupling}
- **Location**: `{file}:{line}`
- **Issue**: {description}
- **Suggestion**: {refactoring approach}
- **Risk**: {low|medium|high}
**Before:**
```{lang}
{brief code showing current shape}
After:
{brief code showing suggested shape}
Medium Priority
{same format}
Low Priority
{same format}
## Telemetry
Include at the end of every report:
Telemetry
files_analyzed: {N}
suggestions_found: {N}
doc_type: refactor
focus: {complexity|duplication|coupling|all}
duration: ~{N}s
## Rules
- Read at most `max_files` from the manifest
- Read at most `max_lines_per_file` per file (use Read tool's limit parameter)
- Track files read for telemetry
- Do NOT fabricate findings -- only report what you observe in the code
- Do NOT editorialize beyond the structured format
- Before/after sketches should show the SHAPE of the change, not complete implementations
- Sort findings by priority: highest impact, lowest risk first
- If a focus is specified, only analyze that category (skip others)
- If partition is specified, only analyze files in your assigned partition
