architectural-analysis

Project Context

• git installed: !which git
• CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
• project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f

Operating Principles

Read these before dispatching anything. They constrain every step below.

• A focus area is required. This skill analyzes a specific module, directory, or feature. "Analyze the whole codebase" is not a valid input. If no focus area resolves to real files, stop and ask the user to name one.
• The agents own the judgment; the skill orchestrates. The skill validates the focus area, classifies size, selects the roster, fans agents out and in, and renders the report. It does not produce findings itself.
• The discovery roster is signal-selected; the synthesis spine always runs. structural-analyst, behavioral-analyst, risk-analyst, and software-architect run at every size BECAUSE structure, runtime behavior, risk-of-inaction, and SOLID synthesis are the irreducible core of an architectural read. Every other specialist is added only when the focus area's signals warrant it and the size band allows it, BECAUSE dispatching an agent whose domain the code does not touch burns tokens and dilutes the report with low-signal findings.
• Default to small. Start classification at small and escalate only when a higher-band signal is clearly present. Borderline signals stay at the smaller band. Under-dispatching is recoverable by re-running at a larger size; over-dispatching is not.
• Recommendations, not refactors. The skill never modifies code. software-architect (and system-architect when dispatched) produce pseudocode sketches for proposed boundaries. Implementation is a separate, later step.
• Negative results are valuable. When a dimension is genuinely clean (no concurrency in a pure-functional module, sound boundaries), the report says so. Agents must not fabricate findings to fill a section.
• Single pass, no iteration round. This skill is a fan-out / fan-in, not an iterative loop. If a band proves too small, the user re-runs at a larger size — the skill does not self-escalate mid-run.
• System-altitude work is deferred by default. software-architect defers cross-service / bounded-context / trust-boundary findings rather than absorbing them. system-architect is added to the roster only at large size and only when a boundary-crossing seam is actually present. When it is not dispatched, those deferrals are surfaced in the report so the user can dispatch system-architect separately.
• The report template lives at [references/architectural-analysis-report-template.md](references/architectural-analysis-report-template.md). The skill renders that template by filling placeholders and removing the sections whose agent was not dispatched. It does not invent a structure inline.

Run an Architectural Analysis

Step 1: Validate the Focus Area and Resolve Project Context

Bind $size. If the user passed small, medium, or large as the first positional argument, bind $size to it. Anything else is part of the focus-area context, not a size; bind $size to the literal none provided.

Resolve the focus area. Take the remaining argument and conversation context as the focus area. Confirm it resolves to real files using Glob and Read. Identify the boundary: which files and directories the focus area includes, and one layer of neighbors in each direction (what it imports, what imports it). If the focus area does not resolve to actual files, stop and ask the user to clarify it before going further. If no focus area was supplied at all, ask the user to name one — do not proceed against the whole codebase.

Resolve project context. If CLAUDE.md is present (see Project Context), read its ## Project Discovery section for conventions. Fall back to project-discovery.md if present. These resolve language, framework, and convention questions so the agents infer less. If neither exists, the agents fall back to surrounding-code inference — note this in the agent briefs.

Note git availability. Read the git installed value from Project Context. If it is empty, git is unavailable: the analysts will skip churn- and recency-based reasoning and the report must state this. If it is non-empty, the analysts may use git history for churn and likelihood evidence.

State the driving concern, if any. If the user named a concern ("I suspect a race in the retry queue", "we want to split this module"), capture it. It biases every agent's attention without narrowing scope. Pass it into every brief.

Step 2: Detect Signals and Classify Size

Run targeted Grep and Glob over the focus area to detect which domains the code actually touches. These signals drive both the size band and the roster:

• Concurrency signal: async/await, Promises, threads, goroutines, workers, channels, mutexes/locks, semaphores, queues, Promise.all, WaitGroup, thread pools, atomic types.
• Security signal: authentication, authorization, sessions, tokens, passwords, secrets, crypto calls, PII fields, deserialization of untrusted input, SQL/command construction from input.
• Data signal: schema or migration files, ORM models/repositories, hand-written SQL, query builders, data-pipeline or stream/event-contract code, document-store access.
• DevOps signal: Dockerfiles, IaC (Terraform, CloudFormation, k8s manifests), CI/CD pipeline definitions, observability/metrics/tracing wiring, retry/timeout/scaling configuration.
• System-seam signal: the focus area crosses a deployable unit or bounded-context boundary — RPC/HTTP clients to sibling services, message brokers, shared databases across services, cross-context model imports, contested data ownership.
• Unfamiliar-area signal: the focus area is large or its internal structure is not legible from a first read, so the discovery analysts would benefit from a map first.

Classify the size. Default to small. Escalate only when a band's signal is clearly present; when a signal is borderline, stay at the smaller band.

• Small (default) — a single module or directory, contained surface, no cross-cutting concerns: no security signal, no data signal, no DevOps signal, no system-seam signal. The concurrency signal may be present or absent.
• Medium — two or three adjacent subsystems, OR exactly one cross-cutting concern present (one of: security, data, or DevOps signal — a single auth surface, a single data-contract, a single operational surface).
• Large — more than roughly a dozen files across multiple subsystems, OR two or more cross-cutting concerns present together, OR a system-seam signal is present, OR $size is large.

Apply the size override. If $size is not none provided, use it as the band and skip the signal-based classification above — but still select specialists by signal (a large override does not dispatch agents whose domain the code never touches). A conversational override ("run this large") is equivalent to $size.

Step 3: Build the Roster and Announce It

Synthesis spine — dispatched at every size:

• structural-analyst — static structure: module boundaries, coupling, dependency direction, abstractions, duplication. Emits S# findings.
• behavioral-analyst — runtime behavior: data flow, error propagation, state management, integration boundaries. Emits B# findings.
• risk-analyst — scores the S/B/C findings for risk of inaction (likelihood, severity, blast radius, reversibility). Emits R# items. Runs after the discovery wave.
• software-architect — synthesizes all upstream findings into intra-codebase recommendations grounded in cohesion, coupling, and SOLID, with pseudocode sketches. Emits A# items. Runs last.

Signal-selected discovery specialists — added when the signal is present and the band allows:

| Specialist | Add when | Min band | |---|---|---| | `