unknowns:pre — resolve unknowns before implementation

The map (your prompt and context) is not the territory (the codebase and reality). The gap between them is unknowns, and work quality is bottlenecked by how well they get clarified — the user's unknowns AND yours. This skill finds them while they are cheap to fix.

Quadrants: KK known knowns (already stated) · KU known unknowns (identified, unresolved) · UK unknown knowns (know-it-when-I-see-it) · UU unknown unknowns (not even on the radar).

Technique → transition: context surfaces raw KUs and routes each to who can answer it · blindspot converts UU→KU · interview resolves KU · prototype resolves UK · reference resolves hard-to-verbalize wants · plan turns residual open unknowns into improvise points.

Artifact directory (state)

All state lives in the CURRENT PROJECT at docs/unknowns-resolver/<task-slug>/ (slug = kebab-case task title).

• Directory missing → create it, write ledger.md from the template below.
• Directory exists → RESUME: read every file in it, re-assess open items, append. Never overwrite existing artifacts, never renumber.
• After EVERY technique: update ledger.md, then regenerate index.html per references/design-system.md.
• Numbered artifacts: 00-context.md + 00-context.html, 01-map.md, 02-blindspot.md, 03-interview.md, 04-prototype/, 05-reference.md, 06-plan.md + 06-plan.html, 07-preview.md + .html, 08-notes.md, 09-pitch.md + .html, 10-quiz.md + .html. Skipped technique = absent file; numbers never shift.

ledger.md template

# Unknowns Ledger: <task title>

Route: <proposed route, e.g. pre(blindspot → interview → plan)> · Status: in-progress

| # | Unknown | Quadrant | Found in | Status | Resolution | Evidence |
|---|---------|----------|----------|--------|------------|----------|

## Deviations → 08-notes.md

## Quiz → 10-quiz.md (score: —)

Quadrant column records transitions (UU→KU). Statuses: open / resolved / deferred. Every row keeps a stable ID (#) — plan sections and evidence links cite these IDs.

Workflow

Step 1 — Context brief (review gate, zero questions first)

READ references/context.md and follow it exactly. Before asking the user ANYTHING: gather the task statement + a codebase scan, write a task-comprehension brief (goal, actors, current→desired, scope, constraints, affected-area diagram, success criteria — no code) plus the raw list of open questions the rest of pre would ask, each tagged with its owner (DEV / PO / PM / DESIGN) and impact (blocker / nice-to-know). Write 00-context.md + 00-context.html, open the HTML, and gate: the user reviews it — corrects misunderstandings, takes PO/PM-owned questions away to get real answers, or approves. Do NOT proceed to Step 2 until the brief is approved. Questions the developer cannot decide are never asked in the Step 4 interview; they resolve via pasted PO/PM answers, get deferred, or become improvise points.

Step 2 — Starting-point interview

Ask ONE question at a time (use AskUserQuestion), maximum 4, each with your recommended answer:

1. Where are you in your thought process? (just an idea / explored a bit / know exactly what I want)
2. How familiar are you with the relevant part of this codebase? (never touched it / have read it / wrote it)
3. How familiar are you with the problem domain itself? (new to me / working knowledge / expert)
4. What does "done" look like for this task? (open answer)

Write answers to 01-map.md.

Step 3 — Quadrant heat assessment

Score UU / KU / UK as HIGH, MED, or LOW — one-line justification each, grounded in the context brief and Step 2 answers plus a quick look at the relevant code area. Also decide: does the desired behavior already exist somewhere (a library, another repo, a site the user likes)? If yes, flag a reference candidate. Record scores in 01-map.md; the 00-context questions are already in the ledger — seed any additional already-identified unknowns.

Step 4 — Route proposal (one confirmation, then run)

Present the route AND every skipped technique with the reason it is skipped. If all quadrants are LOW, say the task looks trivial and offer: plan-only, or stop here. Ask for ONE confirmation, then run the whole route without further gating.

Step 5 — Run the route

For each technique in order, READ its playbook file and follow it exactly:

• context → references/context.md → writes 00-context.md + 00-context.html (already done in Step 1; revisit only when new PO/PM answers arrive)
• blindspot → references/blindspot.md → writes 02-blindspot.md
• interview → references/interview.md → writes 03-interview.md
• prototype → references/prototype.md → writes 04-prototype/
• reference → references/reference.md → writes 05-reference.md
• plan → references/plan.md → writes 06-plan.md + 06-plan.html

After each technique: update the ledger, regenerate index.html, and tell the user in one line what just resolved and which technique is next in the route.

Step 6 — Exit handoff (MANDATORY)

Print exactly this block at the end:

Unknowns resolved: {resolved}/{total} ({open} open → improvise points, {deferred} deferred). Ledger: docs/unknowns-resolver/<slug>/ledger.md · Dashboard: docs/unknowns-resolver/<slug>/index.html

Next phase: open a FRESH session in this repo and paste: /unknowns:impl docs/unknowns-resolver/<slug>/

Escape hatch

/unknowns:pre --only <technique> <task> → skip Steps 1–4, run just that playbook. Create the directory + minimal ledger first if missing.

Rules

• One question at a time, always with a recommended answer.
• Never ask the developer to decide a PO/PM/DESIGN-owned question — hand it over verbatim (context brief), then resolve via their answer, defer, or improvise point.
• If a question can be answered by exploring the codebase, explore instead of asking.
• Never run a technique outside the confirmed route without telling the user.
• No subagents — everything inline.
• Artifacts in English, self-explanatory for a fresh session with zero chat context.