find-your-unknowns git:20260712.eb4eb11A

Immutable. This exact content never changes and is served at /api/v1/blob/565511309a3d144a.

---
name: find-your-unknowns
description: >
  Before turning an agent loose on a coding task, surface the decisions you never specified —
  the gaps between your prompt (the "map") and the real codebase (the "territory"). Runs six
  prompt patterns (blind-spot pass, brainstorm/prototype, interview-me, reference-as-map,
  implementation-notes logging, quiz-me) to enumerate unknowns and shape the architecture up
  front. Use when the user says "help me scope this before I build it", "what am I missing",
  "find my blind spots", "interview me about this feature", "I don't know this codebase / this
  domain, help me prompt better", "de-risk this before the big run", or "surface the unknowns"
  — and BEFORE kicking off a large or architecture-shaping agent run on an under-specified task.
---

# find-your-unknowns

A more capable agent traverses more of the codebase, so it hits more decisions you never wrote
down — and drifts. The fix is to find those decisions *before* the big run. Your prompt is a
**map**; the codebase is the **territory**. This skill surfaces everywhere the territory holds
something your map doesn't.

## When to use vs. skip
- **Use** before a large, ambiguous, or architecture-shaping task, or when you (or the user) are
  new to this codebase or domain.
- **Skip** for a small, fully-specified change where the territory is already known — running the
  full battery would be ceremony.

## Inputs
- A **task/goal** (what the user wants built or changed).
- A **target repo or subsystem** you can read.
- Optionally: reference code/mockups, and context about the user's taste, stage, and constraints.

## Workflow

Don't blindly run all six. Pick by the *kind* of unknown in play (see table), run those, then
consolidate. Note the **When** column: only patterns 1–4 run during this scoping pass. Pattern 5
is an instruction you *produce now* but inject into the later build run; pattern 6 runs *after* the
build. Each pattern's full prompt template is in `references/prompt-patterns.md`.

| Kind of unknown | Pattern | When | Skip if |
|---|---|---|---|
| "I don't even know what I don't know here" | **1. Blind-spot pass** | scoping | rarely — this is the anchor |
| Aesthetic / "know it when I see it" | **2. Brainstorm & prototype** | scoping | the surface isn't primarily visual |
| Under-specified requirements | **3. Interview me** | scoping | requirements are already crisp |
| An example is easier than a spec | **4. Reference — give it another map** | scoping | you have no reference to point at |
| Deviations that only appear mid-build | **5. Implementation notes** | build-time | never — it's a cheap always-on trail |
| Do *I* actually understand the result? | **6. Quiz me** | post-build | you already own the result cold |

### The six patterns (in the order you'd typically reach for them)

1. **Blind-spot pass** — Read the target area and enumerate the *unknown unknowns*: the relevant
   things this task touches that the user hasn't mentioned. Output a list of blind spots + better
   prompting suggestions. Works for a new codebase *or* a new domain.
2. **Brainstorm & prototype** — For decisions the user can only judge by reacting: generate a few
   **wildly different** options (e.g. an HTML page with 3–4 distinct design directions) so they can
   point at one instead of specifying it.
3. **Interview me** — Have the agent interview the *user*, and explicitly
   **prioritize questions that would change the architecture**. Under-specified requirements become
   explicit before any code is written.
4. **Reference — give it another map** — Instead of writing a spec, point the agent at existing
   code (even in another language/system) or a mockup: "read this, understand it, use it as the
   starting point." An example often carries intent a spec can't.
5. **Implementation notes** — Inject an instruction into the *main* run: whenever the agent hits a
   decision not covered by the spec, **log the deviation and why** before proceeding. You get a
   visible trail of where the run left the map.
6. **Quiz me** — After the work, have the agent quiz the user on what actually happened, so they
   understand it well enough to own the PR/merge. Keeps the human in the loop.

### Consolidate
After running the chosen patterns, produce one artifact:
- **Unknowns** — the merged list of surfaced blind spots / open questions.
- **Architecture-shaping answers** — what the interview/references settled that affects structure.
- **A logging instruction** to paste into the main agent run (pattern 5), so mid-run deviations
  keep surfacing.

Then proceed to the real build with far fewer hidden decisions.

## Guardrails
- This is **discovery, not the build.** Don't start implementing during the unknown-finding pass —
  the point is to surface decisions, not make them silently.
- **Prefer context over constraints.** When you prompt the agent for these passes, give it context
  and let it reason; avoid piling on "do not do X" rules.
- Treat the model empirically — build intuition about where *this* codebase and *this* model surprise
  you, rather than assuming fixed rules.

## Reference
- `references/prompt-patterns.md` — the full, copy-pasteable prompt template for each of the six patterns.