improve-codebase-architecture

Scans a codebase for shallow modules and presents deepening opportunities in a visual HTML report.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making code hard to test and hard for both humans and AI to navigate. This Skill surfaces that architectural friction and proposes concrete deepening refactors grounded in a shared design vocabulary. ## Core Features & Use Cases - Hot-spot-driven exploration: Scopes the scan using recent commit history (git log) or a user-named direction, then spawns a sub-agent to find shallow modules, seam leakage, and poor locality. - Visual HTML report: Renders each candidate as a before/after card in a self-contained HTML file (Tailwind + Mermaid via CDN) written to the OS temp directory, with recommendation-strength badges and ADR-conflict callouts. - Grilling loop: After the user picks a candidate, runs a decision-tree interview and keeps CONTEXT.md and ADRs current as decisions crystallize. - Use Case: A team notices their order intake flow is spread across six thin wrappers. Run this Skill to get a visual report of deepening candidates, pick one, and grill the design down to a single deep module with one testable interface. ## Quick Start Ask the agent to scan this repository for architecture deepening opportunities and present them 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 recent commit hot spots and walk the codebase with a sub-agent, applying the deletion test to detect modules whose interface nearly matches their implementation. Results appear as ranked deepening candidates in an HTML report.

What is a deep module versus a shallow module?▼

A deep module hides a large implementation behind a small interface, while a shallow module's interface is nearly as complex as what it wraps. The Skill uses this vocabulary from the codebase-design skill, along with seam, adapter, leverage, and locality.

Does the architecture report write files into my repository?▼

No. The report is a self-contained HTML file written to the OS temp directory (resolved from $TMPDIR, /tmp, or %TEMP%) and opened in your browser, so nothing lands in the repo.

How does the skill handle conflicts with existing ADRs?▼

Candidates that contradict an ADR are only surfaced when the friction justifies revisiting the decision, and they are marked with a warning callout referencing the ADR. Theoretical refactors an ADR forbids are not listed.

When should I not use this architecture review approach?▼

Skip it when the codebase has no clear change hot spots and no testability pain, since deepening only pays off where future changes are likely. It also does not propose interfaces directly; that happens in the follow-up grilling and codebase-design steps.