A single-skill Claude Code plugin that surfaces unknowns before, during, and after implementation — so a strong model doesn't confidently execute the wrong thing.
A capable model's failures are quiet and compounding: it takes the prompt at
face value and executes thoroughly, which is exactly what makes an unstated
assumption expensive. Output quality is bottlenecked by the gap between the
map (prompt, skills, CLAUDE.md) and the territory (the real codebase
and constraints). This plugin spends cheap effort up front to close that gap
before it turns into rework.
Every task is classified across four quadrants:
- Known knowns — stated in the prompt. Already actionable.
- Known unknowns — the user knows they haven't decided. Ask or plan.
- Unknown knowns — obvious-once-seen, never written down. Surface with prototypes/brainstorms.
- Unknown unknowns — not considered at all. Surface with a blindspot pass.
Only quadrant 1 makes it into prompts by default. Quadrants 2–4 are where rework comes from.
From a local checkout, add the directory as a plugin marketplace and install:
/plugin marketplace add /path/to/cc-unknowns-plugin
/plugin install cc-unknowns@cc-unknowns-plugin
Or straight from GitHub:
/plugin marketplace add betmoar/cc-unknowns-plugin
/plugin install cc-unknowns@cc-unknowns-plugin
Both commands above target this repo's own marketplace. Once the central
ccp-market marketplace is published, cc-unknowns will also be
installable from there — the plugin name (cc-unknowns) is identical, only
the @<marketplace> suffix changes.
The plugin ships one skill, surfacing-unknowns, which Claude activates
automatically on matching tasks. You can also invoke it explicitly:
/cc-unknowns:surfacing-unknowns
Automatically on non-trivial coding, design, refactor, or build tasks — especially when the request is ambiguous, long-horizon, touches unfamiliar territory, or a previous attempt came back wrong. Trigger phrases include "help me plan", "blindspot pass", "unknown unknowns", "brainstorm", "interview me", "implementation plan", "port X to", "tell me when it's done".
It stays out of the way for small, fully-specified edits, single-file mechanical changes, or when you say "just do it".
The skill routes to one technique per lifecycle stage. Each has a reference
recipe in skills/surfacing-unknowns/references/
with a strict output contract.
| Technique | Targets | Use when |
|---|---|---|
| Blindspot pass | unknown unknowns | Working in an unfamiliar part of the codebase; fearing landmines. |
| Brainstorm & multi-direction prototype | unknown knowns | Taste-/visually-driven work; scope undefined. Produces 4 divergent directions on one page. |
| The interview | known & unknown unknowns | Ambiguity remains and some answers would change the architecture. One question at a time, ranked by blast radius. |
| Reference (source-code-first) | unknown knowns | A working implementation of the desired behavior exists elsewhere. Produces a semantics map, gated on your sign-off before any port code. |
| Decision-first implementation plan | — | Direction is clear; you want to approve the judgment calls, not the refactoring. |
| Technique | Use when |
|---|---|
| implementation-notes.md with Deviations | Long build where discoveries and conservative departures accumulate. The notes file is the first file mutation of the session and survives it. |
| Technique | Use when |
|---|---|
| Pitch / explainer doc | You need understanding or approvals from other people. Demo-first. |
| Pre-merge comprehension quiz | About to merge; must confirm you understand the change. |
| Self-verification audit | About to claim work is complete/fixed/passing. Claims-vs-evidence table; anything unevidenced is marked Unverified and blocks completion. |
The skill runs an observe-before-re-routing loop:
- Orient — restate the task; ask the user's starting point and expertise.
- Classify across the four quadrants.
- Select the lifecycle stage (pre / during / post).
- Route to a technique and deliver its output contract in the same response.
- Dispatch heavy exploration (blindspot passes, reference reads) to a subagent to keep the main thread clean.
- Observe — after every artifact, a three-line
Thought / Action / Observationtrace records which unknowns moved from unknown → known and decides the next move. No two techniques chain without an Observation between them. - Reframe check — if a surfaced unknown invalidates the task's framing, stop and propose the reframe before continuing.
Techniques that benefit from layout, color, or side-by-side comparison emit
self-contained HTML. scripts/html_artifact.py
wraps body content in the shared template at
assets/artifact-template.html:
python3 scripts/html_artifact.py --title "Plan: export feature" body.html out.html
No dependencies beyond Python 3. Before a PR:
python3 scripts/validate_plugin.py # lints the plugin's internal contracts
python3 -m unittest discover -s tests
CI runs both. See CONTRIBUTING.md and the maintainer handoff in CLAUDE.md.
This skill encodes a public working methodology for surfacing unknowns. It does not replicate any model's internals and never claims to.
MIT — see LICENSE.