improve-codebase-architecture

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

10|3|Updated Jul 18, 2019
One-click install
npx skills add https://github.com/tanqimin/MyFavsORM --skill improve-codebase-architecture-tanqimin
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/tanqimin/MyFavsORM/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/tanqimin/MyFavsORM --skill improve-codebase-architecture-tanqimin

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 review using git history and user direction, then spawns a sub-agent to find shallow modules, seam leakage, and poor testability. - Visual HTML report: Renders each candidate refactor as a self-contained HTML file with Tailwind and Mermaid before/after diagrams, recommendation-strength badges, and ADR conflict callouts, written to the OS temp directory. - Guided decision loop: After the user picks a candidate, it hands off to a grilling workflow that refines the design, updates CONTEXT.md, and offers ADRs for rejected candidates. - Use Case: Point it at a service where understanding one feature requires bouncing between six tiny classes; it returns a report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the assistant to review the architecture of the current repository 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 against your repository; it walks recent git history to find hot spots, then explores for modules whose interfaces are nearly as complex as their implementations. Each finding is presented with a before/after diagram and a deepening proposal.

What is a deep module versus a shallow module?

A deep module hides a large implementation behind a small interface, while a shallow module's interface is nearly as complex as what it wraps. The Skill applies a deletion test: if deleting a module would concentrate complexity rather than just move it, it is a deepening candidate.

Does the architecture review write files into my repository?

No. The HTML report is written to the OS temp directory as architecture-review-<timestamp>.html and opened in your browser, so nothing lands in the repo. CONTEXT.md is only updated later, during the grilling phase, when new domain terms emerge.

How does the review handle existing ADRs?

Candidates that contradict an existing ADR are only surfaced when the friction is real enough to warrant reopening the decision, and they are marked with a warning callout referencing the ADR. Theoretical refactors an ADR forbids are not listed.

What happens after I pick a refactoring candidate?

The Skill hands off to a grilling workflow that walks the decision tree: constraints, dependencies, the shape of the deepened module, and which tests survive. It can also record rejected candidates as ADRs and explore alternative interface designs in parallel.