Discover architectural friction and proposemodule deepening opportunities: refactor shallow modules into deep modules to improve testability and AI navigability. This Skill only performs read-only exploration, reporting, and decision closure; it does not modify business code. After the user confirms they want to implement it, proceed to impl。
process
1. Load project context
Use the already loaded CONTEXT terminology and RULE. If not yet loaded, follow the project knowledge protocol; if knowledge is unavailable, continue and state so truthfully. Project terminology is used to name business concepts, and relevant ADRs are used to identify existing decisions that should not be reopened without reason.
Fully read codebase-design, using itsmodule, interface, depth, seam, adapter, leverage, localityvocabulary and judgment criteria.
2. Explore
First define the scan scope: YAGNI. The benefit of deepening a module comes from making future changes easier, so prioritize areas that change frequently in the near term.
- When the user specifies a module, subsystem, or pain point, use that direction directly.
- When the user does not specify one, inspect a sufficiently long
git log --oneline, and identify recurring files and hotspot areas; only expand the scope when there is no obvious hotspot.
Hand the selected scope, relevant CONTEXT, RULE, ADR, and codebase-design judgment criteria to a read-only sub-agent for exploration. Do not apply a fixed checklist; instead, record real friction while understanding the code:
- Does understanding a concept require jumping back and forth among many small modules?
- Which modules are shallow, with interfaces almost as complex as their implementations?
- Which pure functions were extracted only for testing, while the real defects lie in how they are called, lacking locality?
- Which tightly coupled modules let details leak beyond the seam?
- Which areas cannot be tested naturally through the current interface?
For suspected shallow modules, perform thedeletion test: would deleting it make the complexity disappear, or would it merely scatter the complexity back across multiple callers? Only when the complexity scatters back does the module have deepening value.
3. Generate an HTML report
Write a new architecture-review-<timestamp>.htmlto the operating system temporary directory, and do not write the report into the repository. Prefer $TMPDIR, otherwise use /tmp; on Windows use %TEMP%. After generating it, open it with the current system's default method, and return the absolute path to the user.
The report uses Tailwind CDN for layout and styling, and Mermaid CDN to express call graphs, dependency graphs, and sequences; when a sense of quality, cross-sections, or collapsible effects are needed, use handwritten CSS, div, or inline SVG. Every candidate must have a before / after visualization.
Each candidate card includes:
- Files involved: related files and modules;
- Problem: the specific friction caused by the current architecture;
- Plan: explain in business-readable language what is to be changed;
- Benefits: explain in terms of locality, leverage, and test surface;
- Before / After: show the current shallow shape and the deepened shape side by side;
- Recommendation strength：
强烈推荐、值得探索or推测性。
At the end of the report, give apreferred recommendation: the candidates most worth exploring first and why.
Use CONTEXT vocabulary to name business concepts, use codebase-design vocabulary to describe the architecture. When candidates conflict with an ADR, show them only if the friction is real and sufficient to reopen discussion of the ADR, and clearly mark the conflict on the card.
For the full format, graphical modes, and styling requirements, see HTML-REPORT.md. This stage does not design specific interfaces. After writing the report, ask the user: "Which candidate do you want to continue exploring?"
4. Decision follow-up questions
After the user selects a candidate, start ask-me, and complete the decision tree around constraints, dependencies, the deepened module shape, what is behind the seams, and which tests to keep.
During the decision process:
- When new long-term project terminology or reusable rules appear, propose recording them per the project knowledge protocol, and write them in after user confirmation;
- When the user rejects a candidate for long-term, load-bearing reasons, ask whether to record an ADR to avoid repeating the suggestion in the future; do not record one-off reasons such as short-term priorities;
- When the user wants to compare multiple interfaces, read
codebase-design'sDESIGN-IT-TWICE.mdand perform multi-option design; - When the user confirms implementation, end this Skill and move to
impl, without directly modifying code within the architecture exploration process.