/unknowns-discovery

name: unknowns-discovery
description: Discover and reduce task unknowns — blindspots, missing context, and unknown unknowns — before committing to a plan, implementation, review, or merge.

Unknowns Discovery

Use this skill when an agent should **discover what the user, spec, prompt, or codebase is missing** before it commits to a plan, implementation, review, or merge.

The prompt, skill, ticket, screenshot, and context window are the **map**. The real codebase, product, users, data, constraints, history, and reviewer expectations are the **territory**. The gap between them is the task's **unknowns**.

Unknown types

| Type | Meaning | Agent move | |---|---|---| | Known knowns | Explicit facts and constraints in the prompt | Preserve and restate briefly | | Known unknowns | Questions already recognized as open | Ask, research, parameterize, or gate | | Unknown knowns | Tacit standards the user would recognize only after seeing them | Prototype, mock, compare, or interview | | Unknown unknowns | Hidden constraints, missing vocabulary, prior art, traps, or quality ceilings nobody mentioned | Run blindspot passes, inspect references, search code/history, and surface landmines |

When to activate

Activate this skill when any of these are true:

• The work is multi-step, ambiguous, unfamiliar, high-risk, or likely to require judgment.
• The user mentions “blindspot pass,” “unknown unknowns,” “what am I missing,” “interview me,” “prototype first,” “implementation notes,” “buy-in doc,” “quiz me,” or similar.
• The user lacks domain vocabulary or does not know what good looks like.
• The task involves codebase history, architecture, data model, permissions, migrations, UX, visual design, product scope, rollout, or reviewer approval.
• The agent is about to start a long-horizon implementation or has already discovered that the plan and codebase disagree.

Do **not** activate for tiny deterministic tasks where exploration would add friction, such as fixing a typo, renaming a variable, or answering a direct question with no meaningful unknowns.

Core loop

1. **State the map.** Restate the task, constraints, and what the user says they know. 2. **Inspect the territory.** Read relevant files, docs, examples, data, screenshots, references, prior work, or user-provided context. 3. **Build an unknowns matrix.** Separate known knowns, known unknowns, unknown knowns, and unknown unknowns. 4. **Choose the cheapest useful artifact.** Pick the mode that exposes the highest-blast-radius unknown earliest. 5. **Gate implementation.** Proceed only when dangerous unknowns are resolved, explicitly accepted, or isolated behind reversible decisions. 6. **Carry discoveries forward.** Fold the discoveries into a better prompt, plan, implementation note, buy-in doc, quiz, tests, or review artifact.

Artifact mode selector

| Mode | Use when | Output | |---|---|---| | `blindspot-pass` | Unfamiliar codebase/domain/design area; likely unknown unknowns | Blindspot cards + better implementation prompt | | `teach-me-my-unknowns` | User lacks vocabulary or quality criteria | Mental model + vocabulary ladder + improved prompts | | `brainstorm-prototype` | User will know it when they see it | Divergent prototypes/options + reaction template | | `mock-before-wire` | Need to see UI/flow before backend/state/app changes | Throwaway mock with fake data + wiring plan | | `option-space-brainstorm` | Problem framing may be too narrow or too wide | Ranked interventions from cheapest to ambitious | | `one-question-interview` | Ambiguity remains after exploration | One question at a time, ordered by blast radius | | `reference-semantics-map` | Existing code/design/doc is the best description | Semantics map before porting/adapting | | `tweakable-plan` | Ready to implement but human should review change-prone parts | Plan sorted by likely human-tweak points before execution order | | `implementation-notes` | Implementation is underway and surprises appear | Running log of deviations and conservative choices | | `buy-in-doc` | Work needs approval or stakeholder alignment | Demo-first pitch/explainer with objections and signoffs | | `merge-readiness-quiz` | Human must understand a complex change before merge/release | Report + quiz with pass criteria |

Detailed procedures are in [references/WORKFLOWS.md](references/WORKFLOWS.md). Copyable prompt cards are in [references/PROMPT_PATTERNS.md](references/PROMPT_PATTERNS.md). Output schemas are in [references/OUTPUT_SCHEMAS.md](references/OUTPUT_SCHEMAS.md).

Default output contract

Every unknowns artifact should include:

1. **Scope read:** What was inspected or assumed. 2. **Unknowns found:** Labels by unknown type and severity. 3. **Blast radius:** What changes if this unknown is answered differently. 4. **Conservative default:** What the agent will do if forced to proceed. 5. **Decision needed:** What the user must choose, if anything. 6. **Prompt upgrade:** A revised prompt/instruction incorporating discoveries. 7. **Stop conditions:** Cases where guessing is unacceptable.

Autonomy rules

• Ask before acting when an unknown can change architecture, data model, auth, privacy, compliance, cost, public API, migration, rollout, or user-facing behavior.
• Proceed conservatively when the unknown is low-risk, reversible, and the user has asked not to be interrupted. Label assumptions as `ASSUMED`.
• Prototype before wiring when feedback depends on taste, layout, copy tone, interaction flow, information architecture, or data density.
• Prefer source references over prose when behavior already exists elsewhere.
• During implementation, log every material deviation before continuing.
• Do not merge complex agent work on diff-skimming alone; create a report and quiz if understanding matters.

Stop immediately when

• The territory contradicts the task goal.
• The unknown could cause data loss, auth bypass, privacy leak, billing impact, destructive migration, publi