Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones, aimed at testability and AI-navigability. This skill never edits code itself — it never could, the planner is read-only — so the outcome is plan tasks, not a live refactor. Each candidate the user picks becomes one task for a runner to execute later, out of this conversation's sight.

Vocabulary

• Module / interface / depth — a module is deep when its interface is much simpler than what it hides; shallow when the interface is nearly as complex as the implementation.
• Seam — a boundary a test double or adapter swap crosses. Locality — how close the code that causes a bug sits to the code that shows it; extracting a pure function for testability without moving where the real logic runs loses locality.
• Leverage — how much simpler calling code gets once a module is deepened.
• Deletion test — would deleting this module concentrate complexity elsewhere (worth deepening), or just move it (not worth it)?

If the project keeps its own domain glossary (a CONTEXT.md or similar) or an ADR log (docs/adr/ or similar), use its terms in place of these where they overlap, and read the ADRs that touch the area you're exploring before proposing anything that contradicts one.

Process

1. Explore

Scope before you scan — put weight on what changes often, not everywhere:

• User named a direction (a module, a subsystem, a pain point)? Take it, skip the inference below.
• Otherwise walk git log --oneline for hot spots and let those pull your attention first. Scattered history with no clear hot spot → widen the net.

Explore read-only, delegating to a research subagent where one is available to you instead of reading everything inline. Don't follow rigid heuristics; explore organically and note where you experience friction — where understanding one concept means bouncing between many small modules, where an interface is nearly as complex as its implementation, where a pure function was extracted for testability but the real bug lives in how it's called, where modules leak across their seam, what's untested or hard to test through its current interface. Apply the deletion test to anything you suspect is shallow.

2. Present candidates, prioritized

List every candidate directly in the conversation — no report file; nothing in this step touches disk. For each:

• Title — names the deepening (e.g. "Collapse the Order intake pipeline")
• Files
• Problem / Solution — one sentence each, in the project's own vocabulary where it has one
• Benefits — explained in terms of locality and leverage, and how tests would improve; this is what the recommendation strength below has to be earned by, not asserted
• Recommendation: Strong, Worth exploring, or Speculative
• Overlaps — which other candidates touch the same files; this drives task ordering in step 4
• If it contradicts an existing ADR, a one-line callout naming it (e.g. "contradicts ADR-0007, but worth reopening because…") — only when the friction is real enough to warrant reopening the decision, not for every refactor an ADR happens to forbid

Order the list Strong → Worth exploring → Speculative, and close with which one you'd tackle first and why. Do not propose interfaces yet.

Ask: how many of these should become tasks? Default, unless told otherwise: every Strong candidate, none of the rest. The user may instead name specific candidates, a count ("top 3"), or "all" — whatever they say overrides the default.