/gap-analysis

name: "gap-analysis"
description: >
  Performs a gap analysis between two artifacts (a current state and a desired state) and produces a plain-language,
  stakeholder-readable report indexed by stable gap IDs. Use when the user wants to compare, evaluate, audit, or
  reconcile one artifact against another. Does not investigate runtime bugs — use investigate. Does not assess
  module-level architecture — use architectural-analysis. Does not research open-ended options with no second artifact
  to compare against — use research.
arguments: size
argument-hint:
  "[size: small | medium | large | dynamic] [current state artifact, desired state artifact, optional: scope and modes]"
allowed-tools:
  Read, Write, Glob, Grep, Agent, Bash(find *), Bash(git *),
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Project Context

• CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
• project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
• personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
• project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Operating Principles

• **The `han-core:gap-analyzer` agent owns the primary analysis.** This skill does not classify gaps itself. It calls

`han-core:gap-analyzer` once, reads the analyzer's full output file, and synthesizes a stakeholder-readable report from it.

• **Plain language is the default surface.** Sections 1 and 2 of the report never contain file paths, line numbers,

function or class names, library mechanics, or language primitives. Technical fidelity is quarantined to Section 3 and only appears when the user has explicitly requested technical details.

• **The swarm runs by default.** A minimum viable swarm ships at every size: `han-core:adversarial-validator` and

`han-core:junior-developer` always, plus `han-core:evidence-based-investigator` when the current state is concrete enough to verify against. The user may opt out with `no swarm` to fall back to a lightweight gap-analyzer-only pass.

• **Evidence rule applies to every gap.** Apply the evidence rule from

[../../references/evidence-rule.md](../../references/evidence-rule.md) when characterizing the evidence that establishes each gap. Name the trust class of every citation pair (codebase, web, provided); apply the corroboration gate to web-source claims that establish a gap; and label gaps where the desired-state evidence is absent ("the spec is silent on X") as a distinct state, not as a weak gap. The `han-core:evidence-based-investigator` dispatched in the swarm carries codebase findings; the gap analyzer carries the spec-side citations.

• **Artifact-level analysis caveats are surfaced once, not per gap.** Some validator observations apply uniformly to the

whole comparison rather than to any one gap — most commonly a provenance concern about the desired-state artifact as a whole (for example, "the desired state is a provided, uncommitted, same-session source," which the evidence rule's `provided` trust class genuinely warrants flagging). Surface such an observation a single time as an artifact-level analysis caveat. Do not repeat it as a per-gap verdict on every gap that rests on that artifact, and do not let it raise or lower any gap's confidence — it bears on the whole report equally, so per-gap weighting would double-count one fact. Provenance concerns specific to a _single_ gap's evidence still belong to that gap's verdict.

• **`han-core:junior-developer` runs the actor-perspective sweep.** Gap analysis lives at the feature and behavioral

level from a user's or actor's perspective — human end users (and sub-roles like customer, admin, auditor, support agent), API callers, AI agents, integration partners, batch processes, internal services. The han-core:junior-developer's job in the swarm is to check that each gap holds for every actor type the desired state addresses or implies, and to surface gaps the analyzer missed because it only considered one actor type.

• **`han-core:plan-synthesizer` coordinates Section 4 synthesis at medium and large only.** When the swarm reaches four

or more agents, the synthesizer consolidates the swarm's confirmations, contradictions, augmentations, and per-gap confidence values for the skill to render. At small swarm size (two or three agents), the skill consolidates deterministically without the synthesizer.

• **Optional sections must not be load-bearing.** A report with only Sections 1 and 2 must stand on its own. Sections 3

and 4 are additive — never required for Sections 1 and 2 to make sense.

• **Purpose-conditioned prioritization is a labeled skill judgment, never the analyzer's.** The `han-core:gap-analyzer`

produces a neutral, unprioritized gap list and must stay that way. When the user states _why_ they are running the comparison (e.g., "before a redesign pass," "to scope the next sprint"), the skill may add one explicitly-labeled "Where to start" pointer view that names the few gaps most blocking that stated purpose. This is the skill's own synthesis judgment — the same kind it already makes when it clusters gaps into themes and derives confidence — layered on top of the neutral list, never replacing it, and omitted entirely when no purpose was given.

• **Gap IDs are stable for the life of the report.** Map `GAP-NNN` from the `han-core:gap-analyzer` output to `G-NNN` in

the report, preserving ord