Gap Analysis

Gap Analysis

Run a systematic literature gap analysis for an engineering sub-topic. This skill wraps scholarly-research for source discovery and adds the gap-validation methodology on top.

Workflow

flowchart LR
    Input["Discipline + Sub-topic"] --> Search["Narrow-Query Search"]
    Search --> Triangulate["Triangulate Sources"]
    Triangulate --> Validate["Validate Gap Signal"]
    Validate --> Dossier["Gap Dossier + Provenance"]

Invocation

/gap-analysis   [--deep | --quick]

• discipline: one of civil, mechanical, electrical, software, architectural
• sub-topic: narrow focus within the discipline (e.g., FRP-bonding, hydrogen-embrittlement). Required — if the user doesn't provide one, ask.
• --deep: Force parallel verification lanes for all gap validation claims.
• --quick: Skip parallel verification, use single-source checks only.
• No flag: Auto-scale based on gap criticality (safety-related gaps get parallel verification).

Methodology (Execute This)

Phase 1 — Narrow-Query Search (wrap scholarly-research)

For the target sub-topic, construct a narrow search query and run it through OpenAlex using title_and_abstract.search:

GET https://api.openalex.org/works?filter=title_and_abstract.search:&per-page=20&select=id,display_name,publication_year,cited_by_count,doi,open_access,best_oa_location,authorships

Then run the same query on arXiv:

GET https://export.arxiv.org/api/query?search_query=all:&max_results=20

Gap signal: If the narrow query returns 0–5 hits, and the top hits are off-topic, low-citation ( methodology > citation authority > reproducibility > recency.

Output

Inline Summary (chat response)

• Gap statement (1-2 sentences)
• Confidence: High | Medium | Low (based on triangulation completeness)
• Validation counts: OpenAlex hits, arXiv hits, web "open problem" signals
• Top 3 edge papers: [first author, year] — covers X, misses Y [Tier N]
• 3-5 concrete, answerable research questions
• Path to full dossier on disk

Full Dossier (saved to disk)

Match the structure of existing gap-analysis//-.md files in this repository. Required sections:

• What's Missing — specific knowledge gap description
• Why It Matters — safety, economic, societal stakes
• Suggested Research Questions — 3-5 concrete, answerable
• Key Papers (Touching the Edges) — 4-7 papers with Authors, Year, DOI/URL, Covers, Misses, Tier
• Validation — OpenAlex query + hits + date, arXiv query + hits + date, web sources, open problem signals
• Confidence — High | Medium | Low with justification

Write the dossier to outputs/gap-analysis/.md and a provenance sidecar to outputs/gap-analysis/.provenance.md.

Quality Gate (mandatory before returning)

Self-check the output. If any check fails, retry once with feedback:

1. Gap count — at least 3 distinct gaps identified. If < 3, re-search with broader terms.
2. Source count — at least 4 key papers referenced. If < 4, expand search to additional databases.
3. Triangulation — at least 2 source tiers represented (e.g., OpenAlex + arXiv). If only 1, search missing tier.
4. Research questions — at least 3 concrete, answerable questions. If < 3, refine gap analysis.
5. Confidence justification — Confidence level has explicit justification. If missing, add reasoning.

Retry logic: If quality gate fails, re-run the search phase once with the specific failure as feedback. If it fails again, return the best output with a PARTIAL confidence and list the unresolved issues in provenance.

Scope and Boundaries

• This skill identifies gaps — it does not fill them. For filling gaps,

dispatch to engineering-research.

• Output is research-only, not design or implementation guidance.
• Fail-closed: if triangulation cannot be completed, mark the gap unverified

rather than claiming it exists.

• Never fabricate a gap. If the literature adequately covers the topic, say so.
• When a source is paywalled or unreachable, cite from metadata and mark blocked.

See references/blocked-access-policy.md for the full rules.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adeerkhan
• Source: adeerkhan/vitruvius
• License: MIT

Install and usage instructions live in the source repository linked above.