improve-codebase-architecture

Identifies shallow modules in a codebase and proposes deepening refactors as an HTML report.

Updated Jun 12, 2026
One-click install
npx skills add https://github.com/taylorelley/skills --skill improve-codebase-architecture-taylorelley
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/taylorelley/skills/tree/main/skills/engineering/improve-codebase-architecture
Command: npx skills add https://github.com/taylorelley/skills --skill improve-codebase-architecture-taylorelley

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 reason about. This Skill surfaces that architectural friction and proposes concrete deepening refactors grounded in the project's own domain language and ADRs. ## Core Features & Use Cases - Architecture exploration: Uses an Explore sub-agent to find shallow modules, leaky seams, and untestable code, applying the deletion test to separate real friction from pass-throughs. - Visual HTML report: Renders candidates as a self-contained HTML file with Tailwind and Mermaid before/after diagrams, recommendation-strength badges, and ADR conflict callouts. - 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: Point it at a service where order handling is split across six tiny wrappers; it produces a report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the agent to review this codebase for architecture improvements and show the deepening opportunities as a 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. The deletion test filters real friction: if deleting a module concentrates complexity, it was earning its keep; if complexity vanishes, it was a pass-through.

What is a deep module versus a shallow module?

A deep module hides a large amount of behavior 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 anything.

How does the architecture review report get generated?

The review is written as a single self-contained HTML file in the OS temp directory, using Tailwind and Mermaid from CDNs. Each candidate gets a before/after diagram, a recommendation-strength badge, and ADR conflict callouts, then the file is opened in the browser.

Does the review respect existing ADRs and domain language?

Yes, it reads the project's CONTEXT.md glossary and ADRs first and uses that vocabulary in every suggestion. Candidates that contradict an ADR are only surfaced when the friction justifies reopening the decision, and are marked with a warning callout.

When should I not introduce a new interface or port?

Avoid a new seam when only one adapter would ever satisfy it, since a single-adapter seam is just indirection. Two adapters, typically production plus test, justify a real seam; otherwise deepen the module without adding a port.