skills.rest
ninthday
ninthdayCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

improve-codebase-architecture

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

Updated Mar 30, 2026
Search Tags:#code quality#refactoring#mermaid#adr#architecture review#deep modules#html report
One-click install
npx skills add https://github.com/ninthday/skills-base --skill improve-codebase-architecture-ninthday
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/ninthday/skills-base/tree/main/skills/improve-codebase-architecture
Command: npx skills add https://github.com/ninthday/skills-base --skill improve-codebase-architecture-ninthday

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 grounded in a shared design vocabulary. ## Core Features & Use Cases - Hot-spot-driven exploration: Scopes the review using git history and user direction, then spawns a sub-agent to find shallow modules, seam leakage, and poor testability. - Visual HTML report: Writes a self-contained Tailwind and Mermaid report to the OS temp directory with before/after diagrams, recommendation badges, and a top recommendation. - Grilling loop: After the user picks a candidate, stress-tests the decision, updates CONTEXT.md, and offers ADRs for load-bearing rejections. - Use Case: Point it at a subsystem where bugs keep recurring; it identifies that pricing logic leaks across a seam and renders a before/after diagram showing one deep module with a single testable interface. ## Quick Start Ask the assistant to review the current codebase for architecture deepening opportunities and open the generated 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 architecture improvement opportunities in my codebase?▼

Run this Skill to scan the codebase for shallow modules, seam leakage, and untestable interfaces. It scopes the review using recent git history hot spots, then presents candidates as a visual HTML report with before/after diagrams.

What is a deep module versus a shallow module?▼

A shallow module has an interface nearly as complex as its implementation, offering little leverage. A deep module hides significant implementation behind a small interface, concentrating bugs in one place and making the interface the natural test surface.

Where does the architecture review report get saved?▼

The report is written as a self-contained HTML file to the OS temp directory, resolved from $TMPDIR with fallback to /tmp or %TEMP%. Nothing is written into the repository, and the file is opened automatically with the system default browser.

Does the architecture review respect existing ADRs?▼

Yes, it reads ADRs in docs/adr/ before proposing changes 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 happens after I pick a candidate from the report?▼

The Skill enters a grilling loop that stress-tests the chosen refactor's constraints, dependencies, and module shape. It updates CONTEXT.md with new domain terms and offers to record an ADR when a candidate is rejected for a load-bearing reason.

Related Skills

Explore More Software Engineering Skills→
sumpalabssumpalabs
10

improve-codebase-architecture

Identify shallow, tightly-coupled modules for consolidation aligned with ADRs and domain glossary.

Official
Advanced
JeromyJSmithJeromyJSmith
3

improve-codebase-architecture

Identify shallow modules and propose interface-focused refactoring candidates.

Community
Advanced
tonombtonomb

improve-codebase-architecture

Analyze dependency graphs and refactor shallow modules into deep architectures.

Community
Advanced
laozhong86laozhong86
1

gxpm-prototype

Build throwaway prototypes to validate data model, state machine, or UI design questions.

Community
Intermediate