Gap Scan

Gap Scan — demand × supply → market gaps

Three stages: demand pass (is anyone asking for this?) → supply audit (who serves it, and how well?) → gap verdict. Every claim carries a URL — this pipeline exists because market research is only trustworthy when it's verifiable.

Before starting: if the user keeps a written set of idea-evaluation principles or gates, read it first so the verdicts route into it. One rule is load-bearing here regardless: competition is evidence, not a red flag. A well-served market is never an auto-kill.

Tools

Paths are relative to this skill's directory (the folder containing this SKILL.md). The demand-check skill is expected as a sibling directory; set SKILL_DIR first:

SKILL_DIR=<directory containing this SKILL.md>    # e.g. ~/.claude/skills/gap-scan

# Stage 1 muscle — the sibling demand-check skill, if it is installed beside this one.
# Installed alone (--skill gap-scan), these two paths will not exist: either install
# demand-check too, or skip to Stage 2 and gather demand evidence with web search.
# See that skill's SKILL.md for setup and caveats.
DPY=$SKILL_DIR/../demand-check/.venv/bin/python
DCLI=$SKILL_DIR/../demand-check/scripts/demand.py

# Stage 1+2 muscle — this skill's stdlib-only wrappers (plain python3, no venv):
SIG=$SKILL_DIR/scripts/signals.py
python3 $SIG hn "ableton mcp"              # HN stories: points, comments, dates, links
python3 $SIG hn "x" --recent               # newest-first (frontier pain shows up here early)
python3 $SIG npm "@scope/pkg"              # 12-mo download trend + verdict
python3 $SIG pypi somepkg                  # flaky upstream; falls back per its error hint
python3 $SIG reddit "x"                    # 403s unauthenticated (2026-07) — use the
                                           # WebSearch fallback below instead

Channel notes (verified live 2026-07-22):

• Reddit blocks unauthenticated JSON. Mine it via WebSearch site:reddit.com "<pain phrasing>", then WebFetch the promising threads. Pain phrasings that work: "is there a tool", "how do I X without", "alternative to", "X sucks", "why is there no".
• GitHub goes through the authenticated gh CLI (better rate limits than anonymous API):
  • Incumbents: gh search repos "<topic>" --sort stars --limit 15 --json fullName,description,stargazersCount,updatedAt
  • Feature gaps users beg for: gh search issues --repo <owner/repo> --state open --sort reactions --limit 10 --json title,reactionGroups,url
  • Maintenance: last release / commit dates via gh api repos/<owner/repo> --jq '{pushed_at, open_issues_count}'
• App/Chrome-store and G2/Capterra 1-3★ reviews of incumbents are the "does it do the whole job well?" dataset — WebFetch the review pages directly.

Stage 1 — Demand pass

Goal: turn the seed into 3-5 demand pockets, each with dated evidence.

1. demand-check suggest (free, unlimited) on the seed + obvious variants; --deep if the seed is broad.
2. Trends (trend/explore) on only the 2-3 terms that matter — pulls are soft-block-prone; space them.
3. Pain mining: $SIG hn (both relevance and --recent), WebSearch over Reddit, YouTube tutorial comments where relevant.
4. Willingness-to-pay probes where the pocket suggests money: Keyword Planner CPC (manual, note it), Fiverr/Upwork gig counts + pricing for the manual version of the task (WebSearch/WebFetch).

A pocket = a one-line demand statement + its evidence block (trend verdict, autocomplete tail, 2-3 complaint quotes with URLs, WTP signal if any).

Stage 2 — Supply audit (per pocket)

For pockets that survive Stage 1, fan out one subagent per pocket (they're independent — run them in parallel via the Agent tool). Each audit:

1. Enumerate incumbents — gh search, WebSearch (" tool/app/plugin"), Product Hunt, relevant registries (mcp.so/PulseMCP for agent tools, app stores for consumer).
2. Grade each incumbent on three axes, evidence per cell:
   • Coverage — whole demand or a slice? (feature list vs. the pocket's demand statement)
   • Quality — 1-3★ review themes, top-reacted open issues, community sentiment
   • Momentum — last commit/release, download/star velocity ($SIG npm), team size/funding if visible
3. Capture the complaint themes verbatim — for an UNDERSERVED verdict these are the roadmap.

Stage 3 — Gap verdict

Per pocket, exactly one of:

• UNSERVED — demand evidence but no credible supply. Treat with suspicion: usually the demand isn't real either (or isn't reachable). Requires the strongest Stage-1 evidence to stand.
• UNDERSERVED — real demand, weak/partial/stale supply. The sweet spot. List the specific complaints the gap-filler would fix.
• WELL-SERVED — real demand, good supply. Not a kill: this is validated demand. Verdict output = "enter only with a named wedge + a distribution edge," and name the candidate wedge if one is visible.

Then run the surviving gap(s) through the gates that data can't answer: why-now, moat/distribution, founder-fit, model-timing.

Output

1. Write the report to a file, so it can be cited later: gap-scans/<seed>-YYYY-MM-DD.md in the current project, or the equivalent folder in the user's notes directory if they keep one (create the folder if missing). Contents: pockets, evidence blocks, incumbent grade tables, verdicts, gate notes. Every factual claim gets its URL.
2. Chat summary: the verdicts and the single most decision-relevant fact per pocket — not the firehose.

Hand-offs

• Gap looks real → /idea-check <the idea> for the calibrated-realism pass.
• The user agrees it's worth taking on → suggest evolving the variation and building the pitch/plan as the next step. That is the deliberate next step after conviction, not part of this chain — don't auto-run it.
• Scores/state worth keeping → the project's own scorecard or notes (evidence, dated), if it keeps one.