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. Copyable prompt cards are in references/PROMPT_PATTERNS.md. Output schemas are in 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, public API break, or compliance failure.
• A prior failed/reverted attempt appears and the reason still applies.
• Exact legal/security/compliance behavior is requested but the authoritative source is absent.

Minimal examples

Do a blindspot pass before implementation. Find unknown unknowns, explain why each matters, and rewrite my prompt with the discoveries folded in.

Before touching the app, make a single HTML mock with fake data so I can react to layout and product decisions.

Keep implementation-notes.md as you build. If code forces a plan deviation, choose the conservative option, log it under Deviations, and continue unless it affects security/data/migrations/API/compliance.

Give me a merge-readiness report with a quiz at the bottom. I should not merge until I pass it perfectly.

Packaged resources

• references/ARTICLE_DIGEST.md — faithful extracted digest of the supplied article.
• references/WORKFLOWS.md — detailed procedure for each artifact mode.
• references/PROMPT_PATTERNS.md — reusable prompt cards.
• references/OUTPUT_SCHEMAS.md — artifact schemas and gates.
• references/EVALUATION.md — eval prompts and quality rubrics.
• references/SOURCE_INDEX.md — source and format references.
• assets/templates/ — reusable Markdown templates.
• examples/ — example applications across coding, product/design, and research.
• scripts/ — optional helper scripts for template generation and validation.