Architecture Review Skill
Finds code that is hard to change and proposes a smaller-interface, bigger-
implementation redesign. This is a judgment skill — no paired hook, same
posture as research-mode in skill-hook-pairing.md.
Before running
Read references/deep-module-lens.md. It is the classification lens the
review applies to every module it looks at — do not improvise a different
one.
Scope check (do this first)
This lens is for software modules with interfaces: Python/shell scripts,
plugin code, MCP servers. It does NOT fit markdown rules, canonical files, or
prose content — those don't have "interfaces" in the Ousterhout sense. If the
founder names a target that's mostly .md, say so and ask them to narrow to
a code directory.
Process
- Explore. Spawn an
Agent with subagent_type: Explore over the
target directory. Ask it to walk the code and report, per file/module:
what it does, its public surface (functions/classes/CLI flags other code
calls), and its internal complexity. Don't apply the lens yet — just
gather the shape.
- Classify with the lens. For each module the Explore pass surfaced,
run the questions in
references/deep-module-lens.md. Flag only modules
that are genuinely shallow (interface complexity close to implementation
complexity) — a small module with a small interface is fine, not a
finding.
- Propose, don't prescribe. For each real finding, sketch 1-2 concrete
redesigns using the vocabulary below. State the trade-off of each. Do not
silently pick one — that's a founder/Sana call, same as
quick-plan.md's
name-options rule.
- Write it up, don't file it. Output goes to
q-system/output/plans/architecture-review-<target-slug>-<YYYY-MM-DD>.md
(per quick-plan.md), never a GitHub issue and never auto-filed to
spillover — spillover is scoped to findings that interrupt an active
PRD/issue's work, and linear-first.md already owns where real work gets
tracked. If a finding is worth acting on, the next step is the founder or
Sana deciding whether it becomes a Linear issue or a prd-os PRD.
- No findings is a valid outcome. Say so plainly if the target directory
is already reasonably deep. Don't manufacture friction to justify the run.
Vocabulary discipline
Use: module, interface, depth, seam, adapter, leverage, locality.
Avoid: "component," "service" — too imprecise to carry the deep-module
argument.
What this is not
Not a bug finder (that's /code-review). Not a cleanup pass (that's
/simplify). Not gated, receipted work (that's prd-os) — this produces a
proposal doc for a human decision, not shipped code.
1---2name: architecture-review3description: Surfaces architectural friction in real code — shallow modules, tight coupling, untested seams — and proposes deepening refactors using Ousterhout's deep-module principle (small interface hiding a large implementation). Use when the founder says 'architecture review', 'find shallow modules', 'architectural friction', 'deep module analysis', or asks for refactor recommendations on a directory of code. Scope it to actual code (plugins/, q-system/.q-system/scripts/) — not markdown rules, canonical files, or prose.4---56# Architecture Review Skill78Finds code that is hard to change and proposes a smaller-interface, bigger-9implementation redesign. This is a judgment skill — no paired hook, same10posture as `research-mode` in `skill-hook-pairing.md`.1112## Before running1314Read `references/deep-module-lens.md`. It is the classification lens the15review applies to every module it looks at — do not improvise a different16one.1718## Scope check (do this first)1920This lens is for software modules with interfaces: Python/shell scripts,21plugin code, MCP servers. It does NOT fit markdown rules, canonical files, or22prose content — those don't have "interfaces" in the Ousterhout sense. If the23founder names a target that's mostly `.md`, say so and ask them to narrow to24a code directory.2526## Process27281. **Explore.** Spawn an `Agent` with `subagent_type: Explore` over the29 target directory. Ask it to walk the code and report, per file/module:30 what it does, its public surface (functions/classes/CLI flags other code31 calls), and its internal complexity. Don't apply the lens yet — just32 gather the shape.332. **Classify with the lens.** For each module the Explore pass surfaced,34 run the questions in `references/deep-module-lens.md`. Flag only modules35 that are genuinely shallow (interface complexity close to implementation36 complexity) — a small module with a small interface is fine, not a37 finding.383. **Propose, don't prescribe.** For each real finding, sketch 1-2 concrete39 redesigns using the vocabulary below. State the trade-off of each. Do not40 silently pick one — that's a founder/Sana call, same as `quick-plan.md`'s41 name-options rule.424. **Write it up, don't file it.** Output goes to43 `q-system/output/plans/architecture-review-<target-slug>-<YYYY-MM-DD>.md`44 (per `quick-plan.md`), never a GitHub issue and never auto-filed to45 `spillover` — spillover is scoped to findings that interrupt an *active*46 PRD/issue's work, and `linear-first.md` already owns where real work gets47 tracked. If a finding is worth acting on, the next step is the founder or48 Sana deciding whether it becomes a Linear issue or a `prd-os` PRD.495. **No findings is a valid outcome.** Say so plainly if the target directory50 is already reasonably deep. Don't manufacture friction to justify the run.5152## Vocabulary discipline5354Use: module, interface, depth, seam, adapter, leverage, locality.55Avoid: "component," "service" — too imprecise to carry the deep-module56argument.5758## What this is not5960Not a bug finder (that's `/code-review`). Not a cleanup pass (that's61`/simplify`). Not gated, receipted work (that's `prd-os`) — this produces a62proposal doc for a human decision, not shipped code.
assafkip