Run a Gap Analysis

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