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.
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)
- 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.
- 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.
- 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.
- 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.
- 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.
- 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: 471k | Updated | Claude CodeCodex | Verified | 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 |