# Scan Architecture > Produces a codebase-wide architecture and technical-debt scan, ranked by where refactoring pays off next. Run it with /scan-architecture. - Skill: `jayden-dang/scan-architecture` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add jayden-dang/scan-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/jayden-dang/scan-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: jayden-dang (https://skillmd.com/u/jayden-dang) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jayden-dang/scan-architecture --- # Improve the Architecture Scan the codebase for accumulated friction, present deepening candidates as a visual report, and carry the one the user picks into the normal spec cycle. The goal is testability and navigability — modules deep enough that their interface is the test surface. Vocabulary is strict throughout: **module, interface, implementation, seam, adapter** (plus depth/locality/leverage as qualities) — a *seam* is a public surface where behavior is both observable and substitutable (the same seam `test-first` and `design-solution` name). Never drift into "component", "service", "layer", or "boundary" — precision in the nouns is what keeps the findings comparable run over run. ## 1. Explore for friction Read `CONTEXT.md` (the domain names good seams) and `docs/adr/` (decisions not to re-litigate) first. Then dispatch an explore subagent to walk the codebase organically — no rigid checklist, just note where work hurts: - **Shallow modules** — an interface nearly as complex as the implementation behind it - **Poor locality** — one conceptual change fans out across many files - **Missing or weak seams** — places substitution is needed but impossible, or a seam exists with only one hypothetical adapter - **Untested-through-interface** — code only testable by reaching past its interface into internals Apply the **deletion test** to anything suspect: if this module vanished, how much would its callers need to know to rebuild the behavior? "Almost everything" means the module was shallow — deleting it would concentrate complexity rather than lose it. That concentration point is your candidate. **Done when:** you hold 3–7 candidates, each tied to specific modules and a named kind of friction. ## 2. Present the report REQUIRED SUB-SKILL: use `craft-page` before writing any markup. The treatment is utilitarian — a real type scale, a chosen palette, no hero — and the report is scanned, not read: the confidence badge and the before/after sketch have to read at a glance. The sketch is a primary figure: name the job `before/after structure` and follow `craft-page`'s diagram recipe (recipe-authored inline SVG is hand-built). Write a **self-contained HTML file** (inline CSS/SVG only — no external scripts, stylesheets, or CDNs) to the OS temp directory (`$TMPDIR`, falling back to `/tmp`; `%TEMP%` on Windows) as `architecture-review-.html`, so nothing lands in the repo. Open it (`open` / `xdg-open` / `start`) and tell the user the absolute path. One card per candidate: - **Files** — the modules involved (monospaced list; this report is ephemeral, so paths are fine here) - **Problem** — one sentence: what hurts and which friction kind it is - **Proposed direction** — one sentence, in the strict vocabulary: what would deepen - **Win** — bullets of at most 6 words each, named as qualities ("locality: change lands in one module", "interface shrinks, tests hit one seam") - **Confidence badge** — exactly one of `Strong` / `Worth exploring` / `Speculative` - **Before/after structure sketch** — side-by-side recipe SVG (`before/after structure`): shallow-vs-deep mass diagrams, fan-out collapses, seam lines. The sketch carries the argument; if it needs a paragraph to explain, redraw it. End with a top-recommendation section: which candidate first, one sentence why. Then ask the user which candidate they want to pursue. **Do not propose concrete interfaces yet** — the report names directions, not designs. Interface shape belongs to the clarify-decisions step, with the user in the loop. **ADR conflicts:** a candidate that contradicts an existing ADR is included only when its evidence carries a `Strong` confidence badge; below that it is dropped, not listed. An included one is marked with the ADR reference and why the decision deserves revisiting. Do not list every refactor an ADR forbids. **Done when:** the report is open in the user's browser and you have asked which candidate to pursue. ## 3. Shape the chosen candidate Once the user picks: - REQUIRED SUB-SKILL: use `clarify-decisions` — walk the shape of the deepened module one question at a time: constraints, what sits behind the new seam, which adapters are real, which tests survive. - REQUIRED SUB-SKILL: use `define-domain` for side effects as decisions land — new module named after a concept missing from `CONTEXT.md`? Add the term. Fuzzy term sharpened mid-conversation? Update it now, not later. User rejects a candidate for a load-bearing reason? Offer a 1–3 sentence ADR so future scans do not re-suggest it (skip ephemeral or self-evident reasons). - State the ceremony tier aloud — 0 for a change small enough to go straight to `test-first`, 1+ for one needing requirements first. **Done when:** `clarify-decisions` has no unexplored branch left, and the ceremony tier is stated aloud as 0 or 1+. ## 4. Feed the spec cycle Tier 0 (mechanical, no behavior change) can proceed directly under `test-first`/`prove-claim` discipline. Anything tier 1 or above: REQUIRED SUB-SKILL: use `frame-change` — hand it the shaped improvement and let it run the normal cycle to requirements; architecture work earns no exemption from the spec gate. **Done when:** the work has an owner flow — either in progress under tier 0 discipline, or handed to `frame-change`.