skills.rest
MichaelSolati
MichaelSolatiCOMMUNITY
Explore all skills by this author →
Website𝕏@MichaelSolatiGitHub

improve-architecture

Identify shallow, tightly-coupled modules and propose deep module refactors.

Updated Jul 22, 2025
Search Tags:#testability#technical debt#codebase analysis#code maintainability#module deepening#architecture refactoring#seam design
One-click install
npx skills add https://github.com/MichaelSolati/mkai --skill improve-architecture-michaelsolati
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-architecture
Source: https://github.com/MichaelSolati/mkai/tree/main/profiles/engineering/skills/improve-architecture
Command: npx skills add https://github.com/MichaelSolati/mkai --skill improve-architecture-michaelsolati

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill eliminates the friction of maintaining codebases with shallow, tightly-coupled modules that are hard to test and refactor, reducing long-term technical debt and making code easier for both developers and AI tools to navigate.

Core Features & Use Cases

  • Shallow Module Detection: Identifies modules where the interface is nearly as complex as the implementation, or where deleting the module would spread complexity across multiple callers instead of containing it.
  • Deepening Opportunity Recommendations: Proposes concrete refactors to consolidate scattered logic into deep modules with small, high-leverage interfaces, improving testability and concentrating changes, bugs, and knowledge in a single location.
  • ADR & Domain Alignment: All suggestions respect existing Architecture Decision Records and the project's domain glossary, avoiding redundant or conflicting recommendations for past architectural decisions.
  • Use Case Example: A development team struggling with cross-file bug fixes for payment processing logic can use this skill to identify that scattered validation functions should be consolidated into a single deep payment validation module with a clear, testable interface.

Quick Start

Use the improve-architecture skill to analyze your codebase and list the top 3 highest-impact architecture deepening opportunities for your current project domain.

Frequently Asked Questions about improve-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 module detection works by finding tightly-coupled modules where the interface is nearly as complex as the implementation, indicating that deleting the module would spread complexity across multiple callers instead of containing it.

What is the best way to reduce technical debt by deepening modules?▼

The best way to reduce technical debt through module deepening is to consolidate scattered logic into deep modules with small, high-leverage interfaces, which concentrates changes and bugs in a single location while improving test surface design.

How do I improve code maintainability when bug fixes span multiple files?▼

Improve code maintainability by consolidating scattered validation functions into a single deep module with a clear, testable interface, ensuring cross-file bug fixes are localized within one contained module.

Does architecture refactoring respect existing Architecture Decision Records?▼

Yes, architecture refactoring respects existing Architecture Decision Records and the project's domain glossary, ensuring all module deepening suggestions avoid conflicting with past architectural decisions.

How to design seams for testable code during codebase analysis?▼

Design seams for testable code by using codebase analysis to identify tightly-coupled modules, then proposing concrete refactors that create deep modules with small, high-leverage interfaces to improve the test surface design.

When should I not use module deepening for architecture refactoring?▼

Avoid module deepening when existing Architecture Decision Records define the current structure or when the project domain glossary conflicts with consolidating scattered logic, as forced refactoring would create redundant or conflicting architectural decisions.

Related Skills

Explore More Software Engineering Skills→
assofohdzassofohdz
25

improve-codebase-architecture

Identify shallow modules and propose deep-module refactors using domain glossaries and ADRs.

Community
Advanced
joelhooksjoelhooks
729

system-design

Enforce deep module boundaries and information hiding in software design.

Community
Basic
susomejiassusomejias
9

improve-codebase-architecture

Identify shallow, tightly-coupled modules in codebases.

Community
Advanced
IsKenKenYaIsKenKenYa

improve-codebase-architecture

Identify shallow-module patterns and propose interface-deepening refactors.

Community
Intermediate