Find Your Unknowns

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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: axel-pm
• Source: axel-pm/watch-n-learn
• License: MIT

Install and usage instructions live in the source repository linked above.