architecture-audit

name	architecture-audit
description	Architecture audit / layering scan of a repo with AGENT SCAN, heuristic passes, and a filled REPORT TEMPLATE
demo	Audit this repo's architecture and give me a sequenced refactor plan

══════════════════════════════════════════════════════════ ARCHITECTURE AUDIT SKILL — interactive-shell action agent: ══════════════════════════════════════════════════════════

WHEN TO USE (call this skill when the user ask matches any of these):

• Architecture audit / architecture review / architecture violations
• Structural summary of a codebase (what it does, hotspots, debt themes, recommended refactor sequencing) — not a one-line README paraphrase
• Phrases like: "audit Tracer-Cloud/opensre", "find architecture issues", "summarize this repo's architecture", "what's wrong with the layering", "find huge files / shims", "architecture report for owner/repo"

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.

HARD RULES (violating any = failed turn):

• Never end the turn with shell_run as the last tool — final reply is the filled REPORT TEMPLATE (exact headings; - none for empty lists).
• Every shell_run in this skill MUST pass quiet=true (hide $ / stdout in the terminal; results still return to you).
• Order: AGENT SCAN before heuristics (≤3 shell_run; use discovered roots, do not assume source/include) → 4 separate heuristic shell_run passes → cleanup → architecture_save_observations (passes 3–6 only; path ~/.opensre/{session_id}/{repo_name}-architecture-audit-{uuid}.md) → no-tool report.
• Cap heuristic stdout (about 15–25 lines); You write each bash command; leave no clone on disk. Budget: clone + ≤3 agent-scan shell_run + 4 heuristic shell passes + cleanup
  • save observations + final report.

STEP LABELING RULES (UX) — this skill hides its shell output (quiet=true), so narrate the 9 steps of the compact sequence:

• Before every step's tool calls, emit this exact header format as assistant text in the SAME response as the tool calls, then one short status sentence:

  [n/9]

• Never start tool calls for a new step without its header.
• After a step's tool results are in, state its outcome in one line (start it with ✓ on success, ✗ plus what failed otherwise) before the next step's header.
• Use the step's own number as n and a short name (e.g. ### [2/9] Agent scan, ### [3/9] Import pass), even when a step is skipped or trivial (a ✓ line with no tool calls is fine); never renumber mid-run.

Compact sequence:

1. 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.)

2. 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.

3. 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.

4. 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.

5. 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.