iusztinpaul/squid/squid-architecture-review

Agent(
  subagent_type="Explore",
  prompt="""Architecture mapping pass on {scope}.
 
  Produce four artefacts:
  (1) Module / package list with one-line responsibility per module (file:line for the canonical entry point).
  (2) Dependency graph — who imports whom. Flag any cycles. Flag any "junk drawer" modules imported by everyone.
  (3) Layering — name the de-facto layers (e.g., handlers → services → repositories → models) and list any layer-skipping imports.
  (4) Public surface — what's exported / consumed by other components or external callers. Mark anything intended-internal that's leaked.
 
  Be exhaustive on the dependency graph; missing an edge produces a wrong recommendation. Report as four sections."""
)
 
Agent(
  subagent_type="Explore",
  prompt="""Hot-spot scan on {scope}.
 
  Find:
  (1) Files with > 500 lines.
  (2) Files / modules touched by > 30% of commits in the last 6 months — `git log --since='6 months ago' --name-only | sort | uniq -c | sort -rn | head -20`.
  (3) Tests with > 100 setup lines or > 5 fixtures — usually a smell that the system-under-test is too coupled.
  (4) `# TODO` / `# FIXME` / `# HACK` markers — count and cluster.
  (5) Any `# type: ignore` / `eslint-disable` / `nolint` clusters — places where the team is fighting their own static analysis.
 
  Report as five sections with file:line."""
)

# Architecture review — {scope}, {YYYY-MM-DD}
 
**Scope:** {whole repo / component / path}
**ADRs read:** {N} ({list, e.g. "0001–0007"})
**Findings:** {N total — by severity: S1×N, S2×N, S3×N, S4×N}
 
## Summary
 
{2–3 sentences. The headline shape: "Three module cycles between auth/ and core/, all introduced in the last 4 months, blocking the planned auth-extraction work. Tests on the affected modules have grown 2× in setup size. No ADR governs the boundary. Recommend ADR + extraction refactor."}
 
## Findings
 
### F1 — {one-line title} (S{1–4}, effort: {S/M/L}, confidence: {H/M/L})
 
**Where:** `path/to/a.py:42`, `path/to/b.py:117`
 
**Symptom:** {what is concretely wrong, observable}
 
**Root cause hypothesis:** {your best read on why}
 
**Proposed refactor:** {one paragraph; the shape of the fix, not the fix itself}
 
**ADR exposure:** {does an ADR govern this? if yes, cite. If no, an ADR should accompany the refactor.}
 
**Out of scope (explicit):** {what this finding is NOT recommending}
 
### F2 — ...
 
(Repeat for each finding, top to bottom by priority.)
 
## Not recommended
 
{Smells you found but are deliberately NOT proposing. State why — e.g., "F-skip-1: The `utils/strings.py` module has 12 unrelated functions and looks like a junk drawer. Skipping because every function is < 10 lines and the cost of splitting exceeds the reading cost."}
 
## Pre-existing decisions (from ADRs) you should NOT undo
 
{One-bullet-each summary of ADRs that explain *why* something looks weird but is intentional. This protects the next reader from re-litigating.}
 
## Suggested order of operations
 
1.F{best-first} — {why it goes first}
2.F{next} — {why}
...
 
Pick up a finding with `/squid-refactor F{N}`; run the top 1–3 first, not all at once.

## Architecture review complete — {scope}
 
**Report:** {path or issue URL}
**Findings:** {N} ({severity breakdown})
**Top recommendation:** F1 — {title}
 
### Recommended next step
 
`/squid-refactor F1` (or paste the F1 body into a fresh `/squid-refactor` invocation). The first finding is the highest leverage by severity-over-effort.
 
### Open question (if applicable)
 
{Anything you found but couldn't conclude on without team input — e.g., "F4 hinges on whether the auth/billing boundary should be a hard-coded contract or a feature-flag-toggled split. Surfacing for team decision before refactoring."}
 
### ADR action
 
{One of:}
-"Recommend ADR-{NNNN} to record the resolution of F{X} when its refactor lands."
-"No ADRs in `docs/adr/` — recommend bootstrapping with the `adr` spec (`squid-scaffold/specs/adr.md`) before proceeding so this review's findings stay durable."