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`

## 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:project-manager` coordinates Section 4 synthesis at medium and large only.** When the swarm reaches four or more agents, PM 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 PM.
- **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.

# Run a Gap Analysis

## Step 1: Identify Inputs and Project Context

Read the user's argument and conversation context to identify two artifacts:

- The **current state** — what exists today (e.g., the implementation, the shipped feature, the legacy design).
- The **desired state** — what is expected (e.g., the spec, the PRD, the new design).

Inputs may be file paths, directory paths, URLs, or inline text. If the user named only one artifact and a comparison target is implied (e.g., "compare the auth module to the auth spec"), search the project for the implied second artifact using `Glob` and `Grep` against `docs/`, `specs/`, `requirements/`, or directories surfaced via CLAUDE.md / `project-discovery.md`. If the implied artifact cannot be located, ask the user for the path before proceeding.

State the resolved comparison direction to the user in one line: "Comparing **{current}** against **{desired}**." If the user wants the direction reversed, accept the override.

**Capture the purpose, if one was stated.** Note *why* the user is running this comparison when they said so (e.g., "before a redesign pass," "to scope the next sprint," "to decide whether to ship"). If no purpo