Know Your Unknowns
The map is not the territory — the gap between them is your unknowns. Output quality
is now limited less by the model than by how well the prompt accounts for what the
prompter doesn't know. Specificity cuts both ways: too much detail and the model
rigidly follows instructions even when the territory says to change course; too little
and it fills gaps with industry defaults that don't fit. Either way, unaccounted
unknowns become rework. The cheapest place to find an unknown is before any code is
written; the most expensive is after someone else inherits it.
This skill is a menu of techniques for converting unknowns into decisions. Each
technique targets a specific quadrant of ignorance and ends by folding what it
surfaced back into a better prompt, plan, or sign-off.
The four quadrants
| Quadrant |
What it is |
How to surface it |
| Known knowns |
Already stated in the prompt |
Nothing to do |
| Known unknowns |
Questions you know you haven't answered |
Ask them, ordered by blast radius → the interview |
| Unknown knowns |
Preferences too obvious to write down, but recognized on sight |
Render options to react to → design directions, mocks, brainstorm |
| Unknown unknowns |
Things nobody thought to consider |
Scan the territory → blindspot pass, teach-me, reference map |
Reacting is easier than imagining: for unknown knowns, never ask the user to describe
what they want — show them concrete alternatives and let them point.
Choosing a technique
| Situation |
Technique |
Output form |
| Unfamiliar module/codebase, about to change it |
Blindspot pass |
Inline findings + improved prompt |
| Unfamiliar domain (no vocabulary to prompt with) |
Teach me my unknowns |
HTML explainer with vocabulary ladder |
| No visual direction, "no taste", greenfield UI |
Design directions |
HTML: 3–4 wildly different renderings |
| UI decisions pending, wiring not started |
Mock before you wire |
HTML clickable mock + A/B questions |
| Fuzzy problem, solution space unexplored |
Brainstorm the intervention |
Cost-sorted menu grounded in real code |
| Requirements ambiguous, architecture at stake |
The interview |
Inline Q&A → decisions table + prompt |
| A working reference implementation exists |
Point at a reference |
Semantics map + sign-off gate |
| Plan requested or implied before a build |
The tweakable plan |
Plan ordered by revision-likelihood |
| Mid-build, reality contradicts the plan |
Implementation notes |
Running markdown log of deviations |
| Shipped, needs reviewer/stakeholder approval |
The buy-in doc |
HTML pitch with pre-answered objections |
| Large diff about to merge |
Quiz me before I merge |
HTML report + gated quiz |
Details, prompt patterns, and required output elements:
- references/pre-implementation.md — first eight techniques (read before running any of them)
- references/during-and-post.md — implementation notes, buy-in doc, change quiz
Rules that apply to every technique
Ground everything in the territory. Findings, options, and questions must come
from scanning actual code, files, schemas, and history — cite real paths, functions,
and PRs. A blindspot card that says "auth can be tricky" is noise; one that says
"SessionBridge.write() also fires the audit webhook — skip it and SSO logins
silently vanish from compliance logs" changes the plan.
End with an exportable decision. The loop only closes when surfaced unknowns
become a better prompt. Interactive artifacts finish with reaction affordances
(steal/skip chips, "this resonates" checkboxes, A/B choices) that assemble into a
copyable reply. Conversational techniques finish with a decisions table and a
ready-to-paste implementation prompt that encodes every answer.
Match the medium to the technique. Techniques marked HTML above produce
self-contained artifacts — invoke the html-artifacts skill for format rules,
output paths (docs/.ai/artifacts/ durable, docs/.ai/tools/ throwaway), and the
quality checklist. Conversational techniques (blindspot pass, interview, brainstorm,
tweakable plan) stay inline as markdown unless their output outgrows it.
Implementation notes are a plain markdown file, not an artifact.
Don't interrogate a known territory. If the request is precise, the codebase is
familiar, and the change is mechanical, skip this skill entirely — running an
interview on a one-line fix is worse than the fix being slightly wrong. Scale the
ceremony to the blast radius of being wrong.
One technique at a time. These compose across a project's lifecycle (interview →
tweakable plan → implementation notes → buy-in doc), but pick the single technique
that targets the biggest current unknown rather than firing several at once.
1---2name: know-your-unknowns3description: Surface hidden unknowns before, during, and after implementation using structured techniques — clickable mocks, intervention brainstorms, semantics maps, tweakable plans, implementation notes, buy-in docs, and more. Use PROACTIVELY when entering an unfamiliar codebase or domain, when a feature request is ambiguous or underspecified, when the user says "I'm not sure", "I'll know it when I see it", or has no design direction, when porting from a reference implementation, when writing an implementation plan, before merging a large diff, or when packaging work for reviewer sign-off. Also triggers on explicit asks: "blindspot pass", "interview me", "quiz me before I merge", "show me design directions", "teach me <domain>", "what am I missing?".4---5
6# Know Your Unknowns
7
8The map is not the territory — the gap between them is your unknowns. Output quality
9is now limited less by the model than by how well the prompt accounts for what the
10prompter doesn't know. Specificity cuts both ways: too much detail and the model
11rigidly follows instructions even when the territory says to change course; too little
12and it fills gaps with industry defaults that don't fit. Either way, unaccounted
13unknowns become rework. The cheapest place to find an unknown is before any code is
14written; the most expensive is after someone else inherits it.
15
16This skill is a menu of techniques for converting unknowns into decisions. Each
17technique targets a specific quadrant of ignorance and ends by folding what it
18surfaced back into a better prompt, plan, or sign-off.
19
20## The four quadrants
21
22| Quadrant | What it is | How to surface it |
23| --- | --- | --- |
24| Known knowns | Already stated in the prompt | Nothing to do |
25| Known unknowns | Questions you know you haven't answered | Ask them, ordered by blast radius → **the interview** |
26| Unknown knowns | Preferences too obvious to write down, but recognized on sight | Render options to react to → **design directions, mocks, brainstorm** |
27| Unknown unknowns | Things nobody thought to consider | Scan the territory → **blindspot pass, teach-me, reference map** |
28
29Reacting is easier than imagining: for unknown knowns, never ask the user to describe
30what they want — show them concrete alternatives and let them point.
31
32## Choosing a technique
33
34| Situation | Technique | Output form |
35| --- | --- | --- |
36| Unfamiliar module/codebase, about to change it | Blindspot pass | Inline findings + improved prompt |
37| Unfamiliar *domain* (no vocabulary to prompt with) | Teach me my unknowns | HTML explainer with vocabulary ladder |
38| No visual direction, "no taste", greenfield UI | Design directions | HTML: 3–4 wildly different renderings |
39| UI decisions pending, wiring not started | Mock before you wire | HTML clickable mock + A/B questions |
40| Fuzzy problem, solution space unexplored | Brainstorm the intervention | Cost-sorted menu grounded in real code |
41| Requirements ambiguous, architecture at stake | The interview | Inline Q&A → decisions table + prompt |
42| A working reference implementation exists | Point at a reference | Semantics map + sign-off gate |
43| Plan requested or implied before a build | The tweakable plan | Plan ordered by revision-likelihood |
44| Mid-build, reality contradicts the plan | Implementation notes | Running markdown log of deviations |
45| Shipped, needs reviewer/stakeholder approval | The buy-in doc | HTML pitch with pre-answered objections |
46| Large diff about to merge | Quiz me before I merge | HTML report + gated quiz |
47
48Details, prompt patterns, and required output elements:
49
50- [references/pre-implementation.md](references/pre-implementation.md) — first eight techniques (read before running any of them)
51- [references/during-and-post.md](references/during-and-post.md) — implementation notes, buy-in doc, change quiz
52
53## Rules that apply to every technique
54
55**Ground everything in the territory.** Findings, options, and questions must come
56from scanning actual code, files, schemas, and history — cite real paths, functions,
57and PRs. A blindspot card that says "auth can be tricky" is noise; one that says
58"`SessionBridge.write()` also fires the audit webhook — skip it and SSO logins
59silently vanish from compliance logs" changes the plan.
60
61**End with an exportable decision.** The loop only closes when surfaced unknowns
62become a better prompt. Interactive artifacts finish with reaction affordances
63(steal/skip chips, "this resonates" checkboxes, A/B choices) that assemble into a
64copyable reply. Conversational techniques finish with a decisions table and a
65ready-to-paste implementation prompt that encodes every answer.
66
67**Match the medium to the technique.** Techniques marked HTML above produce
68self-contained artifacts — invoke the **html-artifacts skill** for format rules,
69output paths (`docs/.ai/artifacts/` durable, `docs/.ai/tools/` throwaway), and the
70quality checklist. Conversational techniques (blindspot pass, interview, brainstorm,
71tweakable plan) stay inline as markdown unless their output outgrows it.
72Implementation notes are a plain markdown file, not an artifact.
73
74**Don't interrogate a known territory.** If the request is precise, the codebase is
75familiar, and the change is mechanical, skip this skill entirely — running an
76interview on a one-line fix is worse than the fix being slightly wrong. Scale the
77ceremony to the blast radius of being wrong.
78
79**One technique at a time.** These compose across a project's lifecycle (interview →
80tweakable plan → implementation notes → buy-in doc), but pick the single technique
81that targets the biggest current unknown rather than firing several at once.
blacktop