improve-codebase-architecture

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

2|1|Updated Apr 12, 2026
One-click install
npx skills add https://github.com/brandtam/rubber-ducky-legacy --skill improve-codebase-architecture-brandtam
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/brandtam/rubber-ducky-legacy/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/brandtam/rubber-ducky-legacy --skill improve-codebase-architecture-brandtam

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, spreading bugs and knowledge across callers and making code hard to test and navigate. This Skill surfaces that architectural friction and proposes deepening refactors that consolidate behavior behind small, high-leverage interfaces. ## Core Features & Use Cases - Deepening candidate discovery: Explores the codebase with an Explore sub-agent, applies the deletion test, and presents a numbered list of refactoring opportunities with files, problems, solutions, and benefits. - Guided design conversation: Runs a grilling loop on the chosen candidate, updating CONTEXT.md domain vocabulary and offering ADRs when candidates are rejected for load-bearing reasons. - Parallel interface design: Spawns multiple sub-agents to propose radically different interfaces for a deepened module, then compares them by depth, locality, and seam placement. - Use Case: Ask it to review a service layer where five small classes each wrap one database call; it identifies the cluster as shallow, proposes a single deep repository module, and designs the interface with test adapters. ## Quick Start Ask the assistant to explore this codebase and find architecture deepening opportunities that would make it more testable.

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 this Skill to explore the codebase with an Explore sub-agent, noting shallow modules, tightly-coupled seams, and hard-to-test areas. It presents a numbered list of deepening candidates with files, problems, solutions, and benefits before proposing any interfaces.

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 deleting it just moves complexity rather than concentrating it.

How does the deletion test identify useless modules?▼

Imagine deleting the module: if complexity vanishes, it was a pass-through earning nothing; if complexity reappears across many callers, it was earning its keep. The Skill applies this test to any module suspected of being shallow.

Does this Skill respect existing architecture decision records?▼

Yes, it reads ADRs in docs/adr/ before suggesting 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 new interface or seam?▼

Avoid a seam when only one adapter would ever satisfy it, since a single-adapter seam is just indirection. The Skill's rule is that one adapter means a hypothetical seam while two adapters, typically production plus test, make it real.