finding-unknowns

The map is not the territory.

An agent skill 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) 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:

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), original thread. This repo is an independent distillation into skill form; all example prompts are adapted from the thread.
• Skill structure follows Anthropic's skill-creator conventions.

License

MIT