architecture-audit

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

6. shell_run(command=..., quiet=true) — SHIM pass Lightweight heuristic for compatibility / re-export / facade modules across languages, scoped to roots from AGENT SCAN. Distinguish deliberate public API entrypoints (keep as evidence, do not treat as debt by default) from thin leftover forwarding modules. Keep output short (cap rows).

7. architecture_cleanup_repo() ← required next tool after step 6 (Skip when step 1 used cwd and did not clone.)

8. architecture_save_observations(repo_name, observations) ← required after cleanup (or after shim when cleanup was skipped), before the final no-tool report. Ending the turn before this call skips it. observations = the complete markdown list of findings from passes 3–6 (raw heuristic evidence). repo_name = the repo slug (e.g. opensre or owner/repo).

9. Final NO-TOOL reply: fill core/agent_harness/prompts/skills/architecture_audit/architecture_audit_report.md from passes 3–6 grounded in AGENT SCAN context. Summarize; never paste huge raw dumps. Invent Recommended sequencing yourself — calibrate to the repo's stated contract, not a generic "delete every cross-module edge" story. Propose tasks; never auto-apply fixes. File GitHub issues only after approval.