improve-codebase-architecture

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

Updated Sep 11, 2026
One-click install
npx skills add https://github.com/CYRUS-pinto/pi-bot --skill improve-codebase-architecture-cyrus-pinto
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/CYRUS-pinto/pi-bot/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/CYRUS-pinto/pi-bot --skill improve-codebase-architecture-cyrus-pinto

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 git history and user direction, then spawns a sub-agent to find shallow modules, seam leakage, and poor locality. - Visual HTML report: Renders each candidate as a self-contained HTML file (Tailwind and Mermaid via CDN) with before/after diagrams, recommendation strength badges, and ADR conflict callouts, written to the OS temp directory. - Grilling loop: After the user picks a candidate, walks the decision tree via the grilling skill, updating CONTEXT.md and offering ADRs as decisions crystallize. - 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 assistant 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 scan the codebase for modules whose interface is nearly as complex as their implementation. It applies the deletion test to candidates and prioritizes hot spots found in recent git history.

What does the architecture review report look like?

The report is a single self-contained HTML file written to the OS temp directory, styled with Tailwind and Mermaid from CDNs. Each candidate gets a card with files, problem, solution, benefits, a before/after diagram, and a recommendation strength badge.

Does the architecture review modify my repository files?

No. The HTML report is written to the OS temp directory so nothing lands in the repo. The only repo writes happen later during the grilling loop, when CONTEXT.md terms or ADRs are updated with your agreement.

How are ADR conflicts handled during an architecture review?

Candidates that contradict an existing ADR are only surfaced when the friction justifies revisiting the decision. They are marked with a warning callout referencing the ADR rather than listed as routine suggestions.

When should I not use this architecture review approach?

Skip it for greenfield code with no history to analyze, or when you already know the exact refactor you want. The Skill is designed for discovering and evaluating deepening opportunities, not for executing a predetermined refactor.