gap-analysis
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 investigate runtime bugs — use investigate. Does not assess module-level architecture — use architectural-analysis. Does not research open-ended options with no second artifact to compare against — use research.
npx skills add testdouble/han --skill gap-analysis --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
- 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 investigate runtime bugs — use investigate. Does not assess module-level architecture — use architectural-analysis. Does not research open-ended options with no second artifact to compare against — use research.
How it works
- The skill delegates the primary analysis to the han-core:gap-analyzer agent, which is invoked once to read the analyzer's full output file. It then synthesizes a stakeholder-readable report from the gap data, ensuring Gap IDs map from GAP-NNN to G-NNN and that sections align with the report template.
- It ensures plain language in Sections 1 and 2, with technical details reserved to Section 3 only if explicitly requested by the user. It treats evidence according to the project’s evidence rules and surfaces artifact-level caveats once per report when applicable. It presents neutral gap lists, with optional “Where to start” guidance if a purpose is stated.
- The swarm model uses a predefined composition and may include optional agents (e.g., evidence-based investigator, plan synthesizer) depending on size and signals from the gap analysis output.
When to use it
- Use when comparing a current state artifact against a desired state artifact to identify, document, and communicate gaps.
What it can touch
- It interfaces with the han-core:gap-analyzer to obtain gap data and then writes a structured report to the project’s documentation root or a configured output path. The process preserves stable gap IDs and cross-references across sections using the same IDs. It relies on the provided report template to format the final output.
Caveats
- The skill does not investigate runtime bugs or assess module-level architecture directly. It does not research open-ended options without a second artifact to compare against. The report follows the defined template and readability guidance and preserves gap ID consistency across the report.
## 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: !`echo "${CLAUDE_CONFIG_DIR:-$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 languag
- Project Context
- Operating Principles
- Step 1: Identify Inputs and Project Context
- Step 2: Run the han-core:gap-analyzer Agent
- Step 3: Classify Size and Build the Swarm
- Step 4: Confirm Swarm and Technical-Detail Modes
- Step 5: Run the Swarm (unless opted out)
- Step 5.5: Conditional Second Round
- Step 5.6: Plan-Synthesizer Consolidation (medium and large only)
- Step 6: Synthesize the Report
- Step 6.5: Readability Rewrite and Self-Check
- Step 7: Present the Report
What does the gap-analysis skill do?
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 investigate runtime bugs — use investigate. Does not assess module-level architecture — use architectural-analysis. Does not research open-ended options with no second artifact to compare against — use research.
How do I install it?
Run `npx skills add testdouble/han --skill gap-analysis --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From testdouble/han, a repository with 154 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.