architectural-analysis

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.

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:

# 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:

- 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 i