skills.rest
RavitejaKarra24
RavitejaKarra24COMMUNITY
Explore all skills by this author →
𝕏@RavitejaKarra24GitHub

improve-codebase-architecture

Identifies shallow modules and proposes deepening refactors via an HTML architecture review report.

Updated Mar 12, 2026
Search Tags:#architecture#code review#refactoring#mermaid#modularity#coupling#html report
One-click install
npx skills add https://github.com/RavitejaKarra24/dotfiles --skill improve-codebase-architecture-ravitejakarra24
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/RavitejaKarra24/dotfiles/tree/main/agents/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/RavitejaKarra24/dotfiles --skill improve-codebase-architecture-ravitejakarra24

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules, leaky seams, and tightly-coupled code that is 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 review using git history and user direction, then explores the codebase for shallow modules, leakage across seams, and poor testability. - Visual HTML report: Generates a self-contained HTML file in the OS temp directory with Tailwind and Mermaid before/after diagrams, recommendation-strength badges, and ADR conflict callouts. - Decision workflow: Hands off to grilling, domain-modeling, and codebase-design skills to refine a chosen candidate, update CONTEXT.md, and record ADRs. - Use Case: A team notices their order intake flow is spread across six thin wrappers. Run this Skill to get a visual report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the agent to review the codebase architecture and suggest deepening opportunities, optionally naming a module or pain point to focus on.

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 architectural problems in my codebase?▼

Run this Skill to explore the codebase for shallow modules, leaky seams, and hard-to-test code. It scopes the search using recent git history hot spots or a direction you provide, then presents candidates in an HTML report.

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 its implementation. The Skill applies a deletion test to detect shallowness and proposes deepening refactors.

Does the architecture review modify my repository files?▼

No. The report is written as a self-contained HTML file to the OS temp directory, so nothing lands in the repo. CONTEXT.md or ADR updates only happen later, during the grilling loop, with your involvement.

How does the review handle existing ADRs?▼

Candidates that contradict an existing 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 runs a grilling loop to walk constraints, dependencies, and the deepened module's shape. It updates CONTEXT.md with new domain terms, offers ADRs for load-bearing rejections, and can explore alternative interface designs.

Related Skills

Explore More Software Engineering Skills→
harekihareki

improve-codebase-architecture

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

Community
Advanced
yikartyikart
25.6k

improve-codebase-architecture

Identifies shallow modules and proposes deepening refactors to improve codebase testability.

Official
Advanced
matt-rileymatt-riley
1

grill-with-docs

Elicit and record domain terms and ADR decisions during planning.

Community
Advanced
NealschNealsch

Forge-Repository-Metrics

Interprets codebase knowledge graphs into repository metrics and health indicators.

Community
Intermediate