improve-codebase-architecture

Scan a codebase for module deepening opportunities and present them as a visual HTML report.

Updated Sep 21, 2026
One-click install
npx skills add https://github.com/maxentr/la-cuisine-de-mm --skill improve-codebase-architecture-maxentr
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/maxentr/la-cuisine-de-mm/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/maxentr/la-cuisine-de-mm --skill improve-codebase-architecture-maxentr

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, presented visually rather than as a wall of prose. ## Core Features & Use Cases - Architecture exploration: Walks the codebase (guided by recent commit hot spots, CONTEXT.md, and ADRs) to find shallow modules, leaking seams, and poor locality, applying the deletion test to each candidate. - Visual HTML report: Generates a self-contained HTML file in the OS temp directory using Tailwind and Mermaid via CDN, with before/after diagrams, recommendation-strength badges, and a top recommendation section. - Grilling loop: After you pick a candidate, it drives a structured decision conversation about constraints, dependencies, and the deepened module's shape, updating CONTEXT.md and offering ADRs when decisions are load-bearing. - Use Case: Point it at a subsystem that keeps changing, review the rendered report of deepening candidates, pick one, and grill through the design before writing any code. ## Quick Start Ask the assistant to review the architecture of the order intake subsystem 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 walk the codebase and flag 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 a deepening candidate.

What does the architecture review report look like?

The report is a single self-contained HTML file written to the OS temp directory, styled with Tailwind via CDN and diagrammed with Mermaid plus hand-built SVG. Each candidate card shows files, problem, solution, benefits, a before/after diagram, and a recommendation-strength badge.

Does the architecture review respect existing ADRs?

Yes, it reads ADRs in docs/adr/ before proposing changes 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 through constraints, dependencies, the deepened module's shape, and which tests survive. It updates CONTEXT.md with new domain terms and offers to record an ADR when you reject a candidate for a load-bearing reason.

When should I not use this architecture review approach?

Skip it for parts of the codebase that rarely change, since deepening pays off mainly where future modifications are likely. It also does not propose concrete interfaces during the report phase, so it is not a code-generation tool.