skills.rest
ralvarezdev
ralvarezdevCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

improve-codebase-architecture

Identify shallow modules and propose seam-based interface deepening refactors.

3|Updated Feb 26, 2026
Search Tags:#architecture#refactoring#testability#modularity#adapter#seams
One-click install
npx skills add https://github.com/ralvarezdev/ralvaskills --skill improve-codebase-architecture-ralvarezdev
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/ralvarezdev/ralvaskills/tree/main/skills/refactoring/improve-codebase-architecture
Command: npx skills add https://github.com/ralvarezdev/ralvaskills --skill improve-codebase-architecture-ralvarezdev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Surface architectural friction in a codebase and propose deepening opportunities that convert shallow modules into deep, testable units.

Core Features & Use Cases

  • Identify shallow seams and potential deepening candidates across a codebase.
  • Recommend one-interface-one-deep refactors using seams and adapters to improve locality and leverage.
  • Generate architecture review material aligned with CONTEXT.md and ADR guidelines to support decision-making.

Quick Start

Start by identifying a shallow module and propose a deepening plan that tightens its interface behind a seam.

Frequently Asked Questions about improve-codebase-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I identify shallow modules in my codebase for refactoring?▼

Shallow modules are identified by surfacing architectural friction where a module's interface can be tightened behind a seam using adapters. This targets refactoring scenarios to improve code locality and test leverage.

How do I refactor shallow code into deep, testable modules?▼

Refactor shallow code by proposing a deepening plan that tightens the module's interface behind a seam with adapters. This converts shallow modules into deep, testable units by improving locality and leverage across tests.

What is a shallow seam and how do adapters improve testability?▼

A shallow seam is an architectural friction point where an interface can be tightened. Using adapters at these seams deepens the module, isolating dependencies to improve locality and leverage across tests.

Does this architecture refactoring approach align with ADR guidelines?▼

Yes, architecture refactoring aligns with ADR guidelines by following domain language in CONTEXT.md and decisions in docs/adr. This ensures consistent, auditable module deepening and supports architecture review.

When should I use an adapter seam to deepen a module?▼

Use an adapter seam to deepen a module when architectural friction surfaces in a codebase. This targets refactoring scenarios where tightening a shallow interface improves locality and test leverage.

Related Skills

Explore More Software Engineering Skills→
JCE-Joshhh77JCE-Joshhh77
16

grill-with-docs

Validate planning proposals against local context and ADR files.

Community
Intermediate
joelhooksjoelhooks
729

system-design

Enforce deep module boundaries and information hiding in software design.

Community
Basic
minhtri2710minhtri2710

system-design

Guide modular decomposition and interface design for reusable software modules and APIs.

Community
Advanced
AcendWayAcendWay

improve-codebase-architecture

Identify refactoring opportunities by finding shallow modules and architectural friction.

Community
Advanced