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 gap-analyzer agent owns the primary analysis. This skill does not classify gaps itself. It calls 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: adversarial-validator and junior-developer always, plus 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 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.
• 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 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.
• 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 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 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 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 purpose is evident, you may offer to capture one in the same one-line confirmation — for example, "If you tell me what this comparison is for, I'll flag which gaps block that goal." Do not block on it: a purpose is optional and only drives the optional "Where to start" view in Step 6. Record the purpose verbatim if given.

Resolve project config: read CLAUDE.md's ## Project Discovery section if present; fall back to project-discovery.md; fall back to the working directory's docs/ tree. The output report will be written to the project's documentation root if one exists (docs/, documentation/, or a folder surfaced by project config), otherwise to the current working directory. Default report filename: gap-analysis-report.md. If a same-named file already exists, append a short timestamp suffix to avoid overwriting.

Step 2: Run the gap-analyzer Agent

Launch gap-analyzer with a single Agent tool call. Provide:

• The current state and the desired state (paths, URLs, or inline text exactly as resolved in Step 1), with explicit labeling of which is which.
• Any scope the user provided (specific subsystems, features, sections).
• A directive to write its full analysis to a file alongside the future report (e.g., {report-dir}/gap-analysis-source.md) so the skill can read the structured findings and translate them.
• A directive to use unidirectional comparison (current → desired) unless the user explicitly asked for bidirectional analysis.
• A directive to report the actors and modes it observed in the desired state — named roles and sub-roles, interactive vs. batch/automated modes, and API / agent / integration surfaces — as a neutral observation in its output. The analyzer already reads the desired state's full surface area while building the correspondence map; this only asks it to surface what it saw. It is an observation, not a prioritization or classification, so it does not touch the analyzer's neutral posture.

Read the observed-actor list from the analyzer's output once it returns; it seeds the junior-developer actor sweep in Step 5.

Wait for the age