Use Improve Codebase Architecture by Matt Pocock to survey the parts of a repository that are difficult to change or test. Review a visual report of candidate module improvements, choose one grounded in actual friction, and explore its design before authorizing a refactor.
Name a maintenance hotspot, difficult test boundary, or concept scattered across files. Ask for evidence-backed architectural candidates and their dependency impact, with a design discussion before migration scope is chosen rather than an immediate repository-wide rewrite.
Name recurring changes, difficult dependencies, and existing architecture decisions.
Copy the request into a new Floatboat conversation and provide the required material.
Download FloatboatPreview and copy the request. It is not sent automatically from this page.
Reference: Improve Codebase Architecture https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/SKILL.md Read the original documentation and check the current environment and dependencies. Propose any new installation or tool connection before proceeding. My task: Survey the order-import subsystem for architecture friction. Respect existing ADRs, show candidate improvements first, and do not refactor until I choose one. Expected deliverable: Candidate improvements with supporting code evidence and tradeoffs, awaiting your selection.
Improve Codebase Architecture is a user-invoked survey in Matt Pocock’s collection. It examines a named area or recent change hotspots for shallow modules, leaking seams, and testing friction. The agent presents candidate improvements in an HTML report with affected files, before-and-after views, and recommendation strength. You choose which candidate deserves further discussion; the source does not begin by redesigning every interface. Its later interview uses grilling, codebase-design, and domain-modeling, consulting the project glossary and architectural decisions. This is a way to identify and examine worthwhile changes, not proof that a proposed architecture is better or permission to rewrite the repository.
Repeated edits, tests coupled to internals, and scattered concepts provide different clues about architecture. Compare maintenance evidence before selecting a new module boundary, rather than adding abstractions simply because the code could be reorganized.
A frequently changing module deserves investigation through recent commits and repeated rework, not an immediate rewrite. Look for the specific maintenance costs behind the hotspot and compare improvement candidates against that history. The proposal should explain what recurring burden it removes and which evidence supports making the change.
Tests that depend on private details may reveal an interface that exposes too little useful behavior. Compare those tests with the public behavior they are meant to verify, then propose a better boundary or testing seam. Establish the architectural problem before committing to rewriting the entire test suite.
Understanding one concept across many files can create a real navigation and maintenance burden. Trace the paths needed to follow that concept and examine whether cohesion or layering could reduce the cost. Compare proposed boundaries with existing dependencies so consolidation does not merely move complexity elsewhere.
A suggested extraction may reduce one file while increasing coupling for its callers. Compare the candidate with actual dependencies, public behavior, and maintenance history before committing to it. Use the architecture discussion to explain what becomes easier and what cost moves elsewhere, leaving implementation scope open until the boundary has a defensible reason to exist.
Architectural improvement begins with a subsystem or maintenance problem, not a replacement design. Investigate the code and prior decisions, review candidate boundaries, and select one for a design discussion before defining migration scope and verification.
Name an area or pain point and provide existing domain docs. Let recent change history inform the scope when no area is specified.
Inspect the affected files, friction, proposed direction, and visual comparisons. Distinguish strong recommendations from speculative ones.
Choose a candidate for the dependent-decision interview. Agree the intended interface, preserved behavior, and validation before refactoring.
Read another Skill guide and check its original source before using it.
