improve-codebase-architecture

Improve Codebase Architecture

Not every rough edge is the same kind of problem. This skill's defining constraint, from Martin Fowler's technical debt quadrant: every finding is classified on two axes before it's prioritized: deliberate vs. inadvertent (was the tradeoff known at the time) and prudent vs. reckless (was it a reasoned tradeoff or a corner cut under pressure). A knowingly-accepted tradeoff and an accidental mistake call for different responses even when the resulting code looks identical.

This skill finds what's shallow; codebase-design supplies the vocabulary (module, interface, depth, seam, the deletion test) for describing why. Use that skill's terms exactly rather than drifting into generic words like "component" or "service."

Phase 1: Scope the scan

Decide where to look before looking everywhere, scanning a whole codebase uniformly dilutes attention across places that don't need it:

• If the user named a module, subsystem, or pain point, take it directly.
• Otherwise, walk back through recent commit history to find hot spots (files and areas that keep recurring) since a module actively being changed pays back a deepening investment faster than a stable, rarely-touched one.

Read any existing domain glossary or ADRs covering the scoped area first, so findings don't re-litigate a decision already made deliberately.

Phase 2: Find the friction

Walk the scoped code looking for Ousterhout-style red flags (see codebase-design for the full vocabulary):

• A module whose interface is nearly as complex as its implementation; shallow, not deep.
• Understanding one concept requires bouncing across many small modules to assemble the picture.
• Logic extracted into "testable" pure functions while the real bugs live in how and where they're called; no locality.
• A seam that's leaking implementation details across it instead of hiding them.

For each candidate, apply the deletion test: would removing it concentrate the complexity somewhere sensible, or just relocate the same mess? Only "concentrates" candidates are worth writing up.