improve-codebase-architecture

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

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

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 grounded in a shared design vocabulary. ## Core Features & Use Cases - Architecture exploration: Walks the codebase (optionally via a sub-agent), prioritizing recently changed hot spots from git history, and applies the deletion test to detect shallow modules, seam leakage, and poor locality. - Visual HTML report: Renders each candidate refactor as a self-contained HTML file in the OS temp directory with Tailwind and Mermaid diagrams, before/after visualizations, recommendation-strength badges, and ADR conflict callouts. - Grilling loop: After the user picks a candidate, drives a decision-tree conversation about constraints, seams, and tests, keeping CONTEXT.md and ADRs current along the way. - Use Case: A team notices their order intake flow is spread across six tiny wrappers. Run this Skill to get a visual report of deepening candidates, pick one, and grill through the design before writing any code. ## Quick Start Ask the assistant to review this repository's architecture 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 interfaces are nearly as complex as their implementations. 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.

What is a deepening refactor in software architecture?

A deepening refactor turns a shallow module into a deep one: a small interface hiding a substantial implementation. The Skill presents each candidate with before/after diagrams, the problem, the solution, and wins expressed in terms of locality and leverage.

Where does the architecture review report get saved?

The report is written as a self-contained HTML file to the OS temp directory, resolved from $TMPDIR with fallback to /tmp or %TEMP%, named architecture-review-<timestamp>.html. Nothing is written into the repository itself.

Does the architecture review respect existing ADRs?

Yes, the Skill reads ADRs in docs/adr/ before proposing candidates 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.

What happens after I pick a refactoring candidate?

The Skill enters a grilling loop that walks the decision tree: constraints, dependencies, the shape of the deepened module, what sits behind the seam, and which tests survive. It also updates CONTEXT.md and offers to record ADRs as decisions crystallize.