improve-codebase-architecture

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

Updated Mar 30, 2026
One-click install
npx skills add https://github.com/TrayMachi/dotfiles --skill improve-codebase-architecture-traymachi
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/TrayMachi/dotfiles/tree/main/agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/TrayMachi/dotfiles --skill improve-codebase-architecture-traymachi

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, scattering logic across tightly-coupled files and making testing and navigation difficult. This Skill explores a codebase, finds deepening opportunities, and presents them as a visual HTML report grounded in the project's domain language and existing ADRs. ## Core Features & Use Cases - Architecture exploration: Uses an Explore sub-agent to find shallow modules, leaking seams, and untestable code, applying the deletion test to validate candidates. - Visual HTML report: Generates a self-contained Tailwind and Mermaid report in the OS temp directory with before/after diagrams, recommendation-strength badges, and a top recommendation. - Grilling loop and interface design: Walks the design tree with the user, updates CONTEXT.md with new domain terms, offers ADRs for rejected candidates, and spawns parallel sub-agents to design alternative interfaces. - Use Case: Ask for an architecture review of a service whose order intake logic is spread across six small handlers; receive an HTML report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the assistant to review this codebase for architecture improvements and show the deepening candidates 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 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. Candidates are validated with the deletion test and presented as before/after diagrams in an HTML report.

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 it adds indirection without hiding complexity.

Does the architecture review respect existing ADRs?

Yes, the review reads ADRs in docs/adr/ before suggesting changes and does not re-litigate recorded decisions. A candidate that contradicts an ADR is only surfaced with a clear warning callout when the friction justifies reopening the decision.

Where is the architecture review report saved?

The report is written as a single 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 with the platform's default opener.

When should I not introduce a seam or port?

Do not introduce a seam when only one adapter exists, because a single-adapter seam is just indirection. A port is justified when at least two adapters are needed, typically a production adapter and an in-memory test adapter.