improve-codebase-architecture

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

Updated Apr 16, 2025
One-click install
npx skills add https://github.com/damoke012/eks_code --skill improve-codebase-architecture-damoke012
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/damoke012/eks_code/tree/main/.claude-env/skills/improve-codebase-architecture
Command: npx skills add https://github.com/damoke012/eks_code --skill improve-codebase-architecture-damoke012

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 finds those architectural friction points and turns them into concrete, visualized refactoring candidates instead of vague advice. ## Core Features & Use Cases - Hot-spot-driven exploration: Scopes the scan using git history and user direction, then applies the deletion test to identify shallow modules, leaking seams, and poor locality. - Visual HTML report: Generates a self-contained Tailwind + Mermaid report in the OS temp directory with before/after diagrams, recommendation-strength badges, and ADR conflict callouts for each candidate. - Guided decision loop: After the user picks a candidate, runs a grilling session on constraints and dependencies, updates the domain glossary in CONTEXT.md, and offers ADRs for rejected candidates. - Use Case: A team notices their order intake flow is spread across six tiny wrappers. Run this Skill to get a report showing the call-graph collapse, then grill through the chosen deepening before writing any code. ## Quick Start Ask the assistant to review this codebase for architecture improvements and show the deepening candidates 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 scan the codebase for 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 flagged 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 badge of Strong, Worth exploring, or Speculative.

Does the architecture review respect existing ADRs?▼

Yes, it reads ADRs in docs/adr/ before scanning and avoids re-litigating recorded decisions. A candidate that contradicts an ADR is only surfaced with a warning callout when the friction is real enough to warrant reopening the decision.

What happens after I pick a refactoring candidate?▼

The Skill starts a grilling loop covering constraints, dependencies, the deepened module's shape, and surviving tests. It updates CONTEXT.md with new domain terms and offers to record an ADR if you reject a candidate for a load-bearing reason.

When should I not run an architecture deepening review?▼

Skip it for code that rarely changes, since deepening pays off mainly in hot spots identified through recent commit history. It also does not propose interfaces upfront; interface design happens only after you select a candidate.