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
- State the map. Restate the task, constraints, and what the user says they know.
- Inspect the territory. Read relevant files, docs, examples, data, screenshots, references, prior work, or user-provided context.
- Build an unknowns matrix. Separate known knowns, known unknowns, unknown knowns, and unknown unknowns.
- Choose the cheapest useful artifact. Pick the mode that exposes the highest-blast-radius unknown earliest.
- Gate implementation. Proceed only when dangerous unknowns are resolved, explicitly accepted, or isolated behind reversible decisions.
- 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:
- Scope read: What was inspected or assumed.
- Unknowns found: Labels by unknown type and severity.
- Blast radius: What changes if this unknown is answered differently.
- Conservative default: What the agent will do if forced to proceed.
- Decision needed: What the user must choose, if anything.
- Prompt upgrade: A revised prompt/instruction incorporating discoveries.
- 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.
1---2name: unknowns-discovery3description: Discover and reduce task unknowns — blindspots, missing context, and unknown unknowns — before committing to a plan, implementation, review, or merge.4---5
6# Unknowns Discovery
7
8Use 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.
9
10The 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**.
11
12## Unknown types
13
14| Type | Meaning | Agent move |
15|---|---|---|
16| Known knowns | Explicit facts and constraints in the prompt | Preserve and restate briefly |
17| Known unknowns | Questions already recognized as open | Ask, research, parameterize, or gate |
18| Unknown knowns | Tacit standards the user would recognize only after seeing them | Prototype, mock, compare, or interview |
19| 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 |
20
21## When to activate
22
23Activate this skill when any of these are true:
24
25- The work is multi-step, ambiguous, unfamiliar, high-risk, or likely to require judgment.
26- The user mentions “blindspot pass,” “unknown unknowns,” “what am I missing,” “interview me,” “prototype first,” “implementation notes,” “buy-in doc,” “quiz me,” or similar.
27- The user lacks domain vocabulary or does not know what good looks like.
28- The task involves codebase history, architecture, data model, permissions, migrations, UX, visual design, product scope, rollout, or reviewer approval.
29- The agent is about to start a long-horizon implementation or has already discovered that the plan and codebase disagree.
30
31Do **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.
32
33## Core loop
34
351. **State the map.** Restate the task, constraints, and what the user says they know.
362. **Inspect the territory.** Read relevant files, docs, examples, data, screenshots, references, prior work, or user-provided context.
373. **Build an unknowns matrix.** Separate known knowns, known unknowns, unknown knowns, and unknown unknowns.
384. **Choose the cheapest useful artifact.** Pick the mode that exposes the highest-blast-radius unknown earliest.
395. **Gate implementation.** Proceed only when dangerous unknowns are resolved, explicitly accepted, or isolated behind reversible decisions.
406. **Carry discoveries forward.** Fold the discoveries into a better prompt, plan, implementation note, buy-in doc, quiz, tests, or review artifact.
41
42## Artifact mode selector
43
44| Mode | Use when | Output |
45|---|---|---|
46| `blindspot-pass` | Unfamiliar codebase/domain/design area; likely unknown unknowns | Blindspot cards + better implementation prompt |
47| `teach-me-my-unknowns` | User lacks vocabulary or quality criteria | Mental model + vocabulary ladder + improved prompts |
48| `brainstorm-prototype` | User will know it when they see it | Divergent prototypes/options + reaction template |
49| `mock-before-wire` | Need to see UI/flow before backend/state/app changes | Throwaway mock with fake data + wiring plan |
50| `option-space-brainstorm` | Problem framing may be too narrow or too wide | Ranked interventions from cheapest to ambitious |
51| `one-question-interview` | Ambiguity remains after exploration | One question at a time, ordered by blast radius |
52| `reference-semantics-map` | Existing code/design/doc is the best description | Semantics map before porting/adapting |
53| `tweakable-plan` | Ready to implement but human should review change-prone parts | Plan sorted by likely human-tweak points before execution order |
54| `implementation-notes` | Implementation is underway and surprises appear | Running log of deviations and conservative choices |
55| `buy-in-doc` | Work needs approval or stakeholder alignment | Demo-first pitch/explainer with objections and signoffs |
56| `merge-readiness-quiz` | Human must understand a complex change before merge/release | Report + quiz with pass criteria |
57
58Detailed 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).
59
60## Default output contract
61
62Every unknowns artifact should include:
63
641. **Scope read:** What was inspected or assumed.
652. **Unknowns found:** Labels by unknown type and severity.
663. **Blast radius:** What changes if this unknown is answered differently.
674. **Conservative default:** What the agent will do if forced to proceed.
685. **Decision needed:** What the user must choose, if anything.
696. **Prompt upgrade:** A revised prompt/instruction incorporating discoveries.
707. **Stop conditions:** Cases where guessing is unacceptable.
71
72## Autonomy rules
73
74- Ask before acting when an unknown can change architecture, data model, auth, privacy, compliance, cost, public API, migration, rollout, or user-facing behavior.
75- Proceed conservatively when the unknown is low-risk, reversible, and the user has asked not to be interrupted. Label assumptions as `ASSUMED`.
76- Prototype before wiring when feedback depends on taste, layout, copy tone, interaction flow, information architecture, or data density.
77- Prefer source references over prose when behavior already exists elsewhere.
78- During implementation, log every material deviation before continuing.
79- Do not merge complex agent work on diff-skimming alone; create a report and quiz if understanding matters.
80
81## Stop immediately when
82
83- The territory contradicts the task goal.
84- The unknown could cause data loss, auth bypass, privacy leak, billing impact, destructive migration, public API break, or compliance failure.
85- A prior failed/reverted attempt appears and the reason still applies.
86- Exact legal/security/compliance behavior is requested but the authoritative source is absent.
87
88## Minimal examples
89
90```text
91Do a blindspot pass before implementation. Find unknown unknowns, explain why each matters, and rewrite my prompt with the discoveries folded in.
92```
93
94```text
95Before touching the app, make a single HTML mock with fake data so I can react to layout and product decisions.
96```
97
98```text
99Keep 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.
100```
101
102```text
103Give me a merge-readiness report with a quiz at the bottom. I should not merge until I pass it perfectly.
104```
105
106## Packaged resources
107
108- [references/ARTICLE_DIGEST.md](references/ARTICLE_DIGEST.md) — faithful extracted digest of the supplied article.
109- [references/WORKFLOWS.md](references/WORKFLOWS.md) — detailed procedure for each artifact mode.
110- [references/PROMPT_PATTERNS.md](references/PROMPT_PATTERNS.md) — reusable prompt cards.
111- [references/OUTPUT_SCHEMAS.md](references/OUTPUT_SCHEMAS.md) — artifact schemas and gates.
112- [references/EVALUATION.md](references/EVALUATION.md) — eval prompts and quality rubrics.
113- [references/SOURCE_INDEX.md](references/SOURCE_INDEX.md) — source and format references.
114- [assets/templates/](assets/templates/) — reusable Markdown templates.
115- [examples/](examples/) — example applications across coding, product/design, and research.
116- [scripts/](scripts/) — optional helper scripts for template generation and validation.
majiayu000