skills.rest
cloudofgeorge
cloudofgeorgeCOMMUNITY
Explore all skills by this author →
Website𝕏@cloudofgeorgeGitHub

improve-codebase-architecture

Scan a codebase for shallow modules and present deepening refactors as a visual HTML report.

Updated May 11, 2026
Search Tags:#code analysis#refactoring#technical debt#mermaid diagrams#architecture review#deep modules#html report
One-click install
npx skills add https://github.com/cloudofgeorge/AI-hands-Engineer --skill improve-codebase-architecture-cloudofgeorge
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/cloudofgeorge/AI-hands-Engineer/tree/main/skills/engineering/improve-codebase-architecture
Command: npx skills add https://github.com/cloudofgeorge/AI-hands-Engineer --skill improve-codebase-architecture-cloudofgeorge

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making them hard to test and navigate. This Skill surfaces that architectural friction and proposes concrete deepening refactors instead of vague cleanup advice. ## Core Features & Use Cases - Architecture exploration: Reads CONTEXT.md and ADRs, then explores the codebase with an Explore subagent to find shallow modules, seam leakage, and poor locality. - Visual HTML report: Generates a self-contained HTML file in the OS temp directory using Tailwind and Mermaid via CDN, with before/after diagrams, recommendation badges, and a top recommendation. - Grilling loop: After the user picks a candidate, runs a structured design discussion, updates CONTEXT.md, and offers ADRs for load-bearing rejections. - Use Case: Point it at a service codebase where order handling is spread across six thin wrappers; it produces a report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the agent to review this repository's architecture and show deepening opportunities as an HTML report.

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 shallow modules in my codebase?▼

Run this Skill to explore the codebase with an Explore subagent, applying the deletion test to suspect modules. It flags modules whose interface is nearly as complex as their implementation and presents each finding with a before/after diagram.

What is a deepening refactor in software architecture?▼

A deepening refactor turns a shallow module into a deep one: a small interface hiding a substantial implementation. The Skill uses vocabulary like module, seam, adapter, locality, and leverage to describe these changes precisely.

Does the architecture report get written into my repository?▼

No. The report is a self-contained HTML file written to the OS temp directory as architecture-review-<timestamp>.html, then opened in your browser. Nothing lands in the repo unless you later update CONTEXT.md or add an ADR.

How does the skill handle conflicts with existing ADRs?▼

Candidates that contradict an ADR are only surfaced when the friction justifies revisiting the decision. The report marks them with a warning callout referencing the ADR rather than listing every forbidden refactor.

What happens after I pick a refactoring candidate?▼

The Skill runs a grilling loop to walk the design tree: constraints, dependencies, module shape, and surviving tests. It updates CONTEXT.md with new domain terms and offers to record load-bearing rejections as ADRs.

Related Skills

Explore More Software Engineering Skills→
Ab0umarAb0umar

improve-codebase-architecture

Scan a codebase for module deepening opportunities and render findings as a visual HTML report.

Community
Advanced
officechbusinessservices-creatorofficechbusinessservices-creator

improve-codebase-architecture

Identify architectural friction and deepen shallow modules to improve testability.

Community
Advanced
JeromyJSmithJeromyJSmith
3

improve-codebase-architecture

Identify shallow modules and propose interface-focused refactoring candidates.

Community
Advanced
tonysyutonysyu
2

improve-codebase-architecture

Identify shallow modules to deepen for improved testability and AI navigability.

Community
Intermediate