improve-codebase-architecture

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

3|Updated Nov 8, 2014
One-click install
npx skills add https://github.com/mintuz/.dotfiles --skill improve-codebase-architecture-mintuz
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/mintuz/.dotfiles/tree/main/agents/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/mintuz/.dotfiles --skill improve-codebase-architecture-mintuz

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: Reads CONTEXT.md and ADRs, then explores the codebase for shallow modules, seam leakage, and poor locality using a shared design vocabulary (module, interface, depth, seam, adapter, leverage, locality). - Visual HTML report: Generates a self-contained HTML file in the OS temp directory with Tailwind and Mermaid via CDN, rendering before/after diagrams, recommendation-strength badges, and a top recommendation for each candidate refactor. - Guided design grilling: After the user picks a candidate, walks the design tree, updates CONTEXT.md with new domain terms, and offers ADRs for load-bearing rejections. - Use Case: A developer suspects their order intake pipeline is over-fragmented. Run this Skill to get a visual report showing the shallow call chain, a proposed consolidated deep module, and the testability gains. ## Quick Start Ask the assistant to review this codebase for architecture deepening opportunities and show the results 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 explore the codebase for modules whose interface is nearly as complex as their implementation. It applies the deletion test to check whether removing a module would concentrate complexity, and presents each finding as a deepening candidate.

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 of Strong, Worth exploring, or Speculative.

Does the architecture review respect existing ADRs?

Yes, it reads ADRs in docs/adr before suggesting refactors 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 vocabulary does the architecture report use?

The report uses a fixed glossary: module, interface, implementation, depth, seam, adapter, leverage, and locality. It avoids substitute terms like component, service, API, or boundary, and uses domain names from CONTEXT.md for the modules discussed.

Where is the architecture review report saved?

The report is written to the OS temp directory as architecture-review-<timestamp>.html, resolved from $TMPDIR with /tmp or %TEMP% fallbacks. Nothing is written into the repository, and the file is opened in the browser automatically.