improve-codebase-architecture

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

1|Updated Mar 2, 2025
One-click install
npx skills add https://github.com/marjorg/setup --skill improve-codebase-architecture-marjorg
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/marjorg/setup/tree/main/home/.agents/skills/archive/0-matt/improve-codebase-architecture
Command: npx skills add https://github.com/marjorg/setup --skill improve-codebase-architecture-marjorg

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 scan using git history and user direction, then walks the codebase for shallow modules, seam leakage, and poor testability. - Visual HTML report: Renders each candidate refactor as a self-contained HTML file with Tailwind and Mermaid before/after diagrams, recommendation badges, and ADR conflict callouts, written to the OS temp directory. - Grilling loop: After the user picks a candidate, walks the decision tree with companion skills (grilling, codebase-design, domain-modeling) and keeps CONTEXT.md and ADRs current. - Use Case: Point it at a subsystem where changes keep clustering; it identifies that the Order intake pipeline is shallow, shows a before/after diagram collapsing six wrappers into one deep module, and grills you through the resulting design. ## Quick Start Ask the assistant to review the architecture of the current codebase and present deepening opportunities 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 walk the codebase looking for modules whose interface is nearly as complex as their implementation. It applies the deletion test to candidates and prioritizes hot spots found in recent git history.

What does the architecture review report look like?

The report is a single self-contained HTML file written to the OS temp directory, styled with Tailwind via CDN. Each candidate gets a card with files, problem, solution, benefits, a before/after Mermaid or hand-built diagram, and a recommendation strength badge.

Does the architecture review modify my repository files?

No, the HTML report is written to the OS temp directory so nothing lands in the repo. The only intentional repo writes are updates to CONTEXT.md and optionally new ADRs when decisions crystallize during the grilling phase.

How are ADR conflicts handled during architecture review?

Candidates that contradict an existing ADR are only surfaced when the friction justifies revisiting the decision. They are marked with a warning callout in the report rather than listing every refactor an ADR forbids.

What happens after I pick a refactoring candidate?

The Skill enters a grilling loop that walks the decision tree: constraints, dependencies, the shape of the deepened module, and which tests survive. It updates CONTEXT.md with new domain terms and offers to record load-bearing rejections as ADRs.