architectural-analysis

What this skill does

# Architectural Analysis

## Overview

Produce diagram-first architectural reports for a codebase or a scoped subtree. The primary artifact is a set of mermaid diagrams under `docs/architecture/<report-date>/<mode>/`, accompanied by markdown reports that resolve every callout to a `path:line` citation. Every node and every edge in every diagram is grounded in the source — no exceptions outside the explicit synthesized-concept escape hatch.

## When to use

Trigger this skill when the user asks for:

- A full architectural snapshot of a codebase ("run a full architectural analysis")
- A scoped diagram of a subsystem ("diagram the data flow through `<path>`")
- A specific mode by name ("ERD for this app", "where are the failure modes in `<path>`", "map the integration points")

Do not trigger for:

- Pure prose explanations with no diagram requirement (use `code-explanation`)
- New-system design from a blank page (use `system-design`)
- Single-file walkthroughs (use `diffity-tour`)

## Modes

Eight analysis modes. Each has its own callout prefix, primary mermaid diagram type, and dedicated reference file in `references/`.

| Mode | Prefix | Primary diagram | Reference |
|---|---|---|---|
| Information architecture | `I-` | `graph TD` (module hierarchy) or C4 container | `references/mode-information.md` |
| Data flow | `D-` | `flowchart LR` + `sequenceDiagram` per critical path | `references/mode-data-flow.md` |
| Integrations | `X-` | C4 context boundary | `references/mode-integrations.md` |
| UI surfaces | `U-` | route tree + component graph | `references/mode-ui-surfaces.md` |
| Interaction patterns | `P-` | `graph TD` per-surface pattern decomposition | `references/mode-interaction-patterns.md` |
| Data model | `M-` | `erDiagram` | `references/mode-data-model.md` |
| Control flow | `C-` | `stateDiagram-v2` + `sequenceDiagram` | `references/mode-control-flow.md` |
| Failure modes | `F-` | annotated flowchart with error edges | `references/mode-failure-modes.md` |

Callout IDs are stable across modes — `I-12` referenced from a data-flow report points to the same physical node in the IA diagram. The cross-mode index in the synthesis README binds them.

### Note on interaction patterns

UI surfaces inventories *what* user-facing entry points exist. Interaction patterns answers *how* content within those surfaces is organized: bands vs. tabs, sticky inspector, progressive disclosure, master-detail, wizard, accordion. Two layouts can have identical component imports and still create radically different user mental models — this mode reads composition shape, ARIA roles, state shape, and pattern-naming conventions to surface the difference. See `references/mode-interaction-patterns.md` for signals and the raised synthesized cap (35% vs. 20% for other modes) that reflects the inherently more emergent nature of pattern detection.

## Workflow

Doc-first. The team's in-tree docs are treated as **the spine of the report**. The analysis confirms documented behavior with citations, flags drift where the doc no longer matches code, and surfaces gaps where code does something undocumented. The deliverable is a single report — readers should not have to consult docs separately to know what's true. Each mode report leads with the doc reference (collapsed for those who already know the territory) and uses the narrative to highlight gaps and drift.

Eight phases. Each has a single purpose; do not collapse them.

### 1. Scope

Establish:

- **Target**: full repo, subtree, or named feature.
- **Modes**: which of the eight (default: all if user said "full analysis").
- **Output root**: `docs/architecture/<YYYY-MM-DD>/` — create now if missing.
- **Codanna availability**: check for `.codanna/`. Falls back to grep if absent.

### 2. Read in-tree docs (load the spine)

Find every authoritative doc and **read each one**. This is the load-bearing change: the docs become the prior the rest of the workflow operates on.

```bash
find <target>/docs <target>/*/docs -maxdepth 4 -type f \( -name '*.md' -o -name 'CHANGELOG*' \) 2>/dev/null
find <target>/CLAUDE.md <target>/*/CLAUDE.md <target>/*/README.md 2>/dev/null
find <target>/cf-web-container*/SHUTDOWN*.md <target>/cf-web-container*/GRACEFUL*.md 2>/dev/null
```

Persist the list to `docs/architecture/<date>/docs-inventory.txt`. **Then read them all** (orchestrator, not delegated — the orchestrator owns the doc map and treats the docs as authoritative). Build a working topic→doc index — which doc is authoritative on which subsystem. The output of this phase is `docs/architecture/<date>/doc-map.md`:

```markdown
# Doc map

| Topic | Doc | Modes |
|-------|-----|-------|
| Handlebars 3-layer cache | mainwebcode/docs/HANDLEBARS_CACHING.md | data-flow, control-flow |
| KV-store migration (cache + persist) | mainwebcode/docs/cache-migration/*.md | control-flow, data-model |
| Container shutdown 5-layer signal flow | mainwebcode/cf-web-container-next/GRACEFUL_SHUTDOWN.md | control-flow, failure-modes |
| WAF triage + DetectionOnly→On runway | cosential-proxy/docs/waf-triage-process.md | failure-modes, integrations |
| Okta Admin auth handshake | mainwebcode/docs/okta-authentication-crm-admin.md | data-flow, integrations |
| SQL metrics instrumentation | mainwebcode/docs/sql-metrics.md | failure-modes, control-flow |
| Tests & test runner | mainwebcode/docs/tests.md | failure-modes |
| Legacy EC2 topology (drift) | mainwebcode/docs/architecture-diagram.md | information *(stale)* |
```

A **stale** marker is set when the orchestrator's read of the doc reveals it describes a topology or stack that's no longer current (e.g., legacy EC2 vs. current k8s). Mark the doc as `*(stale)*` in the table and treat it like a gap target rather than a spine entry.

If a target has no docs beyond `README.md` + `CLAUDE.md`, mark this in the synthesis README ("Greenfield doc surface — analysis is gap-only") and proceed.

### 3. Dispatch sub-agents (parallel, primed with the doc map)

Each sub-agent now receives the doc map plus the doc text relevant to its mode. The contract changes shape: sub-agents don't enumerate everything they find — they classify against the documented spine.

Read `references/subagent-dispatch.md` for the prompt template. The output contract is:

```yaml
- callout_id: D-12
  label: "Handlebars Layer 3 cache.put 60s TTL"
  citation: app/com/util/handlebars.cfc:99
  evidence: "this.cache.put(cbKey, local.result, 60000);"
  classification: confirms              # confirms | drift | gap | extends
  doc_ref: mainwebcode/docs/HANDLEBARS_CACHING.md
  doc_claim: "Layer 3: handlebars_templates_{hash} TTL 60,000s"
  notes: "Doc claim verified; cited line matches the TTL value."
```

- **confirms** — code matches the doc claim. Cited for evidence, but the doc is the spine.
- **drift** — code disagrees with the doc. Cited explicitly with the doc claim quoted alongside the code claim. **Drift findings always make it into the report's Drift section, not collapsed.**
- **gap** — code does something the docs don't cover. **Gap findings drive the synthesis README.**
- **extends** — code adds detail the doc doesn't claim. Edge case between confirms and gap.

Sub-agents must NOT re-document territory the spine doc covers cleanly. If `HANDLEBARS_CACHING.md` already explains the 3-layer cache, the data-flow sub-agent's job is to (a) cite the canonical line for each layer (confirms) and (b) report drift or gaps — not to write its own cache description.

Dispatch in a single message with parallel `Agent` tool calls. One sub-agent per mode. Never with `team_name`.

### 4. Verify (orchestrator)

Mechanical pass per `references/verification-protocol.md`:

- Resolve every cited symbol (codanna or grep).
- `Read` each cited line; evidence string must match verbatim.
- Absence claims (`gap` findings often) — grep first; discard if the asserted-missing symbol exists.
- For drift findings — read both the doc claim location and the code; confirm the disagreement