grillmester-improve-codebase-architecture

name	grillmester-improve-codebase-architecture
description	Finds deepening opportunities that improve module depth, locality, leverage, test seams, and navigability. Use when the user asks to improve architecture, consolidate tightly coupled or shallow modules, find refactoring candidates, or explain why code is difficult to test or navigate.

improve-codebase-architecture

Uncover architectural friction in this repository and propose deepening opportunities — refactorings that make shallow modules deep. The goal is testability, and that both humans and AI can navigate the code easily.

Role: this finds candidates (discovery). Design the interface for a chosen candidate inline with two genuinely different alternatives and interrogate the choice with /grillmester-grilling. When lasting concepts or decisions ought to be documented, recommend the documented route and wait for the user's choice. Use /grillmester-architecture-review for architecture review and /grillmester-domain-modeling after the documented route has been chosen.

The skill is informed by domain language and settled decisions when the repository exposes them, but it does not require a glossary, ADR directory, or agent-documentation layout. Discover those artifacts from repository evidence and load only what touches the area. This is the calling workflow's discovery stage: findings feed into /grillmester-grilling, the active plan and verification.

Vocabulary

Use the deep-module vocabulary precisely: a module hides an implementation behind a small interface; depth is the amount of complexity the interface hides. A seam is the place where the module can be separated from an adapter. Locality keeps related knowledge together, and leverage is how much complexity a single interface carries. Do not drift into "component", "service", "layer" or "API" when these more precise words fit.

The deletion test (the operational tool for discovery): would deleting the module concentrate complexity (good — it was shallow) or merely move it (then it was real)? A "yes, it concentrates" is the signal you are hunting for.

Process

1. Explore

Discover the repository's domain vocabulary, decision records and architecture guidance when they exist. Read only the artifacts that touch the area, then walk the codebase organically. Do not follow rigid heuristics. Note where you experience friction. Common deepening opportunities include:

• Thin modules in a call chain: entry point → coordinator → adapter where each link does little more than forward. Consolidate responsibility behind one deep interface.
• Mappers extracted purely for testability: pure conversion functions whose real bugs sit in how callers compose them, leaving no locality.
• Shallow client wrappers: a transport call wrapped in a class that hides nothing — authentication, retry and error contracts still leak to callers.
• Scattered event logic: ingestion, deserialization, idempotency or replay, and domain behavior spread across modules without one seam.
• Leaking persistence: query, connection, migration or transaction details seeping out of the persistence adapter.
• Hard to test through the interface: modules that require booting most of the application to exercise one behavior — a sign the seam is misplaced.

Apply the deletion test to anything you suspect is shallow.

2. Present the candidates as an HTML report

Write an offline, self-contained, script-free HTML file in a fresh private OS temporary directory. Treat every value derived from the repository as untrusted data and follow the safe-write, escaping, static-markup, and Content Security Policy contract in HTML-REPORT.md. Do not run open or xdg-open. State the absolute path and offer to open the report only if the user explicitly asks after it has been written.

Each candidate gets a card with: Files, Problem (one sentence), Solution (one sentence), Benefits (bullet list in the vocabulary — locality/leverage/test surface), Before/after diagram, and Recommendation strength (Strong, Worth exploring, Speculative). Close with a Top recommendation: which one you would take first and why.

Use the repository's discovered domain vocabulary when one exists, and the architecture vocabulary above for structure. Prefer the domain concept over a class name or generic "service" label.

ADR conflict: if a candidate contradicts an existing ADR, raise it only when the friction is real enough to justify reopening the decision. Mark it clearly on the card (yellow callout: "contradicts ADR-0007 — but worth reopening because…"). Do not list every theoretical refactoring an ADR forbids.

See HTML-REPORT.md for the full HTML scaffold, diagram patterns and style guide.

Do not propose concrete interfaces yet. Once the file is written, ask the user: "Which of these do you want to explore?"

3. Grilling loop

Once the user has chosen a candidate, run /grillmester-grilling to walk down the decision tree together with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, which tests survive. This is the calling workflow's design stage.

When clarified concepts or qualifying, lasting decisions ought to be written, recommend /grillmester-grill-with-docs, explain why and wait for the user's choice. Before a documented route is chosen, keep results in the conversation and active task.

After a documented route has been chosen, documentation happens continuously as decisions fall into place:

• Naming a deepened module after a missing domain concept? Use /grillmester-domain-modeling to update the repository's chosen vocabulary artifact when the documented route has been approved.
• Sharpening a vague term along the way? Update that same artifact when it exists and the write is in scope.
• Does the user reject the candidate for a load-bearing reason? Consider an ADR only when the decision is hard to reverse, surprising without context and the result of a real trade-off. Skip transient ("not worth it right now") and self-evident reasons. Use /grillmester-architecture-review for consequential architecture questions, including when Nav or NAIS context changes the recommendation. Use /grillmester-domain-modeling for the ADR itself.
• Want to explore alternative interfaces for the deepened module? Design two genuinely different alternatives sequentially, inline, before comparing them. Use subagents only for compact, read-only divergent exploration, never for parallel writing.

4. Connect to the phase loop

Once the chosen deepening has been thoroughly grilled:

• Write the task scope to the issue/plan. After a documented route has been chosen, /grillmester-domain-modeling writes new concepts and qualifying decisions; maintained detail goes to the relevant topic document.
• Break the deepening down into a safe, incremental refactoring plan in the active task (optionally on to /grillmester-to-issues for grabbable slices).
• Define what proves the deepening succeeded (tests through a single interface, the seam confirmed by two adapters), and return that to the calling workflow.