improve-codebase-architecture

Make an error class impossible, not another check/test. Generic audit belongs to /improve; implementation to /development-lifecycle. Stay read-only.

Vocabulary

Run /codebase-design; use its module, interface, implementation, depth, seam, adapter, leverage, and locality terms.

• Deletion test: removing a deep module spreads hidden complexity into callers.
• Interface is the test surface: verify design through its stable interface.
• Two adapters justify a seam: one adapter is hypothetical.
• Single source of truth: behavior follows one owned representation, not parallel lists, flags, registries, validators, or lifecycles.
• Structural invariant: construction/transitions make invalid states impossible or unrepresentable.

Read CONTEXT.md and relevant ADRs; domain language names modules and prevents needless re-litigation.

1. Frame

Scope before scanning -- YAGNI. If the user names a module/error/pain point, take that scope. Otherwise use git log --name-only --format= for hot spots; widen only when history is scattered.

Explore inline by default; delegation must be explicit. Prefer repo graph tools. Map interfaces, dependency graph or call graph, data ownership, writers, state transitions, failure paths, and interface tests.