improve-codebase-architecture

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

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

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 ADRs. ## Core Features & Use Cases - Architecture exploration: Uses an Explore sub-agent to find shallow modules, leaky seams, and tightly-coupled code, applying the deletion test to validate candidates. - Visual HTML report: Generates a self-contained Tailwind + 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 scattered across six thin wrappers; receive a report proposing 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.

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, leaky seams, and pass-through wrappers using the deletion test. The result is an HTML report ranking candidates by recommendation strength with before/after diagrams.

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 earns little and often just passes calls through.

How does the architecture review report get generated?▼

The review is written as a single self-contained HTML file in the OS temp directory, styled with Tailwind via CDN and diagrammed with Mermaid plus hand-built SVG. It opens automatically in the browser and never writes into the repository.

Does the review respect existing ADRs and domain language?▼

Yes. The review reads CONTEXT.md and docs/adr/ first, names modules using the project's domain vocabulary, and only surfaces ADR-contradicting candidates when the friction justifies reopening the decision, marked with a warning callout.

When should I not introduce a seam or port?▼

Avoid a seam when only one adapter exists, since a single-adapter seam is just indirection. Introduce a port only when at least two adapters are justified, typically a production adapter and an in-memory test adapter.