# finding-unknowns
> The map is not the territory.
An [agent skill](https://code.claude.com/docs/en/skills) that turns a working philosophy into a reusable process: **the quality of long-horizon agent work is bottlenecked by unresolved unknowns, not by model capability** — so find your unknowns deliberately, before, during, and after implementation, instead of discovering them as rework.
Distilled from [a thread by Thariq (@trq212)](https://x.com/trq212/status/2073100352921215386) of Anthropic on working with Claude.
## The idea
Your prompt is a **map** — a compressed representation of the work. The codebase and the real world are the **territory**. The gap between them is made of **unknowns**, and every unknown the agent hits mid-task forces it to guess what you want. This skill sorts those unknowns into four kinds and routes to a cheap probe for each:
| | You know it | You don't know it |
|---|---|---|
| **Aware** | **Known knowns** — what's in your prompt | **Known unknowns** — gaps you can name |
| **Unaware** | **Unknown knowns** — tacit taste; "not what I meant" | **Unknown unknowns** — what you haven't considered at all |
## The eight techniques
| Phase | Technique | What it's for |
|---|---|---|
| Before | **Blindspot pass** | New domain or unfamiliar codebase area — learn what questions to ask |
| Before | **Brainstorm & prototype** | "I'll know it when I see it" — react to divergent variants instead of specifying |
| Before | **Interview** | Close named gaps, one question at a time, architecture-changing questions first |
| Before | **Reference code** | Point at an implementation instead of describing it — source code beats screenshots |
| Before | **Implementation plan** | Lead with the decisions you're most likely to veto; bury the mechanical parts |
| During | **Implementation notes** | Hit an unplanned edge case → conservative option, logged deviation, keep going |
| After | **Pitch & explainer** | Walk reviewers across the same gap you crossed — demo first, diligence below |
| After | **Quiz** | Merge only after you can pass a quiz on what actually changed |
The skill triggers on the *signals* of unknowns ("I don't know this codebase", "no visual taste", vague quality adjectives, long-horizon asks) — not just the literal words. It's also explicitly calibrated to **do nothing** on simple, well-specified tasks: most tasks need zero or one technique, not a ceremony.
## Install
**Claude Code (plugin marketplace — recommended):**
```
/plugin marketplace add oso95/finding-unknowns
/plugin install finding-unknowns@finding-unknowns
```
The first command registers this repo as a marketplace; the second installs the skill. Pull later updates with `/plugin marketplace update finding-unknowns`.
**Manual install** (Claude Code without plugins): the skill is plain markdown under `skills/finding-unknowns/`. Copy that one directory into your skills folder:
```bash
git clone https://github.com/oso95/finding-unknowns /tmp/finding-unknowns
cp -r /tmp/finding-unknowns/skills/finding-unknowns ~/.claude/skills/ # all projects
# or: cp -r /tmp/finding-unknowns/skills/finding-unknowns .claude/skills/ # single project
```
**claude.ai / Claude Desktop**: zip the `skills/finding-unknowns/` directory and upload it as a skill in Settings → Capabilities.
**Other agents** (Codex, Cursor, etc.): plain markdown, no Claude-specific dependencies. Point your agent at `skills/finding-unknowns/SKILL.md` — e.g. add a line to `AGENTS.md`: *"When a task is ambiguous, high-stakes, or in territory I don't know, follow `skills/finding-unknowns/SKILL.md`."*
## Use
Let it trigger on its own, or invoke techniques by name:
- *"Do a **blindspot pass** — I'm touching the auth module for the first time and I don't know what I don't know."*
- *"Make me 4 wildly different design directions as one HTML page so I can react to them."*
- *"**Interview me** one question at a time; prioritize questions where my answer would change the architecture."*
- *"This crate in `vendor/rate-limiter` has the exact backoff behavior I want — read it and port the semantics."*
- *"Write the plan, but lead with what I'm most likely to tweak. Bury the mechanical refactoring."*
- *"Keep an `implementation-notes.md`; log deviations, pick the conservative option, keep going."*
- *"Package this into one doc I can drop in Slack. Lead with the demo."*
- *"**Quiz me** on this change — I only merge after I pass."*
## Structure
```
finding-unknowns/
├── .claude-plugin/
│ ├── marketplace.json # registers the repo as an installable marketplace
│ └── plugin.json # the plugin manifest
└── skills/
└── finding-unknowns/
├── SKILL.md # framework + routing table (loads when the skill triggers)
└── references/ # one playbook per technique (loaded only when routed to)
├── blindspot-pass.md
├── brainstorm-prototype.md
├── interview.md
├── reference-code.md
├── implementation-plan.md
├── implementation-notes.md
├── pitch-explainer.md
└── quiz.md
```
## Evaluation
Five scenarios (one per technique cluster) were run **with and without the skill**, on **two models** (Fable 5 and Sonnet 5), each output graded **blind and cross-model** — Fable's work judged by Sonnet and vice-versa — against a fixed 4-point rubric.
**Rubric pass rate: 65% baseline → 100% with the skill, and it never lowered a score.** (`base → skill`, per model)
| Scenario | Technique | Fable | Sonnet |
|---|---|:---:|:---:|
| Dashboard, "no visual taste" | brainstorm & prototype | 0→4 | 1→4 |
| Color-grade a washed-out demo | blindspot pass | 4→4 | 4→4 |
| Google login in unfamiliar auth | blindspot + interview | 4→4 | 4→4 |
| Rate-limit an API, user AFK | plan + notes | 1→4 | 4→4 |
| Understand a teammate's refactor | quiz | 2→4 | 2→4 |
The lift comes from the artifact-producing techniques models skip on their own — divergent prototypes to react to, a decisions log for an absent user, quizzing the user on a diff. The `4→4` rows are honest nulls: on familiar patterns the models already did the right thing unprompted. Small pilot (n=1 per cell), scoring process over polish.
## Credits
- Framework and techniques: [Thariq (@trq212)](https://x.com/trq212), [original thread](https://x.com/trq212/status/2073100352921215386). This repo is an independent distillation into skill form; all example prompts are adapted from the thread.
- Skill structure follows Anthropic's [skill-creator](https://github.com/anthropics/skills) conventions.
## License
[MIT](LICENSE)