improve-codebase-architecture

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

Updated Jul 30, 2026
One-click install
npx skills add https://github.com/j172/bid --skill improve-codebase-architecture-j172
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/j172/bid/tree/main/agent/skills/improve-codebase-architecture
Command: npx skills add https://github.com/j172/bid --skill improve-codebase-architecture-j172

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 those architectural friction points and proposes concrete deepening refactors, presented visually rather than as a wall of prose. ## Core Features & Use Cases - Hot-spot-driven exploration: Scopes the review 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 in the OS temp directory using Tailwind and Mermaid via CDN, with before/after diagrams, recommendation-strength badges, and ADR conflict callouts for each candidate. - Guided decision loop: After the user picks a candidate, runs a grilling workflow that updates the domain glossary in CONTEXT.md and offers ADRs for load-bearing rejections. - Use Case: A team notices their order intake flow is scattered across six thin wrappers. Run this Skill to get a visual report of deepening candidates, pick one, and walk through the refactor decision interactively. ## Quick Start Ask the assistant to review this codebase for architecture deepening opportunities and show the results 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 for modules whose interface is nearly as complex as their implementation. It applies the deletion test to candidates and presents each finding with a before/after diagram in an HTML report.

How to visualize architecture refactoring proposals?

The Skill writes a self-contained HTML file to the OS temp directory using Tailwind and Mermaid from CDNs. Each candidate gets a card with files, problem, solution, benefits, and a side-by-side before/after diagram.

Does the architecture review modify my repository files?

The HTML report is written to the OS temp directory, not the repo, so nothing lands in your project. During the follow-up grilling loop, CONTEXT.md may be updated and ADRs offered, but only as decisions crystallize with your input.

What happens if a proposal contradicts an existing ADR?

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

When should I not use this architecture review approach?

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