skills.rest
tlipoca9
tlipoca9COMMUNITY
Explore all skills by this author →
GitHub

improve-codebase-architecture

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

Updated Feb 22, 2024
Search Tags:#code analysis#refactoring#mermaid#technical debt#architecture review#deep modules#HTML report
One-click install
npx skills add https://github.com/tlipoca9/dotfiles --skill improve-codebase-architecture-tlipoca9
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/tlipoca9/dotfiles/tree/main/home/dot_agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/tlipoca9/dotfiles --skill improve-codebase-architecture-tlipoca9

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 grounded in a shared design vocabulary. ## Core Features & Use Cases - Hot-spot-driven exploration: Scopes the scan using commit history (git log) and user direction, then spawns a sub-agent to find shallow modules, seam leakage, and poor locality. - Visual HTML report: Writes a self-contained Tailwind + Mermaid report to the OS temp directory with before/after diagrams, recommendation-strength badges, and ADR conflict callouts. - Grilling loop: After the user picks a candidate, walks the decision tree via the grilling skill and keeps CONTEXT.md and ADRs current through domain-modeling. - Use Case: Run it on a service whose order intake logic is scattered across six thin wrappers; get a report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the AI to review this codebase for architecture deepening opportunities and present the candidates 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 scan recent commit history for hot spots, then explore where interfaces nearly match their implementations. It applies the deletion test: if deleting a module would concentrate complexity rather than move it, that module is a deepening candidate.

What is a deep module versus a shallow module?▼

A deep module has a small interface hiding a substantial implementation, while a shallow module's interface is nearly as complex as what it wraps. The Skill uses this vocabulary from the companion codebase-design skill to evaluate every candidate.

Does the architecture review write files into my repository?▼

No. The HTML report is written to the OS temp directory as architecture-review-<timestamp>.html and opened in your browser, so nothing lands in the repo. Only CONTEXT.md updates or ADRs you approve during the grilling loop touch the project.

How does the review handle existing ADRs?▼

Candidates that contradict an ADR are only surfaced when the friction justifies revisiting the decision, and they are marked with a warning callout referencing the ADR. Theoretical refactors an ADR forbids are not listed.

What happens after I pick a refactoring candidate?▼

The Skill invokes the grilling skill to walk a decision tree covering constraints, dependencies, module shape, and surviving tests. It also updates CONTEXT.md with new domain terms and offers to record load-bearing rejections as ADRs.

Related Skills

Explore More Software Engineering Skills→
peachestpeachest

improve-codebase-architecture

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

Community
Advanced
babuallybabually
1

improve-codebase-architecture

Analyze codebases to identify shallow modules and propose deepening opportunities.

Community
Advanced
yashs33244yashs33244
1

improve-codebase-architecture

Identify refactoring opportunities that deepen shallow modules into testable designs.

Community
Advanced
safzanpiranisafzanpirani
1

design-an-interface

Generate multiple interface designs for software modules using parallel sub-agents.

Community
Advanced