improve-codebase-architecture

Explore the codebase organically and note where understanding one concept requires bouncing between many small files. Use git log to focus on hot spots, then apply the deletion test: if deleting a module makes complexity reappear across callers, it earns its keep; if complexity vanishes, it is a pass-through.

A deep module has a small interface hiding a large implementation, making it more testable and easier to navigate. It can be tested at its seam rather than inside, unlike shallow modules whose interface is nearly as complex as their implementation.

The Skill runs gh issue create with a structured template covering the problem, proposed interface, dependency strategy, testing strategy, and implementation recommendations. It creates the issue directly and shares the URL without requiring prior review.

Yes, the Skill uses whatever exploration and parallel-dispatch mechanism the host runtime offers, such as Claude Code's Explore subagent and Agent tool or Codex MultiAgentV2 workers. Sequential execution is the fallback when neither is available.

Avoid deepening modules in code nobody touches, since the refactor will never pay off. Scope the search to hot spots from recent git history first, and only widen the net across the repo when changes are scattered with no clear hot spot.