improve-codebase-architecture

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

Updated Sep 19, 2026
One-click install
npx skills add https://github.com/Ab0umar/selrs.cc.BU --skill improve-codebase-architecture-ab0umar
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/Ab0umar/selrs.cc.BU/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/Ab0umar/selrs.cc.BU --skill improve-codebase-architecture-ab0umar

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 exploration: Walks recent commit history to find frequently changed areas, then spawns a sub-agent to detect shallow modules, seam leakage, and poor locality. - Visual HTML report: Writes a self-contained Tailwind + Mermaid report to the OS temp directory with before/after diagrams, recommendation-strength badges, and ADR conflict callouts. - Grilling loop: After the user picks a candidate, drives a decision-tree conversation covering constraints, dependencies, and test surfaces, updating CONTEXT.md and offering ADRs as decisions crystallize. - Use Case: A team notices their order intake logic is scattered across six thin wrappers. Run this Skill to get a visual report of deepening candidates, pick one, and grill through the refactor design before writing any code. ## Quick Start Ask the assistant to review this codebase for architecture deepening opportunities and show the candidates in 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 history for hot spots, then explore where interfaces nearly match their implementations. It applies the deletion test: if deleting a module would concentrate complexity rather than move it, that module is a deepening candidate.

What is a deepening refactor in software architecture?▼

A deepening refactor turns a shallow module into a deep one: a small interface hiding a large implementation. The Skill uses vocabulary from the codebase-design skill, including module, interface, depth, seam, adapter, leverage, and locality.

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 lands in the repository, and the file is opened automatically with the platform's default opener.

Does the report require any JavaScript build tooling?▼

No build tooling is required. The HTML report loads Tailwind and Mermaid from CDNs and is otherwise fully static, so it renders in any modern browser without npm installs or bundlers.

What happens if a proposed refactor contradicts an existing ADR?▼

The candidate is only surfaced when the friction is real enough to warrant revisiting the decision. The report card includes a warning callout referencing the ADR and explaining why reopening it may be justified.

When should I not use this architecture review approach?▼

Skip it for greenfield code with no commit history to reveal hot spots, or when you need immediate interface proposals. The Skill deliberately presents candidates first and only designs interfaces after you pick one and enter the grilling loop.