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

[kyle-sexton]

Summary

Blindspot mode was a grafted second responsibility on /discovery:explore: it builds the USER's knowledge (not the agent's) and ships a different deliverable — blindspot cards plus one improved prompt, with no EXPLORE.md, the outcome gate skipped, and a bespoke external-research carve-out. This PR extracts it into its own skill and trims explore back to its single core responsibility.

Fix

• New skill plugins/discovery/skills/blindspot/ — SKILL.md (own frontmatter, intake → scan → cards → escalate workflow, output-format + gotchas + "does NOT do") and evals/evals.json (3 graders, including the blindspot-builds-user-knowledge case moved out of explore's evals).
• explore/SKILL.md trimmed — removed the blindspot modes-table row and the "Blindspot mode" section, the two artifact-skip clauses in the outcome gate and final step, the blindspot mention in the frontmatter description/argument-hint, and the domain-lane research carve-out. A one-line pointer to /discovery:blindspot replaces the extracted section.
• explore/evals/evals.json — dropped the blindspot eval, renumbered, and removed the stale blindspot carve-out reference in the no-external-research grader.
• Cross-plugin references repointed — plugins/discovery/README.md (new skill row + framing) and plugins/planning/skills/interview/SKILL.md (/discovery:explore blindspot <area> → /discovery:blindspot <area>).
• Version + changelog — discovery 0.7.3 → 0.8.0 with a top-inserted CHANGELOG entry.

Verification

All run against origin/main in the worktree:

• scripts/check-changed-skills.sh origin/main → PASS (explore, interview; 0 errors)
• check-skill.sh blindspot (skill-quality gate) → PASS — 0 errors, 1 warning (Use-when phrasing, consistent with sibling discovery skills)
• scripts/check-changelog-parity.sh --check and --check-bump origin/main → PASS
• scripts/check-skill-leaf-names.sh --check → PASS (blindspot is a unique leaf, no registry entry needed)
• scripts/check-skill-portability.sh --paths …blindspot/SKILL.md …explore/SKILL.md → PASS (no coupling tokens)
• node scripts/validate-plugin-contracts.mjs → PASS (33 setup skills, 1825 files)
• markdownlint-cli2 on all changed markdown → 0 errors
• Evals JSON parse + schema-shape check (top required + additionalProperties) → valid

Closes #259

Related

• Extracted from /discovery:explore; sibling to explore-deep, research, research-deep, setup.

[claude]

Claude finished @kyle-sexton's task in 3m 59s —— View job

---

PR Review: refactor(discovery): extract blindspot mode into its own skill

• Gather context and understand the request
• Read changed files
• Review new blindspot/SKILL.md
• Review new blindspot/evals/evals.json
• Review trimmed explore/SKILL.md
• Review trimmed explore/evals/evals.json
• Review cross-plugin reference updates (README, interview SKILL.md)
• Review version bump and CHANGELOG
• Synthesize and post findings

---

Overall

Clean, well-motivated extraction. The separation of audience (user vs agent) and deliverable (prompt-coaching cards vs EXPLORE.md) is a correct design boundary, and the implementation is consistent with codebase conventions. Verification matrix in the PR description is thorough.

---

What's working well

blindspot/SKILL.md structure — The 4-step workflow (Intake → Scan → Cards → Escalate) is well-specified, and the "Gotchas" and "What this skill does NOT do" sections correctly guard against the most likely failure modes (presenting training recall as domain fact, surfacing agent gaps instead of user gaps, writing artifacts by reflex). The distinction between codebase lane and domain lane is clear.

Evals coverage — The three evals are well-targeted: the happy path (id:1, ported from explore), the domain lane grounding (id:2, new), and the explore handoff boundary (id:3, new). The third eval is a genuine addition that explore's evals never tested — good catch.

explore SKILL.md cleanup is surgical — The four removal sites are precisely correct: modes-table row, the "Blindspot mode" section, the two SKIP clauses in the outcome gate / final step, and the external-research carve-out in "What this skill does NOT do". No collateral damage to explore's own logic.

Evals renumbering — The old id:2 (blindspot eval) is removed, stale carve-out language in no-external-research's expected_output is cleaned, and ids renumber 1–5 without gaps.

---

Issues

1. README "Both inline skills" phrase is now ambiguous [minor]

After adding blindspot as a fifth entry, the sentence below the table — "Both inline skills persist handoff artifacts (EXPLORE.md / RESEARCH.md) so a fresh session can resume planning from the artifact alone." — is jarring. It was unambiguous when there were exactly two skills; with five entries the reader has to cross-reference the "Axis" column to see which two "inline" means. The logic is still correct, but the phrasing doesn't adapt to the expanded table.

plugins/discovery/README.md line 18

Suggested fix:

- `The `/discovery:explore` and `/discovery:research` skills persist handoff artifacts...`
+ The two artifact-persisting skills (`/discovery:explore`, `/discovery:research`) persist handoff artifacts...

Fix this →

---

2. plugin.json description doesn't reflect the new skill [cosmetic]

The description still reads "explore the local codebase (inline or in an isolated forked subagent) and run disciplined multi-source external research…" — no mention of user-facing blindspot discovery. The README framing was correctly updated to call out blindspot as a fifth, distinct-audience skill; the manifest description is now slightly misaligned.

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

Not a blocker, but a future pass could append something like: "…and surface user unknown-unknowns before working in unfamiliar territory (/discovery:blindspot)."

---

3. Cross-skill coupling in blindspot/SKILL.md [informational]

The codebase lane description references ${CLAUDE_PLUGIN_ROOT}/skills/explore/SKILL.md as the source for its methodology. Both are in the same plugin so they're always co-installed — no runtime risk. But the reference is structural: if explore's dimension headings were ever relocated to a shared reference doc (like ecosystem-discovery.md), line 37 would become stale.

plugins/discovery/skills/blindspot/SKILL.md line 37

Worth a comment in explore/SKILL.md's dimensions header if the dimensions structure is ever refactored — no action needed now.

---

4. Domain-lane eval doesn't explicitly check the intake question [nit]

The domain-lane-grounds-in-sources-not-recall eval (blindspot evals id:2) focuses correctly on grounding vs recall, but its expectations array doesn't include "The run asks one intake question about the user's starting point before scanning." That invariant is covered by id:1, so it's not a gap — just noting the eval is intentionally narrowly focused.

---

Verdict

Approve with suggestion. Item 1 (README "Both inline skills") is worth fixing before merge — it's a one-line clarification that's easy to miss on a close read but will confuse plugin consumers reading the skills table. Items 2–4 are informational. The extraction itself is correct and the implementation is clean.

[claude]

Claude finished @kyle-sexton's task in 37s —— View job

---

• Gather context and understand the request
• Read changed files
• Verify fix for finding chore: initialize marketplace scaffold #1 (README ambiguity)
• Post updated review

---

Re-review: c950337 addresses the only non-informational finding

The follow-up commit fixes the single item flagged as "worth fixing before merge."

Finding #1 — resolved. The ambiguous "Both inline skills" phrase (previously flagged) is now:

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.

This is exactly the suggested fix. The sentence now names the skills explicitly, removing any ambiguity introduced by the five-row table. ✓

Findings #2–#4 were informational (cosmetic description gap in plugin.json, a structural coupling note, a narrowly-focused eval nit) — none required action for this PR, and none are changed here, which is the right call.

---

Verdict

Approved. The extraction is correct, the cleanup is surgical, the evals are well-targeted, and the one pre-merge blocker is resolved. Good to merge.

[kyle-sexton]

Post-green review pass complete (rule 8). Bot review classification:

Finding	Verdict	Action
README "Both inline skills" ambiguous with 5th table entry	VALID, worth fixing before merge	Fixed — skills named explicitly
plugin.json description doesn't mention blindspot	Informational, non-blocking	Not fixed
Cross-skill path coupling to explore's dimensions header	Informational, non-blocking	Not fixed
Domain-lane eval narrowly focused (not a gap)	Informational, non-blocking	Not fixed

No threads to resolve, CI fully green (18/18).

Flipping to ready for review; handing off to the babysit lane for merge.

[claude]

Claude finished @kyle-sexton's task in 1m 15s —— View job

---

• Gather context and understand the request
• Read changed files for final review pass
• Verify finding chore: initialize marketplace scaffold #1 fix (README ambiguity) is correctly applied
• Check for any new issues in the current state
• Post final merge-readiness verdict

---

Final review pass — ready to merge

This is a re-review pass after the PR was marked ready for review following the post-green classification. All 8 changed files are verified.

Finding #1 fix confirmed. README.md line 17 now reads:

The two artifact-persisting skills (/discovery:explore, /discovery:research) persist handoff artifacts…

Exact match to the suggested fix. The five-row table is no longer ambiguous. ✓

blindspot/SKILL.md — Structure is clean and correct: proper frontmatter, clear 4-step workflow (Intake → Scan → Cards → Escalate), output format, gotchas, and "does NOT do" section. The intra-plugin reference at line 37 (${CLAUDE_PLUGIN_ROOT}/skills/explore/SKILL.md) follows the same pattern used across other sibling skills. The pointer in explore/SKILL.md at line 121 mirrors it correctly in the other direction. ✓

blindspot/evals/evals.json — Three evals are well-targeted and complete: happy path (id:1, ported), domain-lane grounding (id:2, new), explore-handoff boundary (id:3, new). ✓

explore/SKILL.md — Cleanly trimmed. Four removal sites are precise. The modes table, "Blindspot mode" section, two SKIP clauses in the outcome gate and final step, and the domain-lane carve-out are all gone. ✓

explore/evals/evals.json — Blindspot eval removed, ids renumber 1–5 without gaps, stale carve-out language removed from no-external-research expected output. ✓

interview/SKILL.md — Cross-plugin reference correctly updated from /discovery:explore blindspot <area> → /discovery:blindspot <area> at line 70. ✓

plugin.json / CHANGELOG.md — Version bumped to 0.8.0, changelog entry is accurate and complete. The plugin.json description still doesn't mention blindspot (finding #2 from prior review, informational, correctly left unfixed). ✓

Verdict

Approved. No new issues. The single pre-merge item from the prior review is resolved, the informational findings are correctly not acted on, and CI is green. Ready to merge.