improve-codebase-architecture

Scan a codebase for shallow modules and present deepening refactors as a visual HTML report.

Updated Jun 26, 2026
One-click install
npx skills add https://github.com/dulltackle/kangkang-skills --skill improve-codebase-architecture-dulltackle
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/dulltackle/kangkang-skills/tree/main/improve-codebase-architecture
Command: npx skills add https://github.com/dulltackle/kangkang-skills --skill improve-codebase-architecture-dulltackle

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making them hard to test and navigate. This Skill surfaces that architectural friction and proposes concrete deepening refactors instead of leaving the analysis abstract. ## Core Features & Use Cases - Hot-spot-driven exploration: Scopes the scan using git history and user direction, then applies the deletion test to find shallow modules, leaky seams, and poor locality. - Visual HTML report: Generates a self-contained Tailwind and Mermaid report in the OS temp directory with before/after diagrams, recommendation-strength badges, and ADR conflict callouts. - Grilling loop: After the user picks a candidate, walks the decision tree on constraints, seams, and tests, updating CONTEXT.md and offering ADRs as decisions crystallize. - Use Case: Point it at a subsystem where bugs keep recurring; it identifies that the Order intake pipeline is shallow, renders a before/after diagram showing the collapse into one deep module, and grills through the resulting design. ## Quick Start Ask the assistant to review the architecture of the current codebase and show deepening opportunities as an HTML report.

Frequently Asked Questions about improve-codebase-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find shallow modules in my codebase?

Run this Skill to scan the codebase for modules whose interface is nearly as complex as their implementation. It applies the deletion test to each suspect: if deleting the module would concentrate complexity rather than move it, it is flagged as a deepening candidate.

How to visualize architecture refactoring proposals?

The Skill writes a self-contained HTML report to the OS temp directory using Tailwind and Mermaid from CDNs. Each candidate gets a side-by-side before/after diagram, a recommendation-strength badge, and a one-sentence problem and solution.

Does the architecture review respect existing ADRs?

Yes, it reads ADRs in docs/adr/ before scanning and avoids re-litigating recorded decisions. A candidate that contradicts an ADR is only surfaced with a clear warning callout when the friction justifies reopening the decision.

Where does the architecture report get saved?

The report is written to the OS temp directory as architecture-review-<timestamp>.html, resolved from $TMPDIR with fallbacks to /tmp or %TEMP%. Nothing is written into the repository, and the file is opened automatically with the platform's default opener.

When should I not use this architecture review approach?

Skip it for greenfield code with no commit history, since hot-spot detection relies on git log to find frequently changed areas. It also defers interface design, so use it to identify candidates rather than to finalize APIs.