{
  "version": "act 1.0.17",
  "slug": "architecture-audit",
  "name": "architecture-audit",
  "description": "Use when asked to audit architecture, produce a comprehensive architectural overview, get the full structural picture of a codebase, assess overall health and porting readiness, find module boundaries, circular dependencies, coupling hotspots, dead code, or code patterns. Depth 3 \u2014 full audit with hypothesis-driven investigation. Replaces the architectural-analysis skill.",
  "url": "https://act101.ai/docs/skills/architecture-audit",
  "body_md": "# Architecture Audit\n\n**Depth:** Level 3 (Full Audit).\n\nSee `../analysis-protocol/references/protocol.md` for: artifact directory structure,\nthe investigation loop, depth levels, summary format, token budget rules, and project\nmap structure. Read that document before proceeding.\n\n## Phase 1: Parallel Tool Dispatch\n\nDispatch all available tools in a **single parallel batch** \u2014 never sequentially.\nEach subagent runs one tool, saves raw JSON to `raw/<tool-name>.json`, returns a\nstructured summary.\n\n**Must-have tools (report is not useful without at least some of these):**\n\n| Tool | Purpose | MCP call |\n|------|---------|----------|\n| `analyze_clusters` | Module groupings | `analyze_clusters` |\n| `analyze_coupling` | Instability rankings | `analyze_coupling` (sort: instability) |\n| `analyze_cycles` | Circular dependencies | `analyze_cycles` |\n| `analyze_seams` | Natural boundaries | `analyze_seams` |\n| `analyze_dead_code` | Unreachable symbols | `analyze_dead_code` |\n| `analyze_patterns` | Structural smells | `analyze_patterns` |\n| `analyze_export` | Codebase dimensions | `analyze_export` |\n\n**Extended tools (use if available, skip and note in manifest if not):**\n\n| Tool | Purpose | MCP call |\n|------|---------|----------|\n| `analyze_layers` | Layer detection + violations (S1+S2) | `analyze_layers` |\n| `analyze_hotspots` | Complexity ranking (H1) | `analyze_hotspots` |\n| `analyze_cohesion` | Internal relatedness (H2) | `analyze_cohesion` |\n| `analyze_chokepoints` | Betweenness centrality (R4) | `analyze_chokepoints` |\n| `analyze_stability` | Stability index + violations (R2+R3) | `analyze_stability` |\n| `analyze_roles` | Module role classification (S3) | `analyze_roles` |\n| `analyze_entry_points` | Application entry points (S5) | `analyze_entry_points` |\n\n## Phase 2: Smell Taxonomy + Hypothesis Formation\n\nBefore dispatching any investigation subagents, form explicit hypotheses using this\ntaxonomy. One module appearing in multiple columns is a stronger signal.\n\n| Evidence pattern | Architectural smell | Confirming query |\n|-----------------|--------------------|--------------------|\n| High instability + appears in cycle | God object / hub | `skeleton` + `interface` \u2014 is the API surface wider than the abstraction warrants? |\n| High instability + wide seam API | Leaky abstraction | `analyze_surface` at boundary \u2014 count unrelated symbols crossing it |\n| Large cluster + low cohesion score | Accidental cluster / false boundary | `skeleton` on cluster members \u2014 do they share a concept? |\n| Cycle length > 3 | Tightly-coupled subsystem | `analyze_surface --files <members>` \u2014 find the minimum cut |\n| Single-file cluster | Orphan / orphaned extract | `references` \u2014 does anything depend on this module? |\n| Dead code in frequently-modified file | Zombie code / incomplete refactor | `symbols` + `references` \u2014 confirm no live callers |\n| Pattern hotspot + high instability | Design debt accumulation point | `skeleton` \u2014 does the file serve multiple unrelated concerns? |\n| Module instability = 1.0, many dependents | Unstable abstraction | `interface` \u2014 is this a leaf that should be stable? |\n| Seam API surface > 10 symbols | Wide interface / tight coupling | `analyze_surface` \u2014 which symbols cross; can the seam be narrowed? |\n| No cycles but very large clusters | Low cohesion, high coupling within cluster | `analyze_coupling` within cluster |\n| High centrality + low cohesion | Overloaded chokepoint | `skeleton` \u2014 is this file doing too many things? |\n| Layer violations + high coupling | Architectural erosion | `graph` \u2014 trace the violation path, assess if structural or incidental |\n\n**Anomaly flags \u2014 investigate regardless of smell match:**\n- Cluster containing 1 file (orphan or misclassified)\n- Cluster containing >30% of all files (god cluster)\n- All instability scores near 0 or near 1 (degenerate dependency structure)\n- Seam with 0 API symbols (disconnected component)\n- Dead code in a file that is also in a cycle (phantom dependency)\n- Zero cycles in a codebase >100 files (suspiciously clean)\n\n## Phase 3: Full Audit Synthesis\n\nAfter all investigation subagents return:\n\n1. **Cross-reference findings** across all categories \u2014 a module appearing in hotspots,\n   coupling, AND cycles is a compounding risk\n2. **Build evidence chains** \u2014 not \"instability = 0.94\" but \"module X has instability\n   0.94, is in 2 cycles, and its API surface exposes 23 symbols across a seam to\n   cluster B \u2014 skeleton shows it handles both auth and request routing, confirming\n   god-object smell\"\n3. **Note negative space** \u2014 absence of expected problems is a meaningful finding\n4. Write `report.md`, update `project-map.md` (full rewrite of all sections)\n\n## Report Structure\n\n```markdown\n# Architecture Audit: <project name>\n\n## Overview\nFiles, symbols, languages, analysis date.\n\n## Executive Summary\n2-3 sentence assessment. Explicit verdict: **Ready** / **Needs work** / **Not ready**.\nOne-sentence justification for the verdict.\n\n## Module Map\nClusters with sizes, labels, cohesion scores. Anomalies noted.\nModule roles (entry point, routing, business logic, data access, utility, etc.).\n\n## Entry Points\nApplication entry points by kind (application, HTTP route, CLI, event listener, test,\npublic API).\n\n## Layer Architecture\nDetected layers with directory mappings. Violations with evidence.\n\n## Dependency Structure\nInstability rankings with interpretation \u2014 what the scores mean structurally.\nStability violations.\n\n## Circular Dependencies\nAll cycles: length, members, confirmed break points from investigation.\n\n## Boundary Assessment\nSeams: API surface width, confirmed leaky vs. clean.\n\n## Complexity Hotspots\nRanked hotspots with skeleton context from investigation.\n\n## Chokepoints\nHigh-centrality files with blast radius and split recommendations.\n\n## Dead Code\nConfirmed unreachable symbols. Zombie code noted separately.\n\n## Code Patterns\nFindings grouped by pattern type and severity.\n\n## Strengths\nWhat the architecture does well. Notable absence of expected problems.\n\n## Weaknesses\nConfirmed structural issues with evidence chains.\n\n## Risks\nCausal chains: what breaks first, what cascades, minimum intervention.\n\n## Recommendations\nPrioritized, actionable steps. Each linked to a confirmed finding\nand a specific act MCP tool call or skill.\n```\n\n## Project Map Updates\n\nUpdates **all sections** of `project-map.md` (workspace root, full rewrite). Appends to the\nAnalysis History table.\n\n## Rules\n\n1. Dispatch Phase 1 in a single parallel batch \u2014 never sequentially\n2. Write all hypotheses before dispatching Phase 2 \u2014 no browsing without a hypothesis\n3. Evidence chains, not data points \u2014 explain what scores mean structurally\n4. Follow new signals \u2014 if a Phase 2 subagent finds something unexpected, dispatch a\n   follow-up (capped at one extra round)\n5. Note negative space \u2014 absence of expected problems is a finding\n6. Executive summary must include an explicit Ready / Needs work / Not ready verdict"
}