improve-codebase-architecture

name

improve-codebase-architecture

description

Audit a Go codebase for deep-module architecture: package DAG, seams, ownership, locality, and shallow or leaky interfaces. Emits structured findings for a phase-wise checklist. Use when the user wants to improve architecture, deepen modules, review seams, find package leaks, or runs /improve-codebase-architecture. Do not use for deletion (ponytail), performance squeeze (perf-review), or one visual HTML/PDF bug (debug-html-template).

Improve-codebase — architecture deepening

Find places where behavior should sit behind a smaller interface. Do not implement. Do not invent plugins.

Read first: codebase-design (vocabulary), then ../references/finding-schema.md. If the module path is gowkhtmltopdf, also read ../references/gowkhtmltopdf.md.

1. Freeze scope

• Record HEAD and whether the tree is dirty. Evidence is current source. Exclude unrelated dirty files from quotes.
• Scan plans/reviews/ for open or closed rows on the same paths. Closed + unregressed → refuse, not a new defect.
• Product ceiling (this repo, and any report renderer like it): authored HTML templates, not a browser. A finding that demands JS, CGO, or Chrome parity is out of scope.

2. Discover the DAG and the intended seam

From source, not from docs:

1. Public / cmd entrypoints → the one job type the engine accepts.
2. Import direction. Flag any production import that points up toward a hub, CLI, or settings package a sink should not know.
3. Where untrusted input crosses a trust boundary.
4. Where PDF vs image (or any two adapters) are supposed to share work and where they are supposed to fork.

Docs that disagree with source are a P3 friction (stale claim), not a redesign.