improve-codebase-architecture

---title: improve-codebase-architecturename: improve-codebase-architecturedescription: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.disable-model-invocation: true---# Improve Codebase ArchitectureSurface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.Use this vocabulary exactly in every suggestion — don't drift into "component," "service," "API," or "boundary":- **Module** — a unit of code with an interface and an implementation.- **Interface** — everything a caller must know to use the module; the interface is the test surface.- **Depth** — a module is **deep** when its interface is much simpler than the functionality it hides; **shallow** when the interface is nearly as complex as the implementation.- **Seam** — a public boundary where behavior can be observed and tested without reaching inside.- **Locality** — the bugs live where the calls happen; extracting pure functions for testability without locality just moves the bugs out of test reach.- **Leverage** — one change at a deep interface improving many call sites at once.- **Deletion test** — would deleting this module concentrate complexity in one honest place, or just move it? "Yes, concentrates" marks a shallow module worth folding in.## Process### 1. ExploreRead `AGENTS.md` (project language and notes) and any relevant `specs/` first. Check `UNSURE.md` and `PAPERCUTS.md` — past confusion often marks bad abstractions.Then use the Agent tool to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:- Where does understanding one concept require bouncing between many small modules?- Where are modules **shallow** — interface nearly as complex as the implementation?- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?- Where do tightly-coupled modules leak across their seams?- Which parts of the codebase are untested, or hard to test through their current interface?Apply the **deletion test** to anything you suspect is shallow.### 2. Present candidates as an HTML reportWrite a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.For each candidate, render a card with:- **Files** — which files/modules are involved- **Problem** — why the current architecture is causing friction- **Solution** — plain English description of what would change- **Benefits** — explained in terms of locality and leverage, and how tests would improve- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badgeEnd the report with a **Top recommendation** section: which candidate you'd tackle first and why.Use the project's own domain vocabulary (from `AGENTS.md` and the code) for the domain, and the vocabulary above for the architecture.See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"### 3. Grilling loopOnce the user picks a candidate, run the `/grilling` skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.Side effects happen inline as decisions crystallize:- **Made a judgment call the user should be able to revisit?** Append it to `UNSURE.md`.- **User rejects a candidate with a load-bearing reason?** Offer to record it under `Project Specific Notes` in `AGENTS.md`, so future architecture reviews don't re-suggest it. Only when the reason would actually be needed later — skip ephemeral ("not worth it right now") and self-evident ones.