The ‘Early Learning Centre’ in the UK used to offer ‘My First…’ products, that’s the spirit of this one. Scrabbling around in the dark.
ONE Analyse the codebase for size and complexity issues:
1. **File size audit**: List all files over 300 lines, sorted by line count. Flag any file over 500 lines as a priority.
2. **Refactoring opportunities**: For each flagged file, identify:
- Functions/methods longer than 50 lines
- Repeated code patterns (potential DRY violations)
- God classes or modules with too many responsibilities
- Deeply nested logic (3+ levels)
3. **Output**: Create a markdown summary table with columns: file path, line count, top issue, suggested refactor. Prioritize by impact.
This works specifically because I’ve asked Claude to reduce investigation to a specific set of files, which can be easily searched for, which cuts down the code base nicely.
TWO
For each of the top refactoring tasks from your analysis, create 4 beads (n*4 tasks) following this exact sequence:
1. **Impact Analysis** — Trace all usages and dependencies of the code being changed. If the change is NOT orthogonal (e.g., it touches shared state, public APIs, or has unexpected downstream consumers), STOP and report back with: what's affected, why it's risky, and a suggested alternative approach if you have one. Do not move to bead 2 until you've confirmed the blast radius is safe.
2. **Test Coverage** — Write tests that exercise every code path being refactored. Tests must pass against the unmodified code before you proceed.
3. **Refactor** — Implement the refactor. Keep changes minimal and focused on the single identified issue.
4. **Full Test Suite** — Run the complete test suite. If anything fails, revert the refactor and report the failure. Do not debug beyond one attempt.
Process these sequentially per task — complete all 4 beads for task 1 before starting task 2. If bead 1 flags a non-orthogonal change on any task, skip it and move to the next.
After completing all tasks, create a summary bead reporting (so, a final extra task: the n*4+1th task): which tasks succeeded, which were skipped at bead 1 (and why), any test failures encountered, and any patterns you noticed across the refactors.
This worked really well once or twice on webdev Go + JS (Vite) codebases.
‘Orthogonal’ also strips out other possible types of refactor, and so there are a few options which come out after step one which are filtered by step two but are perfectly refactorable. This is one angle among many.