axel-pm/watch-n-learn / examples/find-your-unknowns
find-your-unknowns
VerifiedBefore 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.2 KB |
| hooks/plan-mode-unknowns-nudge.shexecutable | script | 1.6 KB |
| references/prompt-patterns.md | markdown | 3.9 KB |
| settings-snippet.json | config | 747 B |
SKILL.md
View on GitHub---
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |