refactor(discovery): extract blindspot mode from explore into its own skill (#259)

plugins/discovery/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "discovery",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Structured discovery before changes: explore the local codebase (inline or in an isolated forked subagent) and run disciplined multi-source external research with source tiers, falsification, and recency gates — persisting EXPLORE.md / RESEARCH.md handoff artifacts.",
   "author": {
     "name": "Melodic Software",

plugins/discovery/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog — discovery plugin
 
+## [0.8.0] — 2026-07-20
+
+### Added
+
+- **`/discovery:blindspot` — blindspot mode extracted from `/discovery:explore` into its own skill.**
+  Surfacing the USER's unknown-unknowns before they work in unfamiliar territory (a codebase area or a
+  domain vocabulary) is a distinct responsibility with a distinct output contract — blindspot cards and
+  one improved prompt, no `EXPLORE.md`, and the explore outcome gate skipped — that had been grafted onto
+  explore. It now lives in `skills/blindspot/` with its own frontmatter, workflow, and evals.
+
+### Changed
+
+- **`/discovery:explore` is trimmed back to its core responsibility** — codebase investigation, the
+  `EXPLORE.md` handoff artifact, and the outcome gate. The blindspot mode/table row, its two artifact-skip
+  clauses in the outcome gate and final step, and the blindspot domain-lane research carve-out are removed;
+  a one-line pointer to the sibling `/discovery:blindspot` skill replaces the extracted section. Cross-plugin
+  references (`plugins/discovery/README.md`, `plugins/planning/skills/interview/SKILL.md`) now point at the
+  new skill.
+
 ## [0.7.3] — 2026-07-19
 
 ### Fixed

plugins/discovery/README.md

@@ -2,17 +2,21 @@
 
 A Claude Code plugin for **structured discovery before changes** — understand what
 IS (the local codebase) and what SHOULD BE (current external sources) before any
-code is written. Four skills, two axes: local vs external, inline vs isolated.
+code is written. The explore/research skills sit on two axes — local vs external,
+inline vs isolated — with `blindspot` as a fifth skill that serves the USER's
+understanding rather than the agent's.
 
 | Skill | Axis | What it does |
 |---|---|---|
-| `/discovery:explore` | Local, inline | Six-dimension codebase exploration — code reading, git history, project structure, test discovery, build config, environment — plus a `blindspot` mode that surfaces the USER's unknown-unknowns and coaches a better prompt. |
+| `/discovery:explore` | Local, inline | Six-dimension codebase exploration — code reading, git history, project structure, test discovery, build config, environment — persisting an `EXPLORE.md` handoff artifact. |
 | `/discovery:explore-deep` | Local, isolated | The same explore workflow in a forked subagent: verbose reads and search output stay in the fork; only a short summary returns, with findings persisted to `EXPLORE.md`. Requires `CLAUDE_CODE_FORK_SUBAGENT=1`. |
 | `/discovery:research` | External, inline | Three chained research phases (broad → targeted + falsification → preferred sources) with per-claim source tiers, independent-corroborator ratios, a recency gate, and a binary outcome gate before presenting. |
 | `/discovery:research-deep` | External, isolated | Dispatcher that routes deep research to the heaviest isolated tier available — a deep-research workflow engine, a forked subagent, or inline as last resort — with a multi-topic check that fans out one agent per separable topic. |
+| `/discovery:blindspot` | Local, user-facing | Surfaces the USER's unknown-unknowns before they work in unfamiliar territory (a codebase area or a domain vocabulary), emitting blindspot cards and coaching one improved prompt. Deliverable is the user's understanding, not `EXPLORE.md`. |
 
-Both inline skills persist handoff artifacts (`EXPLORE.md` / `RESEARCH.md`) so a
-fresh session can resume planning from the artifact alone.
+The two artifact-persisting skills (`/discovery:explore`, `/discovery:research`)
+persist handoff artifacts (`EXPLORE.md` / `RESEARCH.md`) so a fresh session can
+resume planning from the artifact alone.
 
 ## Works in any repo
 

plugins/discovery/skills/blindspot/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: blindspot
+description: "Surface the USER's unknown-unknowns before they work in unfamiliar territory — an unfamiliar codebase area OR an unfamiliar domain vocabulary — and coach a sharper prompt. Scans for gaps the user's framing missed, emits one blindspot card per gap (the gap, why it matters here, a copyable prompt-fix line), then assembles the fixes into one improved implementation prompt. Use when about to work somewhere you don't know well and the goal is a better prompt, not the codebase handoff artifact /discovery:explore produces."
+argument-hint: "[area-or-domain] (e.g., /discovery:blindspot geofencing, /discovery:blindspot payments module, /discovery:blindspot <domain-vocabulary>)"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## Pre-computed context
+
+Current branch: !`git branch --show-current 2>/dev/null || echo "unknown"`
+Project root: !`git rev-parse --show-toplevel 2>/dev/null || echo "unknown"`
+
+These values orient this session only; resolve files against the project root while working.
+
+## Purpose
+
+Every mode of `/discovery:explore` builds the AGENT's local knowledge and hands off an `EXPLORE.md`
+artifact. Blindspot mode builds the USER's knowledge and hands off a better prompt — a different
+audience and a different deliverable, which is why it is its own skill.
+
+Run it when the user is about to work in territory they don't know — an unfamiliar codebase area OR
+an unfamiliar domain vocabulary — and the goal is to surface what their framing didn't account for
+so they can write a sharper implementation prompt. The output is calibrated to the user's disclosed
+starting point, not to a fixed depth.
+
+Local counterpart discipline to `/discovery:explore` (what IS in the codebase) and `/discovery:research`
+(what SHOULD BE from external sources): blindspot borrows from both lanes but serves the user's
+understanding rather than the agent's.
+
+## Workflow
+
+1. **Intake** — ask the user's starting point first (one question). Blindspot output calibrates to
+   that disclosure — what they already know bounds which gaps are worth surfacing.
+2. **Scan** — two lanes, chosen by what is unfamiliar:
+   - **Codebase lane** — read the target area (the codebase-reading, git-history, and project-structure
+     dimensions of [`${CLAUDE_PLUGIN_ROOT}/skills/explore/SKILL.md`](${CLAUDE_PLUGIN_ROOT}/skills/explore/SKILL.md))
+     looking specifically for things the user's framing missed: existing patterns they'd duplicate,
+     constraints they'd violate, historical decisions they'd re-litigate, adjacent code their change
+     would break.
+   - **Domain lane** — build a lightweight vocabulary ladder grounded in sources fetched this session
+     (repo files, official docs) — never bare training recall.
+3. **Output — blindspot cards.** One card per blindspot: the gap, why it matters here, and a copyable
+   prompt-fix line. Close by assembling the fixes into ONE improved implementation prompt the user can
+   run next.
+4. **Escalate when depth warranted** — a domain too deep for a lightweight ladder gets a recommendation
+   to run proper external research (`/discovery:research`) or whatever structured-learning capability
+   the environment provides.
+
+## Output format
+
+Present each blindspot as a card:
+
+- **Gap** — the specific thing the user's current framing did not account for.
+- **Why it matters here** — the concrete consequence in this codebase or domain, not a generic caution.
+- **Prompt-fix** — a single copyable line the user can drop into their prompt to close the gap.
+
+Then assemble every prompt-fix into ONE improved implementation prompt, wrapped in clear
+copy-start / copy-end markers so the exact text to reuse is unambiguous.
+
+This skill does NOT write `EXPLORE.md` — its deliverable is the user's understanding plus the improved
+prompt. When the scan's findings also serve as stage-1 codebase exploration, offer to hand off to
+`/discovery:explore` (or `/discovery:explore-deep`) to persist the `EXPLORE.md` artifact rather than
+duplicating that responsibility here.
+
+## Gotchas
+
+- **Presenting training recall as domain fact** — the domain lane grounds its vocabulary ladder in
+  sources fetched this session (repo files, official docs). Bare recall is the failure mode this
+  skill exists to avoid, not commit.
+- **Surfacing the agent's gaps instead of the user's** — cards name what the USER's framing missed,
+  calibrated to their intake disclosure, not a generic audit of the area.
+- **Generic cautions in "why it matters"** — each card's consequence is concrete to this codebase or
+  domain; a caution that would read the same in any repo is not a blindspot.
+- **Writing an artifact by reflex** — no `EXPLORE.md` unless the user opts into the explore handoff.
+
+## What this skill does NOT do
+
+- **Does not produce the `EXPLORE.md` handoff** — that is `/discovery:explore`. Hand off to it when the
+  findings double as stage-1 exploration.
+- **Does not make changes** — it surfaces blindspots and coaches a prompt. Execution is a separate step.
+- **Does not run open-ended external research** — the domain lane fetches official docs to ground a
+  lightweight vocabulary ladder; anything deeper routes to `/discovery:research`.

plugins/discovery/skills/blindspot/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "skill_name": "blindspot",
+  "evals": [
+    {
+      "id": 1,
+      "name": "blindspot-builds-user-knowledge",
+      "prompt": "I'm about to start working in the geofencing area and I honestly don't know it well. Run blindspot geofencing so I write a better prompt.",
+      "expected_output": "Enters the blindspot workflow: asks one intake question about the user's starting point, scans the area (codebase lane) for things the user's framing missed, emits one blindspot card per gap (gap, why it matters here, copyable prompt-fix line), and assembles the fixes into one improved implementation prompt. Does NOT write EXPLORE.md.",
+      "files": [],
+      "expectations": [
+        "Output builds the USER's understanding (blindspot cards + an improved prompt), not just the agent's internal findings",
+        "The run asks one intake question about the user's starting point before scanning",
+        "Each blindspot is expressed as a card naming the gap, why it matters here, and a copyable prompt-fix line",
+        "Output closes by assembling the fixes into a single improved implementation prompt the user can run next",
+        "The run does not write EXPLORE.md"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "domain-lane-grounds-in-sources-not-recall",
+      "prompt": "I need to work on our event-sourcing projections but I don't know the domain vocabulary. Run blindspot on event sourcing so I understand the terms before I write a prompt.",
+      "expected_output": "Runs the domain lane: builds a lightweight vocabulary ladder grounded in sources fetched this session (repo files, official docs) rather than bare training recall, emits blindspot cards for the terms/assumptions the user's framing missed, and assembles an improved prompt. If the domain is too deep for a lightweight ladder, it recommends escalating to external research (/discovery:research) instead of over-claiming.",
+      "files": [],
+      "expectations": [
+        "The domain vocabulary ladder is grounded in sources fetched this session (repo files or official docs), not presented as bare training recall",
+        "Output is expressed as blindspot cards plus a single improved prompt",
+        "When the domain is too deep for a lightweight ladder, the run recommends escalating to external research rather than fabricating depth"
+      ]
+    },
+    {
+      "id": 3,
+      "name": "offers-explore-handoff-not-duplicate-artifact",
+      "prompt": "Run blindspot on the payments module — and if the scan is thorough enough, save it as our exploration notes.",
+      "expected_output": "Produces blindspot cards and an improved prompt, and when the codebase-lane findings double as stage-1 exploration, offers to hand off to /discovery:explore (or explore-deep) to persist EXPLORE.md rather than writing that handoff artifact itself.",
+      "files": [],
+      "expectations": [
+        "Output produces blindspot cards and an improved prompt as its primary deliverable",
+        "The run offers to hand off to /discovery:explore (or explore-deep) to persist EXPLORE.md rather than writing the handoff artifact from this skill",
+        "The run does not itself write EXPLORE.md as a default step"
+      ]
+    }
+  ]
+}

plugins/discovery/skills/explore/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: explore
-description: "Explore the local codebase before making changes — read code, trace dependencies, scan git history, discover tests, and audit build and tool configuration. Use as step 1 before any code change, for 'what exists for X' investigation, or in blindspot mode to surface the user's unknown-unknowns in unfamiliar territory."
-argument-hint: "[scope] (e.g., /discovery:explore payments module dependencies, /discovery:explore tests, /discovery:explore git, /discovery:explore config, /discovery:explore blindspot <area-or-domain>)"
+description: "Explore the local codebase before making changes — read code, trace dependencies, scan git history, discover tests, and audit build and tool configuration. Use as step 1 before any code change, or for 'what exists for X' investigation."
+argument-hint: "[scope] (e.g., /discovery:explore payments module dependencies, /discovery:explore tests, /discovery:explore git, /discovery:explore config)"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -115,20 +115,10 @@ The `$ARGUMENTS` value shapes the exploration focus:
 | `git` | Recent change history | `git log`, active branches, recent contributors, change velocity |
 | `config` | Build and tool configuration | Read `.editorconfig`, build configs, analyzer settings, CI workflows |
 | `<file-path>` | Single file deep-dive | Read file, its tests, its callers, its git history |
-| `blindspot <area-or-domain>` | The USER's unknown-unknowns, not the agent's | See "Blindspot mode" below |
 
 Multiple arguments combine: `/discovery:explore payments deps tests` explores that area's dependencies AND test coverage.
 
-## Blindspot mode
-
-Every other mode builds the AGENT's local knowledge; blindspot mode builds the USER's. Run it when the user is about to work in territory they don't know — an unfamiliar codebase area OR an unfamiliar domain vocabulary — and the goal is a better prompt.
-
-1. **Intake** — ask the user's starting point first (one question). Blindspot output calibrates to that disclosure.
-2. **Scan** — codebase lane: read the target area (dimensions 1-3 above) looking specifically for things the user's framing didn't account for — existing patterns they'd duplicate, constraints they'd violate, historical decisions they'd re-litigate, adjacent code their change would break. Domain lane: build a lightweight vocabulary ladder grounded in sources fetched this session (repo files, official docs) — never bare training recall.
-3. **Output — blindspot cards.** One card per blindspot: the gap, why it matters here, and a copyable prompt-fix line. Close by assembling the fixes into ONE improved implementation prompt the user can run next.
-4. **Escalate when depth warranted** — a domain too deep for a lightweight ladder gets a recommendation to run proper external research (`/research`) or whatever structured-learning capability the environment provides.
-
-Blindspot mode does NOT write EXPLORE.md by default — its deliverable is the user's understanding plus the improved prompt. Offer the persist only when findings double as stage-1 exploration.
+> Surfacing the USER's unknown-unknowns before they work in unfamiliar territory — a better-prompt deliverable, not the `EXPLORE.md` artifact — is the sibling [`/discovery:blindspot`](${CLAUDE_PLUGIN_ROOT}/skills/blindspot/SKILL.md) skill.
 
 ## Output format
 
@@ -146,7 +136,7 @@ If invoked standalone, present findings directly. If invoked as part of a larger
 
 ## Outcome gate (before EXPLORE.md handoff)
 
-Blindspot-only runs SKIP this gate — their deliverable is blindspot cards plus an improved prompt, not the 7-section artifact (run it only when the user opts into the EXPLORE.md persist). For all other modes: before writing EXPLORE.md (or returning the summary), check the artifact against **binary criteria read off it** — not a "did I explore enough?" recap. Any FAIL → return to the named dimension and fix before handoff:
+Before writing EXPLORE.md (or returning the summary), check the artifact against **binary criteria read off it** — not a "did I explore enough?" recap. Any FAIL → return to the named dimension and fix before handoff:
 
 - **Every Output-format section populated with specifics** — each of the 7 sections carries concrete findings, not placeholders or "TBD".
 - **Every load-bearing area covered OR listed as a numbered gap** — nothing the task plausibly depends on is silently unexplored.
@@ -156,7 +146,7 @@ Blindspot-only runs SKIP this gate — their deliverable is blindspot cards plus
 
 ## Final step: persist artifact for handoff
 
-Blindspot-only runs SKIP this step (see "Blindspot mode"). For all other modes: write the exploration output to `<memory_dir>/<slug>/EXPLORE.md` — a memory-tier artifact, never committed. Destination, slug, and runtime guards resolve per the plugin's topic-docs binding ([`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md)).
+Write the exploration output to `<memory_dir>/<slug>/EXPLORE.md` — a memory-tier artifact, never committed. Destination, slug, and runtime guards resolve per the plugin's topic-docs binding ([`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md)).
 
 This file is the authoritative stage summary — a fresh session must be able to resume external research or planning reading only this artifact. The artifact's Findings section follows the 7-point Output format above, and a closing Next-stage-handoff names what external research (`/research`) or planning needs.
 
@@ -171,7 +161,7 @@ If exploration spans many sub-areas and EXPLORE.md exceeds ~2000 words, split ov
 
 ## What this skill does NOT do
 
-- **Does not research externally** — that's `/research`. This skill reads local code, git, and file system only. Sole carve-out: the blindspot domain lane may fetch official docs to ground its vocabulary ladder
+- **Does not research externally** — that's `/research`. This skill reads local code, git, and file system only
 - **Does not make changes** — it explores. Execution is a separate step
 - **Does not make decisions** — it presents what IS. The planning step decides what SHOULD BE
 - **Does not skip dimensions for "simple" tasks** — a quick bug fix still benefits from reading the surrounding code and checking for tests