gap-analysis.md

/gap-analysis

Operator documentation for the /gap-analysis skill in the han plugin. This document helps you decide when and how to use the skill. For what the skill does internally, read the skill definition at han-research/skills/gap-analysis/SKILL.md.

See also: Plugin README · Repo root · All skills · All agents · Evidence

TL;DR

• What it does. Compares two artifacts (a current state and a desired state) and produces a plain-language, stakeholder-readable report indexed by stable gap IDs.
• When to use it. You have a spec, PRD, design, or requirements doc and want to know how an implementation (or another artifact) measures up, and you want a report a non-engineer can read.
• What you get back. gap-analysis-report.md (four-section progressive-disclosure structure) plus the underlying gap-analysis-source.md written by the gap-analyzer agent.
• Default-on swarm. A validator-and-augmenter swarm runs by default at every size, with junior-developer running an explicit actor-perspective sweep (human users, API callers, AI agents, integration partners, batch processes, internal services). Reply no swarm to opt out and fall back to a lightweight gap-analyzer-only pass.
• Size-aware. The skill classifies the analysis as small / medium / large, defaults to small (minimum viable swarm: validator + junior-developer, plus investigator when the current state is concrete), and scales the swarm composition proportional to the gap count and domain spread. Pass the size as the first positional argument to override (/gap-analysis large). See Sizing.

Key concepts

• Plain language by default. Sections 1 and 2 of the report contain no file paths, line numbers, function names, or library mechanics. Technical fidelity is quarantined to Section 3 and is only added when you explicitly opt in.
• Purpose-conditioned "Where to start." If you say why you are running the comparison (for example, "before a redesign pass"), the report opens Section 1 with a short, explicitly-labeled "Where to start" view: up to five gaps that most block that purpose, one reason each. This is the skill's own prioritization judgment layered on top of the analyzer's neutral, unprioritized gap list, never replacing it, and omitted entirely when no purpose is given. The gap-analyzer itself stays neutral and does no prioritization.
• Whole-report caveats surface once. A provenance concern that applies to the whole comparison surfaces once, as an "Analysis caveats" note in Section 4. The most common case: the desired-state artifact is a provided, uncommitted, same-session source. This caveat is not repeated as a finding on every gap, and it is not folded into any gap's confidence. The evidence rule's scrutiny for provided sources is preserved; only the per-gap noise is removed.
• Stable G-NNN gap IDs. Every gap gets a citable ID assigned in discovery order. Tickets, threads, and follow-up reports reference the IDs. Sections 3 and 4 cross-reference them without restating the plain-language explanation.
• The swarm runs by default. A minimum viable team ships at every size and you opt out with no swarm if you want the lightweight pass. The swarm's job is to corroborate, contradict, and enrich what gap-analyzer produced, and to surface gaps the analyzer missed because it only thought about one actor type.
• Actor-perspective sweep is built in. junior-developer is a required swarm member. It runs an explicit actor sweep across every gap: enumerate every actor the desired state addresses or implies (human users and sub-roles, API callers, AI agents, integration partners, batch processes, internal services), check whether the gap holds for each actor, and raise proposed_new_gap whenever the analyzer's gap is correct for one actor but a different gap exists for another. The sweep no longer depends on you naming the actors in your prompt. gap-analyzer reports the actors and modes it observed in the desired state, and the skill seeds the sweep with that list as a floor that junior-developer then expands.
• Four sections, progressively disclosed. Executive Summary → Indexed Gaps → optional Technical Details → Swarm Findings (default-on). Reading stops anywhere; what came before stands on its own. Optional sections are physically omitted when not requested, not collapsed.
• IA-designed template. The report template was designed by information-architect against Rosenfeld & Morville's four IA systems, DITA topic typing, LATCH, Mark Baker's "Every Page is Page One", John Carroll's minimalism, JoAnn Hackos's audience-task mapping, and Dan Brown's 8 Principles of IA. The template lives at gap-analysis-report-template.md.

When to use it

Invoke when:

• You have a spec, PRD, requirements doc, or design and want to compare it against an implementation, a shipped feature, or another artifact. "What's missing from X compared to Y," "does the auth module satisfy the auth spec," "did the v3 launch ship everything in the PRD."
• The audience is mixed (product managers, engineering leads, designers, auditors, stakeholders) and the deliverable needs to be a plain-language report rather than raw analyst output with file paths and code identifiers.
• You want a stable, citable index of gaps. Each gap gets a G-NNN ID you can reference in tickets, threads, and follow-up work. The IDs are append-only across sections of the same report.
• You want adversarial validation, actor-perspective coverage, and domain augmentation of the gap list before it goes to stakeholders. The swarm runs by default; reply no swarm if you want the lightweight pass.
• You only named one artifact and a comparison target is implied (for example, "is the auth implementation complete," "what's missing from this feature"). The skill resolves the implied artifact from the project's documentation root, codebase, and prior context.
• You explicitly ask for a bidirectional analysis (current ↔ desired) rather than the default unidirectional pass (current → desired).

Do not invoke for:

• Investigating runtime bugs or failures. Use /investigate for evidence-based root-cause work on a bug. This skill compares artifacts. It does not trace data flow or error paths to a defect.
• Reviewing code correctness, style, or security. Use /code-review for a comprehensive code review of a branch or files, or /post-code-review-to-pr to post the review to a GitHub PR. This skill does not assess correctness of implementation independent of a desired-state artifact.
• Architectural assessment of an existing module. Use /architectural-analysis for coupling, data flow, concurrency, risk, and SOLID alignment of a module. This skill compares a module against a target spec. It does not assess the module on its own architectural merits.
• Iterating on a plan that already exists. Use /iterative-plan-review for multi-pass review of a plan you already drafted. This skill compares two artifacts. It does not refine a single plan in place.
• Auditing whether documentation updates preserved important content. Use the content-auditor agent directly when the question is "did the rewrite drop facts the original carried." This skill compares two distinct artifacts. content-auditor validates a single artifact across a before-and-after.
• Single-artifact analysis with no comparison target, even implied. If there is genuinely no second artifact and no implied target, the work is documentation, investigation, or architectural. Pick the matching skill instead.
• Open-ended research with no comparison target. Use /research to survey options, prior art, or how something works. This skill needs two artifacts to compare; /research needs only a question.

How to invoke it

Run /gap-analysis in Claude Code. Point it at the two artifacts in the same message, or describe them. Paths, URLs, or inline text all work.

Give it:

1. The current state. What exists today: a code directory, a file, a URL, or inline text. Examples: src/auth/, docs/features/bulk-export/feature-implementation-plan.md, https://staging.example.com/api/users. The skill defaults to treating the first input as the current state.
2. The desired state. What is expected: a spec, a PRD, a design doc, a requirements file, a URL, or inline text. Examples: docs/specs/auth.md, https://wiki.example.com/PRD-v3, docs/features/bulk-export/feature-specification.md. The skill defaults to treating the second input as the desired state.
3. Scope, optional. A bounded region to compare (a specific subsystem, feature, section, or capability). Without a scope, the gap-analyzer agent identifies the comparison areas itself by reading both inputs.
4. Mode overrides, optional. By default the skill runs the recommended swarm and omits technical details. If you want a different shape, say so up front. "Skip the swarm" / "no swarm" drops to the lightweight gap-analyzer-only pass. "Lightweight swarm" drops to the minimum two (validator + junior-developer). "Include technical details" adds Section 3. "Run a large swarm" overrides the recommended size. Naming specific specialists adds or removes them from the team.
5. Direction override, optional. The default direction is current → desired (what does the implementation lack relative to the spec). If you want the analysis reversed (what does the spec lack relative to the implementation: scope creep, undocumented capabilities) or fully bidirectional, say so.
6. Purpose, optional. Why you are running the comparison: "before a redesign pass," "to scope the next sprint," "to decide whether to ship." When you state a purpose, the report adds a "Where to start" view naming the few gaps that most block it. Omit it and the view is simply not rendered.

Example prompts that work well:

• /gap-analysis docs/specs/auth.md src/auth/. Compare the auth spec to the auth implementation. Default modes: swarm runs, plain language only.
• /gap-analysis. "Compare what we shipped in the bulk-export feature to what the PRD called for. The result is going to the steering committee on Friday." The swarm runs at the recommended size.
• /gap-analysis docs/features/checkout/feature-specification.md src/checkout/. "No swarm, we just want a first-pass scoping pass." Falls back to the lightweight gap-analyzer-only run.
• /gap-analysis. "Compare the v2 PRD at docs/prd-v2.md against the v3 PRD at docs/prd-v3.md. Bidirectional. We need to see what was added and what was dropped."
• /gap-analysis docs/specs/billing.md src/billing/. "Include technical details; engineers need to act on this." Swarm + Section 3.

The skill states the resolved comparison direction, the chosen size class, the swarm composition, and the chosen modes in a short message before launching gap-analyzer. If you want to correct any of those, say so and the skill adjusts before proceeding.

What you get back

Two files on disk plus an in-channel summary:

• The gap-analysis-report.md. The stakeholder-readable artifact. Four sections, progressively disclosed:
  • Section 1: Executive Summary. Plain-language verdict on overall alignment, a magnitude-at-a-glance table broken down by category (Missing / Partial / Divergent / Implicit), 3-5 bullets describing the shape of the gap thematically, a "what this means for the work ahead" paragraph, and a pointer to subsequent sections. When you stated a purpose for the comparison, the section also opens with a labeled "Where to start" view: up to five gaps that most block that purpose, one reason each.
  • Section 2: Indexed Gaps. A scan-view index table mapping gap IDs to plain-language titles and categories, followed by one self-contained entry per gap. Each entry has plain-language Expected and Current descriptions, a Why it matters paragraph, and a Confidence field (High / Medium / Low) with a one-sentence reason.
  • Section 3: Technical Details (included only when requested). Per-gap technical fidelity: Locations (file paths, anchors), Relevant identifiers (function, class, module names), Specifics of the divergence, Remediation direction, Effort signal (Trivial / Small / Medium / Large / Unknown), Risks / dependencies. Cross-references to Section 2 by G-NNN ID.
  • Section 4: Swarm Findings (included only when a swarm ran). Confirmations, Contradictions, and Augmentations from the swarm, grouped by signal type and cross-referenced by G-NNN ID. Confidence summary table grouping gaps as High / Medium / Low based on swarm corroboration. When the validator raised a whole-report caveat, it appears once here under "Analysis caveats," outside the confidence table.
• The gap-analysis-source.md. The gap-analyzer agent's full structured output, written alongside the report. Contains GAP-NNN entries with evidence pairs (file paths and line numbers, document section headings, URL excerpts), the analyzer's category classifications, and an "Actors and Modes Observed" note recording the actor types and modes the analyzer saw in the desired state (which seeds junior-developer's sweep). The skill maps GAP-NNN to G-NNN in the report. The source file is preserved for engineers who need the raw evidence to act on a gap.
• An in-channel summary with the report path, the source file path, the size class, the modes used, the gap count broken down by category, whether a conditional second round ran (and why), and any open recommendations (for example, "the swarm contradicted three gaps. Adjudicate before remediation," or "two proposed_new_gap entries were surfaced by junior-developer's actor sweep and added to the report").

The two files interlock through shared IDs. Every G-NNN in the report maps back to a GAP-NNN in the source file. Every cross-reference in Sections 3 and 4 of the report names a G-NNN from Section 2.

The default report (swarm runs, plain language only) carries Sections 1, 2, and 4. Section 4 reflects the default-on swarm, and per-gap confidence values in Section 2 are derived from swarm verdicts rather than defaulting to Medium. The lightweight report (no swarm path) is Sections 1 and 2 alone, with every gap at Medium confidence. Adding Section 3 augments the report. It never changes the meaning of Sections 1 and 2.

How to get the most out of it

• Be explicit about which is current and which is desired. The default direction is current → desired (what's missing from the implementation relative to the spec). Reversing the direction yields a different finding shape: scope creep, undocumented capabilities, drift in the desired-state artifact. Name the direction up front when it matters.
• Let the default swarm run unless you have a reason not to. The default modes (swarm runs at the recommended size, plain language only) produce a stakeholder-readable report with High / Medium / Low confidence on each gap and explicit actor-perspective coverage from junior-developer. Drop to the lightweight pass (no swarm) when you're doing rapid first-pass scoping and don't need confidence signals yet.
• Use lightweight when you want some validation but not full coverage. The lightweight mode keeps the two required roles (adversarial-validator and junior-developer) and drops everything else. You get adversarial counter-evidence and an actor sweep without paying for domain specialists when the gaps don't warrant them.
• Match swarm size to the analysis, not the calendar. The skill recommends small (2–3 agents, no synthesizer), medium (4–6 agents with it), or large (6–8 agents with it) based on gap count, distribution across categories, and the domains the gaps touch. Override the recommendation only when you have a specific reason (for example, the analysis touches auth even though only two gaps were found: promote to medium and include adversarial-security-analyst).
• Name specialists you know you want. If gaps cluster in a single domain (auth, data, UX, deployment, resilience, architecture), naming the matching specialist (adversarial-security-analyst, data-engineer, user-experience-designer, devops-engineer, on-call-engineer, software-architect, system-architect) ensures they are included regardless of what the heuristic would have picked. The three required swarm roles (adversarial-validator, junior-developer, plus evidence-based-investigator when the current state is concrete) are always there.
• Expect a second round when the swarm finds the analyzer missed an actor type. When the first-round swarm surfaces ≥ 3 proposed_new_gap entries or contradictions on ≥ 20% of gaps, the skill runs one additional pass with gap-analyzer to re-scan with the new actor context. That round is scoped to find additional gaps in the under-covered actor or behavior class, plus recategorizations and withdrawals; it does not re-confirm gaps the swarm already corroborated. It is bounded to one extra round, never iterative beyond that.
• State your purpose to get a "Where to start" shortcut. On a long report, the fastest way to cut through it is to tell the skill why you are comparing ("before a redesign pass," "to scope the next sprint"). The report then opens with a short, labeled list of the gaps that most block that goal. Without a purpose, you get the full unprioritized list and no shortcut. That is the right default when there is no single goal to prioritize against.
• Pair with /plan-implementation downstream. Once a gap analysis identifies the gaps, /plan-implementation produces a committable plan to close them. The pairing is natural: the gap report's Section 2 IDs become work items in the implementation plan; Section 3 (when present) feeds the technical detail straight into the plan's Implementation Approach section.
• Pair with /plan-a-phased-build when remediation spans phases. When the gap report shows gaps that cannot all be closed in one deliverable slice, run /plan-a-phased-build with the gap report as the source. The G-NNN IDs become source citations on the phase entries that close them, and the phased plan flows into /plan-implementation per phase.
• Pair with /iterative-plan-review upstream. When the desired-state artifact is itself a plan you don't yet trust, run /iterative-plan-review on it first. A gap analysis against a flawed desired-state produces flawed gaps. Hardening the desired-state before comparing pays for itself.
• Re-run after the spec or implementation changes. A gap analysis is a point-in-time artifact. It does not auto-refresh. After the implementation closes gaps (or after the spec changes), re-run the skill. The new report's G-NNN IDs are independent of the prior run's. The prior report stays valid as a snapshot.
• Use bidirectional mode when the desired-state artifact is itself drifting. Bidirectional analysis catches the current state has capabilities the desired state never specified failure mode: scope creep, undocumented behavior, capabilities that were shipped without an explicit spec. The default unidirectional pass misses this entirely.
• Read Section 1 even if you wrote it. The IA-designed template is structured so a stakeholder reading only Section 1 has a complete (low-resolution) understanding of the gap. Use it as a sanity check on your own framing. If Section 1 doesn't read well to a non-technical audience, the executive-summary translation step in the skill needs adjusting and you should re-run with a sharper prompt.

Sizing

Size determines the swarm composition. The skill defaults to small and only escalates when concrete signals require it. Every size ships with a swarm by default; opt out with no swarm if you want the lightweight gap-analyzer-only pass.

Size	Gap count	Domain signals	Swarm composition
Small (default)	0–3 total gaps	Single domain (one feature, one module, one document section); no security / data / cross-service / architectural signals in any gap.	2–3 agents. adversarial-validator and junior-developer always, plus evidence-based-investigator when the current state is concrete. No synthesizer.
Medium	4–10 total gaps	Two or three adjacent domains; may touch one cross-cutting concern (a single auth surface, a single integration boundary, a single data-contract change).	4–6 agents. Required three (adversarial-validator, junior-developer, evidence-based-investigator) plus 1–2 domain specialists plus plan-synthesizer for Section 4 synthesis.
Large	11+ total gaps	Cross-cutting concerns across multiple domains (security + data + architecture, or cross-service integration), or you explicitly requested a full swarm.	6–8 agents. Required three plus 2–4 domain specialists plus plan-synthesizer.

How the size is chosen:

• Default to small. Unless the gap count or domain signals push the analysis higher, the skill stays at small.
• Domain-driven specialist selection. Augmenters are drawn from adversarial-security-analyst, data-engineer, user-experience-designer, devops-engineer, on-call-engineer, system-architect, software-architect, content-auditor, codebase-explorer based on which domains the gaps touch.
• The swarm runs by default at every size. The lightweight (no swarm) path is an explicit opt-out.

How to override the size:

• Pass small, medium, large, or dynamic as the first positional argument: /gap-analysis medium, /gap-analysis large docs/specs/auth.md src/auth/.
• When the size is overridden via $size, the skill announces the override (Medium: passed via $size) and uses the chosen band for the swarm composition.
• Pass dynamic when a project or personal .han/config.md sets a default band and you want this one run sized from the artifacts' own signals instead.
• Conversational overrides ("run a large swarm anyway") still work and are equivalent.

For the cross-skill sizing model and design principles, see Sizing.

Cost and latency

The default run carries the swarm. Opting out (no swarm) is the cheapest configuration and is appropriate for rapid first-pass scoping where confidence signals are not yet needed.

• Default mode (swarm runs at the recommended size, plain language only). One gap-analyzer dispatch plus the swarm fan-out (2–8 sub-agents in parallel depending on size). At small, that's 3–4 total dispatches (analyzer + 2–3 swarm agents). At medium, 5–7 (analyzer + 4–6 swarm agents). At large, 7–9 (analyzer + 6–8 swarm agents). The swarm runs in a single parallel round; plan-synthesizer runs after at medium and large to consolidate Section 4 content, then han-communication:readability-editor rewrites the consolidated report for readability, preserving every fact and G-NNN gap ID. The conditional second round (Step 5.5) fires when the swarm produces ≥ 3 new gaps or contradictions on ≥ 20% of original gaps. When it fires, add one more gap-analyzer dispatch, never more.
• Lightweight mode (no swarm). A single gap-analyzer dispatch plus the skill's in-process rendering of Sections 1 and 2. No additional sub-agents. Every gap shipped at Medium confidence. Lowest-cost configuration.
• Technical details mode (Section 3 added). No additional sub-agents. Section 3 is rendered by the skill from the gap-analyzer's existing structured output: file paths, identifiers, and divergence specifics already in the source file. Cost equals the surrounding mode (default or lightweight) plus a marginal rendering pass.

The skill is built for periodic, decision-point analysis (before a steering committee, before a remediation plan, after a release), not for tight-loop iteration on the same comparison within a single session. Re-running the skill is appropriate after a spec or implementation has materially changed. Running it repeatedly against the same inputs in the same session does not produce new insight.

In more detail

The skill's input is two artifacts and its output is a stakeholder-readable report. The judgment-heavy work (identifying comparison areas, mapping correspondences, classifying gaps into the Missing / Partial / Divergent / Implicit taxonomy, gathering evidence pairs from both inputs) happens inside the gap-analyzer agent. The skill orchestrates that agent, runs a validator-and-augmenter swarm by default, then translates the analyzer's structured output into the IA-designed template.

Default-on swarm posture. The swarm runs by default for three reasons.

First, gap-analyzer is generalist by design: it identifies feature-and-behavior correspondences across two artifacts. It reports the actor types and modes it observed in the desired state, and the skill seeds junior-developer with that list, but the analyzer does not itself reason about whether each gap holds per actor. junior-developer's actor sweep catches the failure mode where a gap is correct for human users but a different gap exists for API callers or AI agents that the analyzer never considered, expanding past the observed-actor floor.

Second, the swarm produces per-gap confidence signals (High / Medium / Low) that change how stakeholders prioritize. Stakeholder-readable reports benefit from confidence even when the gap list is small.

Third, contradictions surfaced by adversarial-validator are decision-bearing: they need adjudication before remediation. Waiting for a stakeholder to opt in to discover them would be the wrong default.

The lightweight (no swarm) path remains available for rapid first-pass scoping where confidence is not yet a decision input.

Required swarm roles. At every size, the swarm includes adversarial-validator (attacks gap-analyzer's findings with counter-evidence) and junior-developer (runs the actor-perspective sweep across human users, API callers, AI agents, integration partners, batch processes, and internal services). evidence-based-investigator is required when the current state is concrete enough to verify against, effectively always at medium and large. plan-synthesizer is required at medium and large to consolidate Section 4 content from the four-or-more specialist outputs; at small (two or three agents) the skill consolidates deterministically without it.

Sizing rule. Small analyses (0-3 gaps, single domain, no security / data / cross-service signals) ship the minimum viable swarm (2–3 agents, no synthesizer). Medium analyses (4-10 gaps, two or three adjacent domains, may touch one cross-cutting concern) ship a 4–6 agent swarm with the synthesizer. Large analyses (11+ gaps, multi-domain cross-cutting concerns, security or data implications, or explicit user request) ship a 6–8 agent swarm with the synthesizer. Augmenters are drawn from the standard han specialist roster based on what the gaps touch.

Conditional second round. Single-round parallel fan-out captures most of the value. The one failure mode it can miss is the analyzer systematically excluding an actor type. For example, comparing a spec written for human users against an implementation that also serves API callers, where every gap-shaped finding has a parallel API-caller-shaped finding the analyzer never considered. When the first-round swarm surfaces ≥ 3 proposed_new_gap entries (Trigger A) or contradictions on ≥ 20% of gaps (Trigger B), the skill re-dispatches gap-analyzer once with the new actor context and merges the delta into the source file. A fired trigger is a proxy for an under-covered actor or behavior class; the proposed gaps are a symptom of it. So the round re-scans that class for additional gaps and surfaces recategorizations and withdrawals, and is explicitly told not to spend the pass re-confirming gaps the swarm already corroborated. Bounded to one extra round.

Plain-language translation. The gap-analyzer agent produces structured output rich in technical detail: file paths, line numbers, document anchors, code identifiers. The skill's render step translates each gap's Expected, Current, and Why it matters content into plain language for Sections 1 and 2. It strips every code or document-mechanic reference and replaces it with a capability-or-behavior description. Technical fidelity is preserved in gap-analysis-source.md and, when you opt in, surfaces in Section 3 with full evidence pairs intact.

Append-only G-NNN IDs. Gap IDs are assigned in the order the analyzer surfaced the gaps, including any proposed_new_gap entries the swarm added. IDs are stable for the life of the report and not renumbered if a re-run produces a different gap set. Re-running creates a new report, with its own ID space, rather than editing the prior report in place.

Optional sections are physically omitted. When Section 3 or Section 4 is not requested or generated, the skill removes the section from the rendered output entirely (and removes the corresponding sections_included entry from the front matter). The "How to Read This Report" frame at the top of the template is rewritten to reflect what was included so a reader is never promised a section that does not exist.

Sources

The skill draws on two distinct provenance lines: the gap-analysis vocabulary itself, and the IA frameworks the report template was designed against.

Gap-analysis taxonomy and protocol

The four-category taxonomy (Missing / Partial / Divergent / Implicit) and the evidence-pair requirement come from the gap-analyzer agent's protocol, which is itself grounded in software-engineering specification practice. The taxonomy is the agent's own vocabulary. The skill renders gap entries using that taxonomy verbatim because translating "Missing" or "Partial" into looser language would degrade the precision a stakeholder needs to decide what kind of remediation each gap requires.

URL: see gap-analyzer agent definition

Rosenfeld & Morville: Information Architecture (4th edition)

The four IA systems (organization, labeling, navigation, search) are the foundation of the report's structure. The four-section progressive-disclosure design is an organization system. The gap categories and severity vocabulary are a labeling system. The index table at the top of Section 2 plus the G-NNN cross-references throughout Sections 3 and 4 form the navigation system. The stable, append-only IDs make Cmd-F search durable across the report's lifetime.

URL: https://www.oreilly.com/library/view/information-architecture-4th/9781491913529/

JoAnn Hackos: Audience-Task Mapping and DITA Topic Typing

Hackos's audience-and-task mapping informs the section split. Section 1 serves stakeholders doing a triage task. Section 2 serves PMs and leads doing a discuss-and-prioritize task. Section 3 serves engineers doing an implement task. Section 4 serves anyone doing a trust-and-adjudicate task.

DITA's concept / task / reference distinction informs the topic-type discipline within sections: Section 1 is concept, Section 2 is a reference list of concept entries, Section 3 is reference + task, Section 4 is reference.

URL: https://www.xmlpress.net/publications/dita-third-edition/

Mark Baker: Every Page is Page One (EPPO)

Baker's EPPO discipline shapes the per-gap entry format in Section 2. Each entry is self-contained: a reader landing on a single gap via search or a deep link gets oriented (what it is, what was expected vs. current, why it matters, how confident we are) without needing to read the rest of the report. The "How to Read This Report" frame at the top of the template is the EPPO orientation for cold arrivals to the report itself.

URL: https://everypageispageone.com/

Richard Saul Wurman: LATCH

Wurman's LATCH (Location, Alphabet, Time, Category, Hierarchy) framework drove the choice of indexing scheme for gaps. The IDs use the Location / sequence dimension (assigned in discovery order, append-only, stable for the report's life) rather than Category (Missing/Partial/Divergent/Implicit) because grouping by category fragments the index and prevents a single citable list. Category appears as a facet on each entry, not as the grouping axis.

URL: https://www.wurman.com/books/

John Carroll: Minimalism

Carroll's minimalism principles inform the template's "no throat-clearing" stance. There is no meta-introduction. The "How to Read" frame replaces it. Tables replace prose where lookup is the task. Optional sections are physically omitted (not collapsed) when they are not generated, so a reader scanning the report never reads "Section 3 was not included" when they could read nothing instead.

URL: https://mitpress.mit.edu/9780262531313/the-nurnberg-funnel/

Dan Brown: Eight Principles of Information Architecture

Brown's principle of Disclosure underpins the section ordering and the optional-section placement. Sections 1 and 2 are load-bearing. Sections 3 and 4 sit below them, so removing the optional sections never breaks the sections above.

The principle of Multiple Classification supports the indexing decision: each gap is classified by category but located by sequence ID. Readers who want to scan by category use the index table; readers who want to cite a gap use the ID.

URL: https://eightprinciples.com/

Adversarial Review and Devil's Advocate Practice

The default-on swarm's role mirrors the same red-team / devil's-advocate practice that powers /code-review and /iterative-plan-review team mode. adversarial-validator attacks each gap-analyzer finding with counter-evidence. evidence-based-investigator verifies each gap against the current state. junior-developer runs an actor-perspective sweep to catch gaps the analyzer missed because it only considered one actor type. Augmenters add domain context the generalist gap-analyzer may have missed. The pattern is documented in Klein's pre-mortem literature and the broader red-teaming tradition.

URLs: https://hbr.org/2007/09/performing-a-project-premortem and https://en.wikipedia.org/wiki/Red_team

Related documentation

• Plugin README. The plugin's front door: its skills, agents, and how they fit together.
• Repo root README. The Han suite landing page. Start here if you arrived from outside the docs tree.
• Skills Index. All skills, grouped by purpose.
• Sizing. The cross-skill sizing model. Explains the small / medium / large bands, the default-to-small rule, and the $size override.
• Evidence. The canonical evidence rule the skill applies when characterizing each gap's evidence pair. Trust classes, the corroboration gate for web-source claims, and the no-evidence label for silent desired-state evidence.
• gap-analyzer. The agent that performs the underlying gap analysis. The skill always dispatches it once and reads its full output.
• adversarial-validator. Required swarm role at every size. Attacks each gap with counter-evidence to produce per-gap confirmed / contradicted / inconclusive verdicts.
• junior-developer. Required swarm role at every size. Runs the actor-perspective sweep: enumerates every actor the desired state addresses or implies, checks each gap against every actor type, surfaces gaps the analyzer missed because it only considered one actor.
• evidence-based-investigator. Required swarm role when the current state is concrete (codebase, document on disk, fetchable URL). Verifies each gap against the current state with file-level evidence.
• plan-synthesizer. Required swarm role at medium and large. Consolidates the four-or-more specialist outputs into Section 4 of the report and produces per-gap confidence values. Not called at small.
• readability-editor. Dispatched on the consolidated reports (medium and large, where plan-synthesizer ran) to rewrite the report against the shared readability standard, preserving every fact and gap ID. Skipped at small and on the no swarm path.
• information-architect. The agent that designed the report template. The template is a one-time IA design output. The agent is not dispatched at runtime.
• /iterative-plan-review. Pair upstream when the desired-state artifact is itself a plan you do not yet trust. Hardening the desired state before comparing produces sharper gaps.
• /plan-implementation. Pair downstream when the gap report will drive remediation work. The gap report's Section 2 IDs become work items. Section 3 (when present) feeds the implementation plan's Implementation Approach.
• /investigate. The sibling skill for runtime bug investigation. Use /investigate when the question is "why is this broken". Use /gap-analysis when the question is "how does this compare to what was specified."
• /code-review. The sibling skill for code-level quality review. Use /code-review when the question is about correctness, style, or security. Use /gap-analysis when the question requires a comparison against a specification.
• Report template. The IA-designed template the skill renders. The template's front matter, "How to Read This Report" frame, and section structure are the canonical reference for the report's shape.