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](../../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 order. Cross-references in Sections 3 and 4 use the same `G-NNN` IDs.
- **The report template lives at [gap-analysis-report-template.md](./references/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.

# Run a Gap Analysis

## Step 1: Identify Inpu