architecture-analysis

What this skill does

# Architecture Analysis Skill

## Purpose

This skill produces **risk and design-characteristics analyses** over an architecture's documentation — the kind of assessments that come out of an architecture review meeting, pre-incident review, or release-readiness audit.

It bundles **ten focused analyses** across two groups, each driven by a dedicated spec and a universal sub-agent:

**HIGH-priority (runtime / security risk):**

| # | Analysis | Lens | Output |
|---|----------|------|--------|
| 1 | **SPOF** | Single points of failure → full outage / degradation / operational | `analysis/SPOF-<date>.md` |
| 2 | **Blast Radius** | Per-component downstream cascade impact | `analysis/BLAST-RADIUS-<date>.md` |
| 3 | **Bottleneck** | Throughput chokepoints and capacity headroom | `analysis/BOTTLENECK-<date>.md` |
| 4 | **Cost Hotspots** | Pareto cost concentration and over-provisioning | `analysis/COST-HOTSPOTS-<date>.md` |
| 5 | **STRIDE** | Security threats per trust boundary | `analysis/STRIDE-<date>.md` |

**Strategic / sustainability:**

| # | Analysis | Lens | Output |
|---|----------|------|--------|
| 6 | **Vendor Lock-in** | Portability risk, exit cost, vendor concentration | `analysis/VENDOR-LOCKIN-<date>.md` |
| 7 | **Latency Budget** | Per-hop SLO decomposition, over-budget hops | `analysis/LATENCY-BUDGET-<date>.md` |
| 8 | **Tech Debt / EOL** | Technology currency, deprecated SDKs, ADR debt | `analysis/TECH-DEBT-<date>.md` |
| 9 | **Coupling** | Fan-in/fan-out, instability, cyclical dependencies | `analysis/COUPLING-<date>.md` |
| 10 | **Data Sensitivity** | PII data flows, encryption gaps, retention compliance | `analysis/DATA-SENSITIVITY-<date>.md` |

**Distinct from:**
- `architecture-peer-review` — evaluates *document quality* (structure, completeness, coherence). This skill evaluates *runtime and operational risk*.
- `architecture-compliance` — generates contract adherence documents (10 compliance types). This skill produces architectural risk reports.
- `architecture-traceability` — maps PO Spec use cases to architecture sections. This skill has no dependency on a PO Spec.

---

## When to Invoke This Skill

- Before a release-readiness review or architecture gate
- During an annual architecture audit
- After a major architectural change (new component, ADR superseded, Redis removed, etc.)
- Pre-incident risk assessment or chaos engineering planning
- User asks: "find my SPOFs", "blast radius analysis", "where are my bottlenecks", "cost analysis of my architecture", "threat model my architecture", "run all analyses"
- Use `/skill architecture-analysis`

**Do NOT invoke for:**
- Document quality review → `architecture-peer-review`
- Compliance contract generation → `architecture-compliance`
- Requirements traceability → `architecture-traceability`
- ADR creation or update → `architecture-definition-record`

---

## Files in This Skill

| File | Purpose |
|------|---------|
| `SKILL.md` | This file — dispatcher, menu, orchestration |
| `analyses/SPOF.md` | Classification rules and report spec for SPOF analysis |
| `analyses/BLAST_RADIUS.md` | Classification rules and report spec for Blast Radius analysis |
| `analyses/BOTTLENECK.md` | Classification rules and report spec for Bottleneck analysis |
| `analyses/COST_HOTSPOTS.md` | Classification rules and report spec for Cost Hotspots analysis |
| `analyses/STRIDE.md` | Classification rules and report spec for STRIDE Threat Model |
| `analyses/VENDOR_LOCKIN.md` | Classification rules and report spec for Vendor Lock-in analysis |
| `analyses/LATENCY_BUDGET.md` | Classification rules and report spec for Latency Budget analysis |
| `analyses/TECH_DEBT.md` | Classification rules and report spec for Tech Debt / EOL analysis |
| `analyses/COUPLING.md` | Classification rules and report spec for Coupling / Fan-out analysis |
| `analyses/DATA_SENSITIVITY.md` | Classification rules and report spec for Data Sensitivity & Flow analysis |
| `analyses/SECURITY_POSTURE.md` | Consolidation spec — merges the STRIDE + Data Sensitivity reports into a reviewer-fillable Security Posture validation checklist (markdown-only) |
| `templates/analysis-report-skeleton.md` | Shared section structure for all Markdown analysis reports |
| `templates/analysis-report-html-skeleton.html` | Shared HTML shell (d3.js v7 + d3-sankey, corporate styling) for the HTML output mode |
| `templates/viz/<analysis_type>.html` | One self-contained d3 viz snippet per analysis type (10 files); inlined into the HTML shell at render time |

---

## Step 0 — Resolve Plugin Directory

Before any workflow, resolve the absolute path to the plugin installation so spec files can be loaded by the sub-agent.

**Step A — Glob (dev/local mode)**:

Glob for: `**/{sa-skills,solutions-architect-skills}/skills/architecture-analysis/SKILL.md`

The brace expansion matches both marketplace installs (`sa-skills/` in `~/.claude/plugins/cache/...`) and local dev clones (historical repo folder `solutions-architect-skills/`). If found, strip `/skills/architecture-analysis/SKILL.md` from the result to get `plugin_dir`.

**Step B — Marketplace fallback**:

If Glob returns nothing, set:
```
plugin_dir = ~/.claude/plugins/marketplaces/shadowx4fox-solution-architect-marketplace
```

Store `plugin_dir` for use in all agent prompts.

---

## Step 1 — Locate Architecture Document

Search for `ARCHITECTURE.md` at the project root. Determine doc structure:

- **Multi-file**: `ARCHITECTURE.md` exists as a navigation index + `docs/NN-*.md` section files + `docs/components/` per-component files
- **Monolithic**: a single `ARCHITECTURE.md` file containing all sections

If no `ARCHITECTURE.md` is found, abort:
```
❌ No ARCHITECTURE.md found. Use /skill architecture-docs to create one first.
```

Build `doc_files` — an ordered list of absolute file paths to pass to each agent:
1. `ARCHITECTURE.md` (always)
2. `docs/NN-*.md` section files in numeric order (if `docs/` exists)
3. `docs/components/README.md` and `docs/components/**/*.md` in numeric order
4. All `adr/ADR-*.md` files in alphabetic order
5. `compliance-docs/COMPLIANCE_MANIFEST.md` (if present — used for SPOF and STRIDE cross-reference)

---

## Step 2 — Select Analyses (BLOCKING — user must choose)

Present the analysis menu. **Do not default or assume.** If the user says "analyze my architecture" without specifying which, present this menu:

```
═══════════════════════════════════════════════════════════
Architecture Analysis — choose analyses to run:
═══════════════════════════════════════════════════════════

  HIGH-priority (runtime / security risk):
   1. SPOF             (Single Points of Failure)        1 agent
      Critical, Degradation, and Operational failure modes with Heat Map

   2. Blast Radius     (Downstream cascade impact)       1 agent
      Per-component fan-out, cascade severity, bulkhead assessment

   3. Bottleneck       (Throughput chokepoints)          1 agent
      Serial chokepoints, connection saturation, capacity headroom

   4. Cost Hotspots    (Cost concentration)              1 agent
      Pareto cost ranking, over-provisioning candidates, vendor lock-in cost

   5. STRIDE           (Security threats per boundary)   1 agent
      Per-trust-boundary STRIDE matrix, high-priority threats

  Strategic / sustainability:
   6. Vendor Lock-in   (Portability risk, exit cost)     1 agent
      L1/L2/L3 lock tiers, vendor concentration, exit cost ranking

   7. Latency Budget   (Per-hop SLO decomposition)       1 agent
      Per-flow budget breakdown, over-budget hops, tail-latency variance

   8. Tech Debt / EOL  (Currency, deprecated tech)       1 agent
      EOL hotlist, deprecated SDKs, unimplemented ADR replacements

   9. Coupling         (Fan-in/fan-out, cycles)          1 agent
      Critical hubs, volatile leaves, god objects, cyclical dependencies

  10. Data Sensitivity (PII flow, encryption gaps)       1 agent
      Data inventory, encryption/retention gaps, sensitive flow map

  11.