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 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 order. Cross-references in Sections 3 and 4 use the same G-NNN IDs.
• The report template lives at gap-analysis-report-template.md. It was designed by the han-core:information-architect agent. The skill renders the template by filling placeholders and removing the optional sections that were not requested or generated.
• The report is written to the shared readability standard. The skill sources the standard by invoking han-communication:readability-guidance and applies it as it writes the report, holding the default audience frame: a capable reader who did not do this work and lacks the author's context. The stable gap IDs (G-NNN) are citation identifiers and survive any rewrite or self-check unchanged.