skills.rest
drshailesh88
drshailesh88COMMUNITY
Explore all skills by this author →
GitHub

improve-codebase-architecture

Identify shallow, tightly coupled modules and propose deepening refactors with RFC-style GitHub issues.

Updated Mar 30, 2026
Search Tags:#refactoring#testability#code architecture#ports and adapters#dependency boundaries#GitHub RFC#deep module
One-click install
npx skills add https://github.com/drshailesh88/build_playbook --skill improve-codebase-architecture-drshailesh88
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/drshailesh88/build_playbook/tree/main/vendor/mattpocock-skills/improve-codebase-architecture
Command: npx skills add https://github.com/drshailesh88/build_playbook --skill improve-codebase-architecture-drshailesh88

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Architectural drift and shallow, tightly coupled modules make a codebase hard to understand, hard to test, and risky to change, hiding bugs in the seams between components.

Core Features & Use Cases

  • Codebase architectural exploration: Uses agentic navigation to locate friction points such as confusing module boundaries, coupling hotspots, and untestable seams.
  • Deepening opportunity proposals: Produces multiple refactor candidates, explaining coupling causes, dependency categories, and how boundary tests would replace shallow tests.
  • Multi-interface design for the same refactor goal: Proposes 3+ radically different deepening interfaces, including a ports-and-adapters oriented option when appropriate, then recommends a strongest design.
  • RFC-style GitHub issue output: Converts the selected interface into an issue using an explicit RFC template to drive implementation alignment.

Quick Start

Use improve-codebase-architecture to analyze your repository and generate a GitHub issue RFC for deepening a specific set of modules to improve testability.

Frequently Asked Questions about improve-codebase-architecture

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

FAQPage Schema
How do I refactor shallow and tightly coupled modules to improve code architecture?▼

Deepening refactors shift testing to stable boundary interfaces by consolidating seams and reducing integration risk. This architectural approach targets shallow, tightly coupled modules to make behavior more testable and the system safer to change.

What is the best way to identify coupling hotspots and untestable seams in a codebase?▼

Organic codebase exploration locates friction points like confusing module boundaries, coupling hotspots, and untestable seams. Candidates are then ranked using dependency-category assessment to prioritize the most impactful deepening refactors.

How do I use ports and adapters to design deep module interfaces for refactoring?▼

You propose multiple radically different deepening interface designs, including a ports-and-adapters oriented option when relevant, then evaluate and recommend the strongest design to consolidate seams and reduce integration risk.

How do I create a GitHub RFC issue for a codebase architecture refactoring proposal?▼

Convert the selected deepening interface design into an issue using an explicit RFC template to drive implementation alignment. This converts architectural refactoring proposals into actionable, RFC-compliant GitHub issues.

Does this codebase architecture refactoring approach work for AI-navigable agent workflows?▼

Yes, this approach makes the system more AI-navigable for future agent workflows. By deepening brittle modules and establishing stable boundary interfaces, agents can more reliably navigate and interact with the codebase.

Related Skills

Explore More Software Engineering Skills→
wesleyegbertowesleyegberto
3

codebase-improve-architecture

Identify architectural friction in codebases and propose RFC-ready deepening opportunities for improved testability.

Community
Advanced
VoDaiLoczVoDaiLocz
24

improve-codebase-architecture

Analyze codebases to identify shallow modules and suggest refactoring opportunities.

Community
Advanced
sridsrid
25

lowy

Identifies axes of change in modules using volatility-based decomposition.

Community
Advanced
jankneumannjankneumann
4

tech-debt-analysis

Analyze codebase complexity, coupling, duplication, and import issues to generate markdown and JSON reports.

Community
Advanced