improve-codebase-architecture

Scan a codebase for module deepening opportunities and present them as a visual HTML report.

1|Updated Apr 25, 2025
One-click install
npx skills add https://github.com/Gabr1elaugus700/WorkaPool --skill improve-codebase-architecture-gabr1elaugus700
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/Gabr1elaugus700/WorkaPool/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/Gabr1elaugus700/WorkaPool --skill improve-codebase-architecture-gabr1elaugus700

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making code hard to test and navigate. This Skill surfaces those architectural friction points and proposes concrete deepening refactors, so you can decide what to fix with evidence instead of gut feel. ## Core Features & Use Cases - Hot-spot-driven exploration: Scopes the scan using git history and user direction, then explores the codebase for shallow modules, seam leakage, and poor locality. - Visual HTML report: Generates a self-contained HTML file (Tailwind and Mermaid via CDN) in the OS temp directory with before/after diagrams, recommendation-strength badges, and a top recommendation. - Decision grilling loop: After you pick a candidate, walks the decision tree with the /grilling skill, keeps CONTEXT.md and ADRs current, and respects existing architectural decisions. - Use Case: Point it at a subsystem where changes keep hurting — it identifies that your order intake pipeline is six shallow wrappers deep, renders the collapse into one deep module as a diagram, and grills you through the refactor trade-offs. ## Quick Start Ask the assistant to review the architecture of the current codebase 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 architecture problems in my codebase automatically?

Run this Skill to scan your codebase for shallow modules, seam leakage, and poor locality. It scopes the search using recent git history to find hot spots, then presents each candidate refactor as a visual before/after card in an HTML report.

What is a shallow module and how do I fix it?

A shallow module has an interface nearly as complex as its implementation, adding indirection without hiding complexity. The Skill applies the deletion test to detect them and proposes deepening: collapsing wrappers into one module with a small interface and a thick implementation.

Does the architecture report write files into my repository?

No. The HTML report is written to the OS temp directory (resolved from $TMPDIR, /tmp, or %TEMP%) with a timestamped filename, so nothing lands in the repo. It is opened in your browser automatically.

What diagram tools does the HTML architecture report use?

The report uses Tailwind CSS and Mermaid, both loaded from CDNs. Mermaid renders graph-shaped diagrams like call flows and dependencies, while hand-built HTML/SVG handles editorial visuals such as mass diagrams and cross-sections.

What happens after I pick a refactoring candidate?

The Skill runs a grilling loop that walks the decision tree with you: constraints, dependencies, the shape of the deepened module, and which tests survive. It updates CONTEXT.md with new domain terms and offers to record rejected candidates as ADRs.

When should I not use this architecture review approach?

Skip it when a candidate contradicts an existing ADR without real friction to justify reopening it, or when the codebase has no clear hot spots and changes are scattered. The Skill deliberately avoids listing theoretical refactors that ADRs already forbid.