improve-codebase-architecture

Identifies shallow modules and proposes deepening refactors rendered as an HTML architecture review report.

Updated Jul 23, 2025
One-click install
npx skills add https://github.com/derrik-fleming/dotfiles --skill improve-codebase-architecture-derrik-fleming
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/derrik-fleming/dotfiles/tree/main/private_dot_agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/derrik-fleming/dotfiles --skill improve-codebase-architecture-derrik-fleming

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, navigate, and refactor. This Skill surfaces that architectural friction and proposes concrete deepening opportunities grounded in the project's own domain language and recorded decisions. ## Core Features & Use Cases - Architecture exploration: Walks the codebase with an Explore sub-agent to find shallow modules, leaking seams, and tightly-coupled clusters, applying the deletion test to each candidate. - HTML review report: Renders candidates as a self-contained Tailwind/Mermaid HTML file in the OS temp directory with before/after diagrams, recommendation-strength badges, and a top recommendation. - Grilling loop and interface design: After the user picks a candidate, drives a design conversation, updates CONTEXT.md with new domain terms, offers ADRs for rejected candidates, and can spawn parallel sub-agents to design alternative interfaces. - Use Case: Ask for an architecture review of a service whose order intake logic is scattered across six small wrappers; receive a visual report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the assistant to review this codebase's architecture and suggest deepening opportunities, then pick a candidate from the generated HTML report to explore further.

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 refactoring opportunities in a codebase?▼

Run an architecture review that explores the codebase for shallow modules whose interfaces are nearly as complex as their implementations. Each candidate is presented with a problem statement, solution, and before/after diagram so you can pick which deepening to pursue.

What is a deep module versus a shallow module?▼

A deep module hides a large amount of behaviour behind a small interface, giving callers leverage and maintainers locality. A shallow module has an interface nearly as complex as its implementation, so deleting it would make complexity vanish rather than redistribute.

How does the review handle existing architecture decision records?▼

The review reads ADRs before suggesting changes and avoids re-litigating recorded decisions. A candidate that contradicts an ADR is only surfaced when the friction justifies reopening it, and the conflict is flagged with a warning callout in the report.

Where is the architecture review report 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%, named architecture-review-<timestamp>.html. Nothing is written into the repository itself.

Can I compare alternative interface designs for a module?▼

Yes. After choosing a candidate, the interface design workflow spawns three or more parallel sub-agents, each producing a radically different interface under distinct constraints such as minimal surface or maximum flexibility. The designs are then compared by depth, locality, and seam placement with an opinionated recommendation.