{"slug":"gap-analysis-2","title":"gap-analysis","summary":"Performs a gap analysis between two artifacts (a current state and a desired state) and produces a plain-language, stakeholder-readable report indexed by stable gap IDs. Use when the user wants to compare, evaluate, audit, or reconcile one artifact against another. Does not inves","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-15T13:11:55.279017Z","repo":{"url":"https://github.com/testdouble/han","stars":303,"forks":24,"license":"MIT","updatedAt":"2026-10-14T20:22:28Z"},"bodyHtml":"
\n

name: \"gap-analysis\"\ndescription: >\nPerforms a gap analysis between two artifacts (a current state and a desired state) and produces a plain-language,\nstakeholder-readable report indexed by stable gap IDs. Use when the user wants to compare, evaluate, audit, or\nreconcile one artifact against another. Does not investigate runtime bugs — use investigate. Does not assess\nmodule-level architecture — use architectural-analysis. Does not research open-ended options with no second artifact\nto compare against — use research.\narguments: size\nargument-hint:\n\"[size: small | medium | large | dynamic] [current state artifact, desired state artifact, optional: scope and modes]\"\nallowed-tools:\nRead, Write, Glob, Grep, Agent, Bash(find *), Bash(git *),\nBash(bash \"$/scripts/han-config-dir.sh\")

\n

Project Context

\n\n

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read\nthat returns no file is no personal configuration: continue silently. When that file or the project .han/config.md\nprobe supplies content, apply it per config-rule.md, which governs precedence\nbetween the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

\n

Operating Principles

\n\n

Run a Gap Analysis

\n

Step 1: Identify Inputs and Project Context

\n

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

\n\n

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

\n

State the resolved comparison direction to the user in one line: \"Comparing against .\" If the\nuser wants the direction reversed, accept the override.

\n

Capture the purpose, if one was stated. Note why the user is running this comparison when they said so (e.g.,\n\"before a redesign pass,\" \"to scope the next sprint,\" \"to decide whether to ship\"). If no purpose is evident, you may\noffer to capture one in the same one-line confirmation — for example, \"If you tell me what this comparison is for, I'll\nflag which gaps block that goal.\" Do not block on it: a purpose is optional and only drives the optional \"Where to\nstart\" view in Step 6. Record the purpose verbatim if given.

\n

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

\n

Step 2: Run the han-core:gap-analyzer Agent

\n

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

\n\n

Read the observed-actor list from the analyzer's output once it returns; it seeds the han-core:junior-developer actor\nsweep in Step 5.

\n

Wait for the agent's return. The summary it returns names the file path and gap counts by category. Read the full\nanalysis file from disk before proceeding — the per-gap entries (GAP-001, GAP-002, ...) are in the file, not the\nreturned summary.

\n

Step 3: Classify Size and Build the Swarm

\n

Default to small. Start the classification at small and only escalate to medium or large when the signals below\nclearly require it. When a signal is borderline, stay at the smaller band. Use these signals from the\nhan-core:gap-analyzer output:

\n\n

Always required, at every size:

\n\n

Required when the current state is concrete (codebase, document on disk, fetchable URL — not inline-text-only\ncomparison):

\n\n

Required at medium and large:

\n\n

Add domain specialists up to the size cap based on what the gaps actually touch. Read the gap entries to decide. Draw\nfrom:

\n\n

Extra agents named in the project config's ## Extra Agents list join this domain-specialist pool and compete under\nthe same gap-driven selection and size caps, per\n../../references/config-rule.md: add one only when a gap touches its stated\nspecialty, count it against the size cap, and skip an entry that does not resolve to a dispatchable agent with a\none-line note.

\n

State the size, the chosen swarm composition, and the per-specialist justification to the user in a short message — for\nexample:

\n
\n

Size: medium. Detected 7 gaps across the auth surface and the user-profile data contract. Swarm (5 agents):

\n\n
\n

Size override. If $size is non-empty (the user passed small, medium, large, or dynamic as the first\nargument), use it: a band value is the size and skips the signal-based classification above, while dynamic forces the\nsignal-based classification even when the project config sets a default band. If $size is empty and the project\nconfig supplies a band via default-swarm-size (per the config rule in\n../../references/config-rule.md), use that band, skip the signal-based\nclassification, and announce the config as the source. The swarm composition still scales to the chosen size. If the\nuser named specific specialists, honor those. If the user requested a different size in conversation rather than via\n$size, accept the override.

\n

Step 4: Confirm Swarm and Technical-Detail Modes

\n

Surface both decisions to the user in one combined message:

\n
\n

Swarm: running by default with [team above]. Reply no swarm to skip the swarm entirely, lightweight to drop to\nthe minimum two (validator + han-core:junior-developer), or name specialists to add or remove.

\n

Technical details: not included by default. Reply include technical details to add Section 3 with file-level\nfidelity, or plain language only to omit it.

\n
\n

If the user already specified either mode in their original request (e.g., \"run a gap analysis with technical details\"\nor \"skip the swarm\"), honor that and skip this confirmation.

\n

Default behavior when the user does not respond or says \"proceed\": swarm runs as recommended, plain language only.\nRecord the chosen modes — they determine which sections appear in the final report.

\n

Step 5: Run the Swarm (unless opted out)

\n

If the user passed no swarm, skip to Step 6.

\n

Launch every selected swarm agent in parallel — a single Agent-tool message with one tool call per agent so they run\nconcurrently — except han-core:plan-synthesizer, which is held for synthesis after the other agents return (see Step\n5.6). Use domain-scoped briefs:

\n\n

Collect every agent's verbatim output. If an agent returned a proposed_new_gap with evidence, append it to the\nanalyzer's findings as a new GAP-NNN entry before report rendering — do not silently drop it. Mark it in the report\nwith a footnote noting it was surfaced by the swarm and by which agent (han-core:junior-developer (actor sweep),\nhan-core:adversarial-security-analyst, etc.).

\n

Step 5.5: Conditional Second Round

\n

Inspect the first-round swarm output for signals that the analyzer's correspondence map systematically excluded an actor\ntype or behavior class:

\n\n

If neither trigger fires, skip to Step 5.6.

\n

A fired trigger is a proxy for the same underlying signal — the first pass systematically under-covered an actor type\nor behavior class. The proposed gaps the swarm already surfaced are a symptom of that under-covered class, not the\nwhole of it. So the round's job is to re-scan that class for additional gaps and to catch recategorizations and\nwithdrawals — not to re-confirm the gaps the swarm already corroborated.

\n

If a trigger fires, run one additional pass — bounded to one extra round, never more:

\n
    \n
  1. Re-dispatch han-core:gap-analyzer with the new findings and the actor types han-core:junior-developer surfaced.\nBrief: \"Your first pass produced N gaps. The validator-augmenter swarm surfaced [new gaps / contradictions], which\npoint to the actor or behavior classes [list] being under-covered in your first pass. Do not re-confirm gaps the\nswarm has already corroborated. Re-scan both artifacts focused on those classes and return only the delta: (a)\nadditional new gaps in those classes that neither your first pass nor the swarm has surfaced, (b) gaps that need\nrecategorization, and (c) gaps that should be withdrawn.\"
    2. \n
  2. Read the delta. Merge new gaps into the source file with fresh GAP-NNN IDs in append order. Record\nrecategorizations and withdrawals.
    3. \n
  3. Do not re-run the full swarm. The second round is for the analyzer; the swarm verdicts on existing gaps carry\nforward.
    4. \n
\n

Record in the in-channel summary that a second round ran and why (which trigger, what changed).

\n

Step 5.6: Plan-Synthesizer Consolidation (medium and large only)

\n

If han-core:plan-synthesizer is not on the team, skip to Step 6.

\n

Launch han-core:plan-synthesizer with:

\n\n

Ask the han-core:plan-synthesizer to produce only Section 4 content — Confirmations, Contradictions, Augmentations,\nany artifact-level Analysis caveats the validator returned, and the Confidence summary table — plus per-gap confidence\nvalues for the skill to fold into Section 2. Direct the synthesizer to keep analysis caveats out of the per-gap confidence values\n(they apply to the whole report, not to any one gap). The synthesizer does not write the report file directly; it returns the\nconsolidated Section 4 content and confidence values to the skill, which renders them into the template in Step 6.

\n

Step 6: Synthesize the Report

\n

Read gap-analysis-report-template.md. Render the report by filling\nplaceholders and removing optional sections that do not apply.

\n

Render rules:

\n
    \n
  1. Map IDs. For each GAP-NNN from the analyzer (and any proposed_new_gap from the swarm, plus any second-round\ndelta), produce a corresponding G-NNN entry in the report. Preserve order. Do not skip IDs.
    2. \n
  2. Translate to plain language for Sections 1 and 2. The analyzer's per-gap content is technical (file paths, code\nidentifiers, document headings). For Sections 1 and 2, restate each gap's Expected, Current, and Why it matters\nfields in plain language a non-technical stakeholder can read. Strip every file path, line number, function name,\nclass name, schema field name, library name, and language primitive. Replace technology terms with capability or\nbehavior descriptions (\"the part of the system that authenticates users\" rather than auth/middleware.ts:42).
    3. \n
  3. Set confidence per gap. If the swarm ran, derive confidence from swarm verdicts: High when ≥ 2 swarm agents\nconfirmed the gap with evidence; Medium when one agent confirmed or augmenters added context without contradiction;\nLow when at least one agent contradicted it. If the synthesizer was on the team, use the per-gap confidence values it returned\nin Step 5.6. If no swarm ran (no swarm path), mark every gap Medium — confidence rests on the analyzer alone —\nand state this in the executive summary.
    4. \n
  4. Inline swarm augmentations into Section 2. For each gap that received augmenter context (added risks, secondary\neffects, refined framing, actor-perspective notes from han-core:junior-developer), add an\nAdditional context (swarm): line to that gap's Section 2 entry in plain language. The same augmentation is\npreserved verbatim in Section 4's Augmentations list for audit trail. Augmentations enrich understanding; they do not\nchange the gap's category or confidence.
    5. \n
  5. Compose the executive summary's \"shape of the gap\" bullets by clustering related gaps thematically. Each bullet\nis a plain-language theme covering one or more gaps. Do not enumerate every gap here — that is Section 2's job.
    6. \n
  6. Render Section 3 (Technical Details) only if the user opted in. For each gap, fill Locations,\nRelevant identifiers, Specifics of the divergence, Remediation direction, Effort signal, and\nRisks / dependencies. Pull Locations and Relevant identifiers directly from the analyzer's evidence pairs. The\nskill itself produces the Effort signal only when the analyzer or the swarm provided enough information; otherwise\nmark it Unknown with a one-sentence basis. If a gap is Implicit and has no concrete location, omit its Section 3\nentry and note it in the section-3 preface as expected.
    7. \n
  7. Render Section 4 (Swarm Findings) by default. Section 4 is omitted only when the user passed no swarm. Group\nentries into Confirmations, Contradictions, and Augmentations using the swarm agents' verbatim verdicts. Build the\nConfidence summary table from the per-gap confidence values set in step 3. If the synthesizer was on the team, use the\nconsolidated Section 4 content it returned in Step 5.6.
    8. \n
  8. Render artifact-level analysis caveats once. Collect every analysis_caveat the validator returned (Step 5) into\nSection 4's Analysis caveats subsection, rendered once as a plain reminder that applies to the whole report —\nexplicitly not a gap finding. Do not let any caveat feed the per-gap confidence values set in step 3. If no\nanalysis_caveat was returned, omit the subsection. (On the no swarm path there is no validator, so there are no\nanalysis caveats.)
    9. \n
  9. Render the \"Where to start\" view only if a purpose was captured. If Step 1 recorded a purpose, render the\noptional Where to start block in Section 1 (after the magnitude table): up to five gaps that most block that\nstated purpose, each as G-NNN — one-line plain-language reason it blocks {purpose}, under the explicit label \"Where\nto start (skill judgment for your stated purpose: ).\" This is the skill's labeled synthesis judgment from\nthe Operating Principles — it adds no new gaps, changes no categories or confidence, and cites only existing G-NNN\nIDs. If no purpose was captured, omit the block entirely; never invent a purpose to justify it.
    10. \n
  10. Update the optional-section markers in the front matter. If Section 3 was not rendered, remove\n- technical_details from sections_included. If Section 4 was not rendered (because the user passed no swarm),\nremove - swarm_findings. Update the \"How to Read This Report\" frame so it does not promise sections that are not\npresent — replace each promise with a single line stating the section was not included for this report. The \"Where\nto start\" block and the \"Analysis caveats\" subsection are conditional content inside existing sections, not\ntop-level sections, so they do not get their own sections_included entries.
    11. \n
\n

Readability. Invoke han-communication:readability-guidance to surface the shared readability standard into your\ncontext, then draft every prose region to that standard: lead with the main point, give sections descriptive headings\nthat name their content, keep one idea per paragraph with the first sentence carrying it, number sequential steps and\nbullet non-sequential items, and reveal detail in layers (Section 1 before 2, 2 before 3). Do not duplicate the rule's\ntext; apply it. The rule governs prose only — leave code fences, any diagram bodies, and the G-NNN gap IDs untouched,\nsince those IDs are citation identifiers that must survive every rewrite and the self-check unchanged.

\n

Write the rendered report to the path resolved in Step 1.

\n

Step 6.5: Readability Rewrite and Self-Check

\n

Readability editor (consolidated reports only). When the run produced a consolidated report — the medium and large\nsizes where han-core:plan-synthesizer consolidated Section 4 — dispatch the han-communication:readability-editor\nagent in a single Agent call to audit and rewrite the report against the standard. Pass it the report file path and the\ndefault audience frame (a capable reader who did not do this work and lacks the author's context); the editor reads\nhan-communication's own canonical rule, so pass no rule path. Direct it to preserve every fact and to rewrite prose\nregions only — never inside code fences, diagram bodies, or the G-NNN gap-ID citation identifiers. Apply its rewrite\nto the report file. At small size and on the no swarm path this is the lightweight gap-analyzer-only pass, so skip\nthis dispatch; the template above and the self-check below still apply.

\n

Self-check (all sizes, after any rewrite, before presenting). Run the standardized readability self-check (the\nshared standard is in your context from han-communication:readability-guidance) over the report's prose regions only —\nnever inside code fences, diagram bodies, or the G-NNN gap-ID citation identifiers. Confirm each criterion and fix any\nfailure before presenting:

\n

Run the readability rule's standardized self-check, which is already in your context from the readability-guidance\ninvocation above. Correct every failure before presenting. Its fidelity criterion is not optional: the standard governs\nhow the content is said, and drops a required fact only when the reader asked for less and losing it would not change\nwhat they do next.

\n

Step 7: Present the Report

\n

Tell the user, in a short summary:

\n\n

Ask whether the user wants to add technical details (if Section 3 was omitted) or refine the scope and re-run.

\n","files":[{"path":"references/gap-analysis-report-template.md","sizeBytes":10766,"isText":true},{"path":"SKILL.md","sizeBytes":32654,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-15T13:12:06.710817Z","sha256":"8FBD09FE9EAD124C5E9F6C094432B5FBB1F0B5CB756473F676CC9DF0F190BEB2","sizeBytes":15928},"review":null,"source":{"repositoryUrl":"https://github.com/testdouble/han","path":"han-research/skills/gap-analysis","license":"MIT","commit":"abba73a773528905a8f3d15956029394746e5c7f","subtreeSha":"803C439FC87D5C06A7AA0C26F269B30489798A4A34CE7CD973DAE9E6673DB62E","lastSyncedAt":"2026-10-15T13:11:53.672149Z"},"reviewedAt":"2026-10-15T13:12:41.74346Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/testdouble/han/tree/main/han-research/skills/gap-analysis"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install testdouble-han@llmmart"},{"target":"git","command":"git clone https://github.com/testdouble/han.git"}]}