improve-codebase-architecture

Scan a codebase for module deepening opportunities and render findings as a visual HTML report.

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

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 so you can judge trade-offs before committing. ## Core Features & Use Cases - Hot-spot-driven exploration: Scopes the scan using git history and user direction, then spawns a sub-agent to find shallow modules, seam leakage, and poor locality. - Visual HTML report: Writes a self-contained Tailwind + Mermaid report to the OS temp directory with before/after diagrams, recommendation-strength badges, and ADR conflict callouts. - Grilling loop: After you pick a candidate, runs the grilling skill to walk the decision tree, updating CONTEXT.md and offering ADRs as decisions crystallize. - Use Case: Point it at a subsystem where bugs keep recurring; it identifies that pricing logic leaks across a seam, renders a before/after diagram of the deepened module, and walks you through the refactor decision. ## Quick Start Ask the assistant to review the architecture of the current codebase or a named subsystem and present 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 architecture refactoring opportunities in my codebase?

Run this skill to scan your codebase for shallow modules, seam leakage, and poor locality. It uses git history to focus on hot spots, then presents each candidate refactor as a visual before/after card in an HTML report.

What is a deep module versus a shallow module?

A deep module has a small interface hiding a substantial implementation, while a shallow module's interface is nearly as complex as its implementation. The skill applies the deletion test: if deleting a module would concentrate complexity rather than move it, it is a deepening candidate.

Does the architecture review modify my repository files?

The HTML report is written to the OS temp directory, not the repo, so nothing lands in your project. It may update CONTEXT.md or offer to record ADRs during the grilling phase, but only as decisions are made with you.

How does the review handle existing ADRs?

Candidates that contradict an existing ADR are only surfaced when the friction is real enough to warrant revisiting the decision. Such candidates are marked with a warning callout referencing the ADR rather than silently re-litigating it.

What happens after I pick a refactoring candidate?

The skill runs the grilling skill to walk the decision tree with you, covering constraints, dependencies, and the shape of the deepened module. It updates the domain model in CONTEXT.md inline and can invoke codebase-design to explore alternative interfaces.