Spring Cleaning
Full codebase health pass. Two phases, in order.
Phase 1: Subtract
"Should this still exist?"
Delete things. The codebase gets smaller.
- Dead code — Unused functions, types, modules, imports, variables, and constants. If nothing calls it, remove it.
- Unused dependencies — Dependencies in the manifest that aren't imported anywhere. Remove them.
- Backwards compatibility shims — Deprecated APIs, migration helpers, legacy type aliases, re-exports kept only for old consumers. If the migration window has passed, remove them.
- Abandoned experiments — Half-finished features behind dead flags, commented-out code blocks, modules that were started but never wired in.
- Stale config — Environment variables, feature flags, or config keys that nothing reads anymore.
- Orphaned files — Files that aren't imported, included, referenced, or served anywhere. Stale test fixtures, unused assets, leftover scripts, generated files that aren't regenerated.
- Gitignore hygiene — Check
.gitignore for patterns that no longer apply (removed tooling, old build dirs). Add missing patterns for things that shouldn't be tracked (build artifacts, editor files, OS files, secrets, .env).
Catalog (don't delete) TODOs and placeholders — search for TODO, FIXME, HACK, XXX, placeholder implementations. Present a list with location (file:line), brief description, and suggested priority.
Phase 2: Restructure
"Should this be structured differently?"
Reshape what survived Phase 1. The codebase gets better organized.
- Deduplication — Duplicated logic, copy-pasted code, or near-identical implementations that could be unified into a shared function, trait, or module.
- Missing abstractions — Places where a shared trait, interface, type, or helper would reduce repetition and make the code more expressive.
- Module splits — Large modules doing too many things that should be broken into focused pieces.
- Pattern normalization — Inconsistent approaches to the same problem (e.g., error handling done three different ways). Pick the best pattern and normalize.
- Coupling — Tightly coupled code that should be disentangled so pieces can change independently.
- Efficiency — Unnecessary allocations, redundant operations, or suboptimal algorithms where a simpler or faster approach exists.
- Dependency leverage — Vendored or hand-rolled code that an existing dependency already handles, or dependencies that could replace verbose manual implementations.
Why This Order Matters
Delete first, restructure second. No point deduplicating code that should be deleted. No point extracting abstractions from dead modules.
1---2name: spring-cleaning3description: Full codebase health pass in two phases — first delete dead things (unused code, deps, shims), then restructure what remains (dedup, abstractions, pattern normalization, efficiency).4---56# Spring Cleaning78Full codebase health pass. Two phases, in order.910## Phase 1: Subtract1112**"Should this still exist?"**1314Delete things. The codebase gets smaller.15161. **Dead code** — Unused functions, types, modules, imports, variables, and constants. If nothing calls it, remove it.172. **Unused dependencies** — Dependencies in the manifest that aren't imported anywhere. Remove them.183. **Backwards compatibility shims** — Deprecated APIs, migration helpers, legacy type aliases, re-exports kept only for old consumers. If the migration window has passed, remove them.194. **Abandoned experiments** — Half-finished features behind dead flags, commented-out code blocks, modules that were started but never wired in.205. **Stale config** — Environment variables, feature flags, or config keys that nothing reads anymore.216. **Orphaned files** — Files that aren't imported, included, referenced, or served anywhere. Stale test fixtures, unused assets, leftover scripts, generated files that aren't regenerated.227. **Gitignore hygiene** — Check `.gitignore` for patterns that no longer apply (removed tooling, old build dirs). Add missing patterns for things that shouldn't be tracked (build artifacts, editor files, OS files, secrets, `.env`).2324Catalog (don't delete) **TODOs and placeholders** — search for `TODO`, `FIXME`, `HACK`, `XXX`, placeholder implementations. Present a list with location (file:line), brief description, and suggested priority.2526## Phase 2: Restructure2728**"Should this be structured differently?"**2930Reshape what survived Phase 1. The codebase gets better organized.31321. **Deduplication** — Duplicated logic, copy-pasted code, or near-identical implementations that could be unified into a shared function, trait, or module.332. **Missing abstractions** — Places where a shared trait, interface, type, or helper would reduce repetition and make the code more expressive.343. **Module splits** — Large modules doing too many things that should be broken into focused pieces.354. **Pattern normalization** — Inconsistent approaches to the same problem (e.g., error handling done three different ways). Pick the best pattern and normalize.365. **Coupling** — Tightly coupled code that should be disentangled so pieces can change independently.376. **Efficiency** — Unnecessary allocations, redundant operations, or suboptimal algorithms where a simpler or faster approach exists.387. **Dependency leverage** — Vendored or hand-rolled code that an existing dependency already handles, or dependencies that could replace verbose manual implementations.3940## Why This Order Matters4142Delete first, restructure second. No point deduplicating code that should be deleted. No point extracting abstractions from dead modules.
samgalanakis