structural-analyst

July 6, 2026 · View on GitHub

Operator documentation for the structural-analyst agent in the han plugin. This document helps you decide when and how to dispatch the agent. For what the agent does internally, read the agent definition at han-core/agents/structural-analyst.md.

See also: Plugin landing page · All agents · All skills

TL;DR

  • What it does. Analyzes the static structure of a specified codebase focus area: module boundaries, coupling, dependency direction, abstractions, and duplication. Produces numbered structural findings with file paths and verbatim code.
  • When to dispatch it. You want a principled static-structure pass on a module or focus area, independent of runtime behavior or risk assessment. Always dispatched by /architectural-analysis. Conditionally dispatched by /code-review, and by /iterative-plan-review and /plan-implementation when the plan or review covers module boundaries, coupling, or dependency direction. Available to /plan-a-feature as an opt-in specialist, included on request.
  • What you get back. Numbered S# findings, each tied to a structural dimension (Boundaries / Coupling / Dependency Direction / Abstraction / Duplication), file paths, verbatim code, and an impact statement.

Key concepts

  • Static, not runtime. The agent reads code as written. Data flow, error propagation, and concurrency are out of scope and deferred to behavioral-analyst and concurrency-analyst.
  • Five dimensions, all required. Module Boundaries and Cohesion, Coupling Analysis, Dependency Direction, Abstraction Assessment, Duplication and Pattern Candidates. Skipping a dimension makes the analysis incomplete.
  • Coupling has texture. The agent distinguishes afferent (who depends on this?) from efferent (what does this depend on?), and stable-dependency from volatile-dependency, rather than counting imports as a single number.
  • Negative results are valuable. When a dimension surfaces no issues, the agent says so explicitly. "Well-structured" is a finding too.
  • Discovers findings, does not synthesize. Recommendations belong to software-architect. Risk assessment belongs to risk-analyst.
  • /code-review adds a default-SUGG dispatcher directive at Step 3.5. When dispatched from /code-review, the skill appends an instruction: default the severity of every finding to SUGG. Escalate to WARN or CRIT only when the change actively introduces or worsens the issue. This is /code-review's tailoring; the agent's general behavior outside /code-review is unchanged. Other callers (such as /architectural-analysis) receive the agent's default skeptical posture.

When to use it

Dispatch when:

  • /architectural-analysis is running. The agent is one of the three parallel analysts the skill always dispatches.
  • /code-review flags structural concerns in the file list (new module boundaries, large refactors, suspicious import patterns).
  • You suspect a coupling or cohesion problem in a module but cannot point at the specific finding. The agent surfaces them concretely.
  • A pre-refactor baseline is needed before splitting or restructuring a module.

Do not dispatch for:

  • Runtime behavior, data flow, error propagation. Use behavioral-analyst.
  • Concurrency hazards. Use concurrency-analyst.
  • Risk prioritization. Use risk-analyst (which consumes this agent's findings).
  • Architectural recommendations or refactoring plans. Use software-architect.
  • Cross-service topology. Use system-architect.

How to invoke it

Dispatch via the Agent tool with subagent_type: han-core:structural-analyst. Give it a focus area (module, directory, or set of files). The agent examines the focus area plus one layer outward in each direction (what depends on it, what it depends on).

Example prompts:

  • "Analyze the static structure of src/billing/. Focus on module boundaries and coupling. Use git churn to identify volatile dependencies if available."
  • "Examine packages/notifications/ for cohesion and abstraction quality. We are about to split this package into two."

What you get back

  • Numbered S# findings, each with: dimension (Boundaries / Coupling / Dependency Direction / Abstraction / Duplication), relevant file paths, verbatim code in fenced blocks, and an impact statement.
  • A Structural Summary with the focus area analyzed, the 2-3 key concerns, and any well-structured areas. It also names any dimensions that could not be fully assessed (for example, when git is unavailable for churn analysis).

How to get the most out of it

  • Scope narrowly. A single module produces sharp findings. A broad scope flattens into generic concerns.
  • Run with git available. The agent uses git log --since="90 days ago" to identify high-churn modules. Without git, churn-based findings drop and the agent says so explicitly.
  • Pair with behavioral-analyst and concurrency-analyst. The three analysts together cover static structure, runtime behavior, and concurrency. /architectural-analysis dispatches all three.
  • Feed findings into risk-analyst. The agent's findings are the upstream input for risk prioritization.

Cost and latency

The agent runs on sonnet. A focused-scope analysis runs in a couple of minutes. Built for per-module cadence, not tight-loop iteration.

Sources

The agent's vocabulary and dimensions are grounded in established structural-analysis practice.

Robert C. Martin: Stability Metrics

Martin's afferent / efferent coupling and Instability Index frame the agent's coupling analysis.

URL: https://blog.cleancoder.com/uncle-bob/2018/11/27/Comments-by-Tests.html

Eric Evans: Domain-Driven Design

Evans's bounded-context and aggregate framings inform the agent's module-boundary findings inside a single codebase.

URL: https://www.domainlanguage.com/ddd/

Martin Fowler: Refactoring Catalog

Fowler's catalog (Extract Class, Move Method, Inline Class) names the structural moves the agent surfaces.

URL: https://martinfowler.com/books/refactoring.html