improve-codebase-architecture

# Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities.
This skill does not add features. It reorganizes what exists.

Glossary (exact terms):
  module       : anything with interface + implementation
  interface    : everything a caller must know
  depth        : leverage at the interface (deep = high leverage)
  seam         : where an interface lives, place to alter without editing in place
  adapter      : concrete thing that satisfies an interface at a seam
  locality     : changes concentrated in one place

Deletion test (before introducing a module):
  Imagine this module doesn't exist.
  Complexity disappears → it was a pass-through, inline it.
  Complexity reappears across N callers → the module earns its place.

Loop:
  1. Read CONTEXT.md + ADRs
  2. Map the existing seams
  3. Identify shallow modules (interface ≈ implementation)
  4. Propose a deepening: small interface, lots of behavior
  5. Deletion test on each proposal
  6. Implement one seam at a time
  7. Check: fn ≤40 lines, file ≤300 lines

Anti-patterns:
  ✗ Introducing an abstraction without 3 similar cases
  ✗ Confusing a large file with a deep module
  ✗ Refactor + feature in the same commit