skills.rest
hgxszhj
hgxszhjCOMMUNITY
Explore all skills by this author →
GitHub

improve-codebase-architecture

Identify shallow modules and propose refactors to improve codebase architecture.

Updated May 7, 2026
Search Tags:#architecture#codebase#adr#refactor#domain-language#deepening#grilling
One-click install
npx skills add https://github.com/hgxszhj/mattpocock_skills --skill improve-codebase-architecture-hgxszhj
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/hgxszhj/mattpocock_skills/tree/main/skills/engineering/improve-codebase-architecture
Command: npx skills add https://github.com/hgxszhj/mattpocock_skills --skill improve-codebase-architecture-hgxszhj

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Deepening opportunities surface architectural friction and propose refactors that turn shallow modules into deep ones. The aim is to improve testability and AI-navigability in a codebase.

Core Features & Use Cases

  • Explore the codebase to identify shallow modules and friction points that hinder testing, comprehension, and AI navigation.
  • Present candidates for deepening, including problem statements, affected modules, and potential adapters or seam placements.
  • Grilling loop: iteratively discuss constraints, dependencies, and trade-offs to converge on practical deeper interfaces.

Quick Start

Run the agent in Explore mode to identify deepening opportunities across the codebase.

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 to improve codebase architecture?▼

You surface shallow modules by running the agent in Explore mode to identify deepening opportunities, analyzing architectural friction points that hinder testing, comprehension, and AI navigation across the codebase.

What is a deepening opportunity in software refactoring?▼

A deepening opportunity in software refactoring is an architectural friction point that, when addressed, turns shallow modules into deep ones, proposing refactors to improve testability and AI-navigability across the codebase.

How do I reduce coupling and increase testability across large codebases?▼

You reduce coupling and increase testability across large codebases by surfacing shallow modules and proposing refactors via deepening opportunities, relying on domain glossaries and ADR decisions to present practical deeper interfaces.

Do I need a CONTEXT.md file or ADR decisions to use this architecture refactoring approach?▼

Yes, this architecture refactoring approach relies on a domain glossary named CONTEXT.md and ADR decisions to surface deepening candidates and present them for grilling loops.

How does the grilling loop work for codebase refactoring trade-offs?▼

The grilling loop for codebase refactoring iteratively discusses constraints, dependencies, and trade-offs to converge on practical deeper interfaces, ensuring the proposed architectural changes are viable.

When should I not use deepening opportunities for codebase refactoring?▼

You should avoid using deepening opportunities for codebase refactoring if your project lacks a domain glossary CONTEXT.md or ADR decisions, as the tool relies on these to surface candidates and present them for grilling loops.

Related Skills

Explore More Software Engineering Skills→
ralvarezdevralvarezdev
3

improve-codebase-architecture

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

Community
Advanced
jorgeasaurusjorgeasaurus
12

improve-codebase-architecture

Identify and propose architectural improvements by transforming shallow modules into deep ones.

Community
Advanced
anukkrit149anukkrit149

improve-codebase-architecture

Analyze codebases to identify architectural deepening opportunities using ADR decisions and domain vocabulary.

Community
Intermediate
anonymousminatianonymousminati

improve-codebase-architecture

Analyze codebases to identify architectural friction and refactoring opportunities.

Community
Advanced