Architecture review

# Mattpocock Improve Codebase Architecture > Mattpocock Improve Codebase Architecture - Skill: `nklofy/mattpocock-improve-codebase-architecture` (Agent Skill) - Install (CLI): `npx skillmds@latest add nklofy/mattpocock-improve-codebase-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/nklofy/mattpocock-improve-codebase-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: nklofy (https://skillmd.com/u/nklofy) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/nklofy/mattpocock-improve-codebase-architecture --- # Mattpocock Improve Codebase Architecture Run an architecture health pass focused on depth, locality, leverage, and testability. The output is a visual report of deepening candidates, followed by a Mattpocock Grill Me style interview for the candidate the user chooses. ## When To Use Use when tests are awkward, modules are shallow, behavior leaks across seams, or future changes require too much codebase context. ## Core Idea Architecture work should make future behavior easier to add and verify. The target is not aesthetic cleanup; the target is deeper modules: smaller interfaces hiding more behavior, with tests crossing the same seams as callers. ## Inputs Read what exists: - `CONTEXT.md` or `CONTEXT-MAP.md` - relevant ADRs in `docs/adr/` - build/test scripts - the modules near the user's area of concern, or the highest-churn areas if no area is specified Proceed silently when domain docs are absent. ## Explore Look for friction, not just smells: - understanding one behavior requires bouncing across many files - tests must mock internal collaborators - call sites repeat the same ordering, validation, or data-shaping knowledge - modules are shallow: their interface is nearly as complex as their implementation - external integrations leak through multiple callers - a seam exists with only one adapter and no real variation - code is hard to test except by poking internals Use the `mattpocock-codebase-design` vocabulary exactly: module, interface, implementation, depth, seam, adapter, leverage, locality. ## Candidate Shape Each candidate should include: - **Files**: the involved modules - **Problem**: the friction in current terms - **Proposed deepening**: what behavior moves behind which interface - **Dependency category**: in-process, local-substitutable, owned remote, or true external - **Testing effect**: what tests can move to the new interface - **Recommendation strength**: Strong, Worth exploring, or Speculative - **ADR conflict**: only when a real existing decision would be reopened Do not propose a final interface in the first report. The report selects a problem; the Mattpocock Grill Me interview loop designs the solution. ## Report Write a self-contained HTML report outside the repo: - macOS/Linux: use `$TMPDIR` if set, otherwise `/tmp` - Windows: use `%TEMP%` - write to `architecture-review-.html` Open it for the user and provide the absolute path. The report should be visual and concise. Use plain HTML and CSS so the file works offline in locked-down environments. - plain HTML/CSS for layout - inline SVG or simple boxes for before/after diagrams - side-by-side before/after view for each candidate - one top recommendation at the end Minimal scaffold: ```html Architecture review

``` Candidate cards should be sparse. The diagram should do most of the work. ## After The Report Ask: ```text Which candidate would you like to explore? ``` When the user picks one, run the Mattpocock Grill Me interview loop: - clarify what the new module owns - choose the seam - decide dependencies and adapters - define what tests cross the interface - record new domain terms through `mattpocock-domain-modeling` - offer an ADR only for durable, surprising trade-offs If the user wants alternative interfaces, use the `mattpocock-codebase-design` "design it twice" pattern: compare at least two materially different interface shapes and recommend one. ## Non-Goals - Do not mass-refactor during the review. - Do not list cosmetic cleanup. - Do not create interfaces just for their own sake. - Do not reopen ADRs unless current friction is strong enough to justify it.