improve-codebase-architecture

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

Updated Jul 4, 2024
One-click install
npx skills add https://github.com/hareki/dotfiles --skill improve-codebase-architecture-hareki
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/hareki/dotfiles/tree/main/agents/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/hareki/dotfiles --skill improve-codebase-architecture-hareki

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 vague cleanup advice. ## Core Features & Use Cases - Architecture exploration: Uses an Explore subagent to find shallow modules, leaking seams, and poor locality, applying the deletion test to validate candidates. - Visual HTML report: Generates a self-contained Tailwind + Mermaid report in the OS temp directory with before/after diagrams, recommendation-strength badges, and a top recommendation. - Guided design grilling: After you pick a candidate, it runs a grilling loop that updates CONTEXT.md, offers ADRs for rejected candidates, and explores alternative interfaces. - Use Case: Point it at a service codebase where order handling is split across six thin wrappers; it renders 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 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 and it dispatches an Explore subagent to walk the codebase, flagging modules whose interfaces are nearly as complex as their implementations. It applies the deletion test to confirm whether collapsing a module would concentrate complexity rather than just move it.

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 gets a before/after visualization, problem and solution statements, and a recommendation-strength badge.

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. The only repo changes happen later during the grilling loop, when CONTEXT.md glossary updates or new ADRs are added with your agreement.

How are ADR conflicts handled during an architecture review?▼

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

When should I not use this architecture review approach?▼

Skip it when you already know the specific refactor you want, since the Skill is designed for discovery and presentation of candidates rather than executing a predetermined change. It also depends on companion skills like codebase-design and grilling for vocabulary and follow-up design work.