improve-codebase-architecture — In-Depth Codebase Architecture Review Skill

Skill Overview

improve-codebase-architecture scans your codebase to identify opportunities for deeper architectural improvements, produces an HTML review report with before-and-after diagrams, and then walks through the one you select step by step—the entire process does not modify a single line of code.

Use Cases

1. Routine structural maintenance: Run it every few days or whenever you have time to prevent the code structure from quietly degrading between feature-development cycles. By default, it first reviews recent commits and focuses on paths that are changing frequently rather than untouched corners.
2. Before developing a major feature: Point it at the spec you are about to implement and ask, “How can we make this change simpler?” This is the most effective way to use the skill—make room in the structure first, then start writing the feature.
3. Surveying legacy projects and adding seams: When facing a large, structurally chaotic repository—or one built up through “vibe coding”—use it to understand what the code actually looks like. You can also use it to identify missing seams before writing tests for untestable legacy code.

One boundary to note: it processes only one candidate at a time. The report may contain a dozen candidates; select one to explore, and turn the rest into independent tickets to handle in separate sessions.

Core Features

1. Scanning for opportunities to deepen: It looks for problems according to a single criterion: depth. Deep modules hide substantial behavior behind small, stable interfaces, while shallow modules have interfaces nearly as broad as their underlying implementations, meaning they hide almost nothing. The report specifically looks for three kinds of shallowness: pure functions extracted solely for testability, where the real bug lies in how they are called and there is no locality; modules leaking through their seams; and concepts that cannot be understood without opening five different files.
2. Candidate-card HTML report: Each candidate is rendered as a card containing the relevant files, points of friction, a plain-language description of the solution, benefits expressed in terms of locality and leverage, a hand-drawn before-and-after diagram, and a strength badge—Strong (the deletion test clearly passes and the candidate deserves serious consideration), Worth exploring (the direction is reasonable, but the benefits depend on where the code goes next), or Speculative (listed for completeness and probably safe to ignore). The report concludes with a “top recommendation.” It is written to the system temporary directory and does not pollute the repository.
3. Deletion test and candidate filtering: Every candidate must pass the deletion test—if this module were deleted, would the complexity be concentrated behind a smaller interface, or merely spread across its callers? Only candidates that concentrate the complexity qualify for the report. This filter is what keeps it from degenerating into generic cleanup advice.
4. Exploration after selection: Once you choose a candidate, it walks through a decision tree covering the constraints, what belongs behind the seam, which tests can survive, and what the deepened interface should look like. The output is a decision, not a diff. It also adds newly emerging domain terminology to CONTEXT.md (CONTEXT.md is created if it does not exist) and proactively suggests recording rejected candidates as ADRs so the same suggestions do not reappear the next time it runs.

It reads architectural decisions from CONTEXT.md and docs/adr/, and speaks in your project’s own terminology—the candidates will be phrased as “deepen the order integration module” rather than “refactor FooBarHandler.”

Frequently Asked Questions

Will it modify my code directly?

No. The entire process produces only an HTML file in a temporary directory and a conversation. The refactoring itself must wait for a separate session and follow the normal development process (decision → to-spec → to-tickets → implementation). That is why this counts as “reconnaissance” rather than a “refactoring tool,” and why it is worth running first on a codebase you are not yet ready to modify.

The report opens as a pile of unstyled raw HTML, and the diagrams are missing. Why?

The report loads Tailwind and Mermaid from a CDN, so it requires an internet connection when opened; if access is blocked, they fail silently. One archived case involved a security hook requiring SRI hashes: the agent added the hashes, but the bytes the CDN sent to the browser differed from the bytes retrieved by curl to calculate the hashes, so the browser blocked the scripts. Offline and restricted environments run into the same wall. The agent cannot see this phenomenon—it never renders the page. The workaround is to tell it not to use a CDN-based scaffold and instead use inline CSS and hand-crafted SVG diagrams.

It gave me twelve candidates at once. Do I need to process all of them in the same session?

One session should handle one candidate. Processing several in one conversation stuffs the report, the exploration, domain-model changes, and code changes into the same context window. The report exists only in a temporary file, so what you need to carry forward is the candidate itself, not the file: choose one, explore it, send the decision to /to-spec, and turn the rest into tickets that can be picked up independently later. When you want an improvement plan, going into a spec is more reliable than jumping straight into implementation.

How can I make it stop asking questions and just produce the report?

Say so directly when invoking it, for example: “Don’t ask me follow-up questions; just give me the report.” This is the skill’s most common complaint—some users initially appreciated how it “made it easy to get a thorough improvement analysis,” but found it “almost unusable” after the exploration phase was added, noting that in some sessions it proposed only one approach yet asked “dozens or hundreds of questions.” The intended design is to produce the report first and begin the exploration only for the candidate you select, but weaker models may skip the report and immediately interrogate you about the first idea they come up with. This issue remains unresolved: the skill currently has no documented no-exploration mode.

How is it different from /codebase-design?

/codebase-design is a reference, not a session driver. It provides the vocabulary—modules, interfaces, depth, seams, adapters, leverage, and locality—that this skill borrows. Pointing a new agent at /codebase-design and telling it to “execute it” is a known failure mode: that skill has no process of its own to follow, so the agent invents one, rescans the code, runs for a long time, and only then asks its first question. Use this skill to drive the process, and treat codebase-design as a dictionary.

How well does it work on large legacy codebases?

It is partially effective. It performs reasonably well on large, existing codebases that lack a unified structure, and it is also recommended as a routine maintenance tool after any one-time structural cleanup. But the other side should be stated plainly: some users report that on truly out-of-control projects it “helped a little, but was still nowhere near enough,” while a developer who had maintained a legacy system for eight years reported that the same skill could draw clean diagrams for a tidy repository but kept going in circles in theirs. There is currently no dedicated /refactor skill for this scenario. If the codebase does not even have a shared vocabulary, establish one first with grill-with-docs, then run this skill; the output will improve significantly.

How should I prompt it for the best results?

Prompt it with what you are going to build next. When a major feature is coming, point it at the spec and ask, “How can we make this change simpler?” An unguided run will scan hotspots on its own, which is sufficient for routine maintenance, but the report becomes actionable only when you identify a direction.

Will it tell me that “there is nothing wrong with the codebase”?

Rarely, and you should know that in advance. This skill is designed to produce findings; the framework itself pushes it toward proposing candidates rather than concluding that “everything is fine.” The strength badges are the safeguard: a report consisting entirely of Speculative candidates is its way of telling you, using the only method it has, that it did not find much.