improve-codebase-architecture

Identifies shallow modules and proposes deepening refactors to improve codebase testability.

Updated May 23, 2026
One-click install
npx skills add https://github.com/Oatse/CWE-Automation --skill improve-codebase-architecture-oatse
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/Oatse/CWE-Automation/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/Oatse/CWE-Automation --skill improve-codebase-architecture-oatse

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 maintain. This Skill surfaces that architectural friction and proposes deepening refactors that consolidate tightly-coupled modules behind small, high-leverage interfaces. ## Core Features & Use Cases - Deepening Opportunity Discovery: Explores the codebase with sub-agents to find shallow modules, pass-through abstractions, and tightly-coupled clusters, applying the deletion test to validate each candidate. - Structured Candidate Review: Presents numbered refactoring candidates with files, problems, solutions, and benefits framed in terms of leverage and locality, while respecting existing ADRs and domain vocabulary from CONTEXT.md. - Guided Design Conversation: Runs a grilling loop on the chosen candidate, updates CONTEXT.md with new domain terms, offers ADRs for rejected candidates, and supports parallel sub-agent exploration of alternative interface designs. - Use Case: A team struggling with scattered business logic across dozens of small functions uses this Skill to identify consolidation candidates, then designs a single deep module with a minimal interface that callers and tests both use. ## Quick Start Ask the assistant to analyze this codebase for architecture improvement opportunities and list the top deepening candidates.

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?

Use this Skill to explore the codebase for shallow modules where the interface is nearly as complex as the implementation. It applies the deletion test to each candidate and presents a numbered list of deepening opportunities with files, problems, and benefits.

What is a deep module in software architecture?

A deep module hides a large amount of behaviour behind a small interface, giving callers leverage and maintainers locality. A shallow module is the opposite: its interface is nearly as complex as its implementation, so it earns little.

How do I design a better interface for a module?

The Skill spawns multiple sub-agents in parallel, each producing a radically different interface under constraints like minimizing entry points or optimizing the common caller. It then compares the designs by depth, locality, and seam placement and gives an opinionated recommendation.

Does this refactoring approach work with existing ADRs?

Yes, the Skill reads docs/adr/ before proposing changes and avoids re-litigating recorded decisions. It only surfaces a candidate that contradicts an ADR when the friction is real enough to warrant reopening it, and marks the conflict clearly.

When should I not introduce a port or seam?

Do not introduce a seam unless at least two adapters justify it, typically production plus test. A single-adapter seam is just indirection, and the Skill treats one adapter as a hypothetical seam rather than a real one.