improve-codebase-architecture

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

1|Updated May 25, 2020
One-click install
npx skills add https://github.com/titaneric/dotfiles --skill improve-codebase-architecture-titaneric
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/titaneric/dotfiles/tree/main/dot_agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/titaneric/dotfiles --skill improve-codebase-architecture-titaneric

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules, leaky seams, and scattered logic that make testing and navigation painful. This Skill surfaces those architectural friction points and presents concrete deepening refactors as a visual report, so you can decide what to fix first. ## Core Features & Use Cases - Architecture exploration: Uses an Explore subagent to find shallow modules, cross-seam leakage, and poor locality, applying the deletion test to validate candidates. - Visual HTML report: Generates a self-contained HTML file in the OS temp directory with Tailwind and Mermaid via CDN, showing before/after diagrams, recommendation strength badges, and a top recommendation. - Guided design follow-up: After you pick a candidate, it runs a grilling loop to refine the design, updates CONTEXT.md with new domain terms, and offers ADRs for load-bearing rejections. - Use Case: Point it at a service where order handling is spread across six thin wrappers; it produces a report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the assistant to review this repository's architecture and show deepening opportunities in 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 explore the codebase with an Explore subagent that looks for modules whose interface is nearly as complex as their implementation. It applies the deletion test to confirm whether collapsing them would concentrate complexity in one place.

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 before/after diagram, problem and solution summary, and a recommendation strength badge, then the file is opened in your browser.

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 source tree. The only repo changes happen later if you accept follow-up actions like updating CONTEXT.md or recording an ADR.

What happens after I pick a refactoring candidate?

The Skill runs a grilling loop that walks the design tree with you, covering constraints, dependencies, and the shape of the deepened module. It updates CONTEXT.md with new domain terms and can offer an ADR when you reject a candidate for a load-bearing reason.

When should I not use this architecture review approach?

Skip it when an existing ADR already forbids the refactor and the friction is not severe enough to reopen that decision. It is also a poor fit for greenfield code with no accumulated module structure to evaluate.