══════════════════════════════════════════════════════════
ARCHITECTURE AUDIT SKILL — interactive-shell action agent:
══════════════════════════════════════════════════════════
Do NOT use this skill for: live incident RCA, metric/log queries, deploying,
or ordinary chat that only needs a short verbal overview with no scan.
STEP LABELING RULES (UX) — this skill hides its shell output (quiet=true), so
narrate the 9 steps of the compact sequence:
-
architecture_clone_repo(owner, repo, ref?)
→ workspace_root = /opensre/workspace
(If already in the target checkout and no owner/repo named, skip clone and
use cwd as workspace_root; then skip cleanup.)
-
AGENT SCAN — orient on the repo before heuristics (max 3 shell_run,
each with quiet=true)
Purpose: learn enough layout/docs context that later passes hit the right
trees — not to invent a parallel findings dump.
From workspace_root (repo root), discover top-level packages and where
source vs public headers vs API/schema trees live. Prefer CONTEXT.md and
ADRs in areas you touch; if missing, fall back to AGENTS.md,
ARCHITECTURE.md, DECISIONS.md, docs/adr/, CONTRIBUTING.md layout notes,
or nearest equivalents. Note "none found" when absent.
Explore organically (≤3 shell_run total) and note early friction that
should steer later probes:
- Where does understanding one concept require bouncing between many
small modules?
- Where are modules shallow — interface nearly as complex as the
implementation?
- Where have pure functions been extracted just for testability, but
the real bugs hide in how they're called (no locality)?
- Where do tightly-coupled modules leak across their seams?
- Which parts are untested, or hard to test through their current
interface?
Apply the deletion test to anything you suspect is shallow: would
deleting it concentrate complexity, or just move it? A "yes,
concentrates" is the signal you want.
Carry the discovered roots/contracts into steps 3–6.
-
shell_run(command=..., quiet=true) — IMPORT pass
Using AGENT SCAN layout/docs, discover the repo's stated layer/module
import contract from layout + docs (AGENTS.md, ARCHITECTURE.md,
CONTRIBUTING.md, build files, package maps), then gather evidence of
cross-boundary imports that contradict that contract. Prefer the target
repo's own rules. Treat composition roots / intentional wiring as allowed
when the docs imply it; do not invent a stricter graph. Cap rows.
-
shell_run(command=..., quiet=true) — PLACEMENT pass
Using AGENT SCAN layout, discover the repo's package/module placement
contract from top-level layout, build/module definition files
(settings.gradle, go.mod, Cargo.toml, pyproject.toml, package.json
workspaces, Bazel/Pants/Nx, etc.), and AGENTS-style docs. Report only
placements that contradict those contracts, with paths + the rule they
break. Cap rows.
-
shell_run(command=..., quiet=true) — SIZE pass
Decide what "large" means for this repo/request. Prefer a threshold the
user named; otherwise choose a sensible bar from context (top outliers,
percentile, or a justified line-count cutoff). State the chosen definition
in the report. Scan source files of ANY language (e.g. .py, .go, .ts,
.tsx, .js, .jsx, .java, .rs, .rb, .php, .cs, .kt, .swift, .c, .cc, .cpp,
.h, .hpp, .scala, .sh) — do NOT limit to Python and do NOT skip non-Python
sources. Prefer primary source roots discovered in AGENT SCAN; skip only
noise dirs: tests, docs, examples, caches, .venv, node_modules, dist,
build, vendor lock dirs, and binary/media assets (images, fonts,
lockfiles, generated minified bundles). Cap rows.
