Finding Unknowns

# Agent interface design

Examples teach one path and quietly fence off the others: shown three ways to call a tool, a model tends to produce those three. A well-designed interface teaches the whole space at once. The parameters say what is possible, the description says what is expected, and there is very little left to write.

## Steps

1. Find out how the tool is actually being misused before redesigning it. Read transcripts, logs, or the user's complaint. Misuse is an interface symptom first and a documentation symptom second, and the fix is usually a rename or a type, not a paragraph.
2. Push meaning into the parameters:
   - Enumerate instead of accepting free text. A status of `pending | in_progress | completed` teaches the whole state machine without a sentence of prose.
   - Name for intent rather than implementation, so the right call is the one that reads correctly.
   - Make invalid states unrepresentable wherever the type system allows it. A parameter that cannot express a mistake needs no warning about that mistake.
3. Put behavioral instruction in the tool's own description, at the point of use, and only there. The same guidance restated in a global preamble is how a codebase grows contradictions.
4. Treat the urge to add a usage example as a diagnostic: it usually means a parameter is underspecified. Fix the interface first. Keep an example only for a format that genuinely cannot be guessed, such as a bespoke query syntax.
5. Decide what is resident and what is discoverable. Tools needed on most turns belong in context; tools needed rarely should be findable on demand so they cost nothing until they're wanted.
6. Finish by naming the mistake the design still permits, and say whether it is cheap enough to live with or needs an explicit guardrail.

## Guardrails

- A description that has to explain what a parameter means is a parameter that needs a better name.
- Irreversible and high-stakes operations are the exception to all of the above: there, explicit constraint and confirmation beat elegance.
- Never redesign a signature without first finding every existing caller.
- Terseness is not the goal; expressiveness is. Cutting a description that carried real behavior is a worse outcome than a description that ran long.

# Assumption test

A plausible assumption can survive every planning conversation and still fail on contact with the system. Turn the consequential uncertainty into a question an experiment can answer.

## Steps

1. Read the request, relevant code, and existing evidence. If inspection already settles the question, cite that evidence and stop; do not manufacture an experiment. If several assumptions remain, select the one whose failure would most change the approach.
2. State the assumption as an observable prediction. Define what would refute it, what would support it within the tested scope, and what would leave it inconclusive. Set those criteria before observing the result.
3. Design the smallest discriminating experiment. Use an isolated fixture or test environment, the real component under question where available, and a bounded number of operations. Name what the setup cannot represent; a mock's behavior is not evidence about its provider.
4. Run the experiment within the user's authorized scope. Preserve the command, relevant inputs, actual output, and environment details needed to reproduce it. If a tool or dependency is unavailable, report the experiment as unrun or inconclusive, with the missing prerequisite.
5. Close with the assumption, method, observation, verdict (**supported within scope**, **refuted**, or **inconclusive**), and the planning decision this evidence changes. Recommend the next discriminating check only if it could change that decision. Keep temporary code separate from the production implementation.

## Guardrails

- One successful trial does not establish a universal claim. State the tested conditions and remaining uncertainty, particularly for concurrency and performance.
- Do not use production writes, real payments, destructive operations, or newly incurred costs without authorization. An experiment does not grant additional permissions.
- Distinguish the component failing from the experiment failing to run. Never turn missing access or a broken fixture into a verdict about the system.
- Do not fix the implementation or broaden into a build unless the user requested it. The deliverable is evidence that informs a decision.

# Blindspot pass

The user is about to work in territory they don't know well. Your job is not to do the task yet. Your job is to show them what they don't know they don't know, so their next prompt is better.

## Steps

1. Ask (or infer from context) two things: what they're trying to do, and what their experience level is with this specific area. Their starting point changes everything.
2. Explore the relevant territory yourself: the module, its history, its conventions, prior art in the repo, and (if the domain is external) what practitioners consider table stakes.
3. Report back in four sections:
   - **Landmines** — the mistakes someone new here typically makes, and any repo-specific potholes (deprecated paths, misleading names, half-migrated patterns).
   - **Hidden context** — decisions already made that constrain the work (why the code is shaped this way, invariants that must hold).
   - **What good looks like** — 2-3 examples of the pattern done well, from this repo or elsewhere, so they can calibrate quality.
   - **Questions you should be asking** — the 3-5 questions an expert would ask before starting, with your best guess at each answer.
4. End with a rewritten version of their original request that incorporates what you found, so they can see the difference between their map and the territory.

## Guardrails

- Do not start implementing. This skill ends at understanding.
- Prioritize unknowns that would change the architecture or the approach over trivia.
- If the area turns out to be simpler than the user feared, say so plainly. "You have no significant blindspots here" is a valid and valuable result.

# Brainstorm and prototypes

The user has unknown knowns: criteria they can't verbalize but will recognize on sight. Finding those during prototyping is cheap; finding them mid-implementation is expensive, because small spec changes can mean drastically different code. Give them things to react to.

## Steps

1. Establish scope first: what is being decided (layout? approach? data model? tone?) and what is explicitly out of scope. One decision per round.
2. Produce 3-5 variations that are **wildly different, not shades of the same idea**. If two variations would get the same reaction, replace one.
3. Make them cheap and disposable:
   - Visual/UX → a single self-contained HTML file with fake data, no backend, no state.
   - Approaches → a one-screen sketch of each: the idea, what it optimizes for, its sharpest tradeoff.
   - Ranked lists → order from cheapest to most ambitious so the user can draw their line.
4. Label each variation with the belief it bets on ("this one assumes density beats whitespace"), so the user's reaction reveals the underlying criterion, not just a preference.
5. Collect reactions, then verbalize what was learned: "you consistently rejected X, which suggests the real requirement is Y." That sentence is the deliverable — it becomes part of the spec.

## Guardrails

- Nothing produced here is production code. Say so, and don't wire prototypes into the real app.
- Do not converge early to the variation you'd pick. The point is spanning the space.
- If the user reacts to none of them, that's signal too: the decision space was framed wrong. Reframe and rerun rather than generating more of the same.

# Change quiz

After a long session the agent has often done more than the user realizes, and a diff only shows surface. Behavior lives in how the change interacts with existing code paths. The user should merge only what they can pass a quiz on.

## Steps

1. Build the report first, in four short sections:
   - **Context** — what problem this session set out to solve.
   - **What changed** — grouped by intent (feature, fix, refactor), not by file.
   - **How it interacts** — the existing code paths the change touches, and what now behaves differently even in files the diff doesn't show.
   - **Intuition** — the 2-3 mental-model updates the user should walk away with ("retries are now idempotent because X").
2. For long sessions, offer the report as a single self-contained HTML page with the quiz at the bottom — it reads better than a wall of markdown.
3. Then the quiz: 5-8 questions targeting what would bite an unaware maintainer.
   - Mix recall ("what happens to in-flight jobs during deploy now?") with prediction ("if someone calls X with a stale token, what do they see?").
   - Weight questions toward deviations, edge cases, and interaction effects — not trivia about names.
4. Grade honestly, one round at a time. For each miss, explain the right answer AND flag it: a miss is either a gap in the user's model or a sign the change is too clever — say which.
5. Pass = merge-ready. Fail = point back to the specific report sections to reread, then offer a fresh variant quiz. Do not soften the bar; the whole point is that unread changes don't ship.

## Guardrails

- The quiz covers the change and its blast radius, not general knowledge.
- If the user can't pass after two rounds, the recommendation is to simplify the change or split it, not to keep quizzing.
- Never mark the user correct out of politeness. A false pass defeats the skill.

# Context audit

A prompt is written for one task; context is reused across every task, so it can never be as specific. That gap is where instructions rot: rules written for a worst case that no longer happens, guidance duplicated across three layers, two layers quietly telling the model opposite things. The model can resolve all of it — by spending thinking budget on it before it starts your actual work. This skill finds what to delete.

## Steps

1. Inventory every layer that reaches the model: root and nested `CLAUDE.md`/`AGENTS.md`, each skill's description and body, hooks, tool and MCP server descriptions, and any harness prompt the user controls. Report each layer's size. The layer the user forgot they wrote is usually the loudest one.
2. Read them together, the way the model receives them — not one file at a time. Contradictions only exist between layers.
3. Classify every instruction as one of five things:
   - **Conflict** — two layers pulling opposite ways ("document as appropriate" against "never add comments"). Quote both sides verbatim. These are the most expensive finding and go first.
   - **Duplicate** — the same instruction in two places. Keep the copy nearest the point of use; behavior of a tool belongs in that tool's description, not in the global preamble.
   - **Obvious** — restates what the file tree, the language, or the surrounding code already shows.
   - **Judgement-now** — a blanket rule written to prevent a worst case, wrong for some real subset of requests, and the kind of call a current model makes well on its own.
   - **Gotcha** — non-obvious, specific to this repo, load-bearing. This is what should survive; most repos are mostly the other four.
4. Propose the cut as a diff: conflicts resolved first, then duplicates, then the rest. For anything that is worth keeping but only sometimes needed, propose relocating it into a skill or a linked file loaded on demand rather than deleting it.
5. Close with before/after line counts and the single deletion you are least confident about, named explicitly so a human decides that one.

## Guardrails

- Propose, don't apply. The user approves every deletion.
- A rule that reads as over-constraint is sometimes scar tissue from a real incident. Anything naming a specific failure gets asked about, not cut.
- Judge instructions by whether they change behavior, not by whether they sound wise. A line the model already follows by default costs tokens to say nothing.
- If the harness ships its own rightsizing command, this runs alongside it, not instead of it.
- An audit that deletes a real invariant costs far more than the tokens it saved. When a line's purpose is unclear, that ambiguity is the finding — report it rather than guessing.

# Implementation notes

No amount of planning removes every unknown; some only appear once the code is open. When the territory disagrees with the plan, don't stop and don't silently improvise — take the conservative option, write it down, and keep going. The notes file is how the next attempt learns from this one.

## Steps

1. At the start of the build, create `implementation-notes.md` with three headings: **Deviations**, **Discovered edge cases**, **Questions for review**.
2. Whenever reality forces a choice the plan didn't cover:
   - pick the conservative option (the one that's easiest to reverse),
   - log it under Deviations: what the plan said, what was done instead, why, and what it would take to revisit,
   - continue working. Do not block on the user for reversible decisions.
3. Log edge cases as they're found, even ones handled cleanly — they are exactly the unknowns the next plan should account for.
4. Anything irreversible or scope-changing goes under Questions for review AND stops the work at a safe checkpoint. Deviating conservatively is fine; deviating expensively needs a human.
5. At the end, append a five-line summary: deviations count, the one most likely to be revisited, edge cases found, and what the next session should read first. Reference the file in the handoff or PR.

## Guardrails

- The notes file is temporary working memory, not documentation. Keep entries to 2-3 lines each.
- Never let the notes drift from reality — an unlogged deviation is worse than no notes at all, because the file claims completeness.
- "Conservative" means reversible, not necessarily simple.

# Implementation plan

A plan's job is not to prove you thought of everything. It's to put the reversible-but-expensive decisions in front of the user while changing them is still free. Order the plan by likelihood-of-tweaking, not by build order.

## Steps

1. Open with a three-line summary: what is being built, the approach chosen, and the single riskiest assumption.
2. **Section 1 — Decisions you'll probably want to tweak.** Data model changes, new type interfaces, API shapes, anything user-facing. For each: the choice made, one alternative considered, and what changing it later would cost.
3. **Section 2 — Known unknowns and how the plan absorbs them.** Where ambiguity remains, state the default that will be taken and the signal that would trigger a pivot. A plan that admits its unknowns survives contact with the territory; one that doesn't just breaks quietly.
4. **Section 3 — The mechanical work.** Refactors, wiring, migrations, tests. Compress this; the user trusts you here and reviewing it is a waste of their attention.
5. End with the review request: the 2-4 specific items you want a yes/no or a pick on before starting.
6. If the plan is more than a screenful or the user prefers visual artifacts, offer it as a single self-contained HTML page — sections collapsible, tweakable decisions pinned to the top.

## Guardrails

- If a genuinely better approach appears mid-planning, present the pivot as its own decision — don't silently re-plan.
- Keep it reviewable in minutes. A plan too long to read gets skimmed, and skimmed plans hide bad decisions.
- The plan should leave room for improvisation during implementation; over-specified plans fail exactly where the territory disagrees with the map.

# Interview me

Brainstorming is over and there are still gaps between the user's map and the territory. Close them by asking, one question at a time, starting with the questions whose answers would change the most.

## Steps

1. Read everything already established: the request, any spec, any prototypes, relevant code. Do not ask about things that are already answered.
2. Build a private list of open ambiguities and sort by blast radius:
   - **First: architecture-changers** — answers that would alter the data model, the interfaces, or the overall approach.
   - **Then: behavior definers** — edge cases, failure modes, defaults, permissions.
   - **Last: polish** — naming, copy, cosmetics. Often not worth asking; propose and move on.
3. Ask exactly one question per turn. For each: give the context that makes it matter, offer 2-3 concrete options with your recommendation, and accept "you decide" as an answer you then own.
4. Every few questions, checkpoint: restate what has been decided so far in one tight list, so drift dies early.
5. Stop when the remaining unknowns are cheaper to discover during implementation than to ask about now, and say that out loud. End with the final decision list, ready to paste into a plan.

## Guardrails

- One question at a time means one. No question bundles.
- Never ask a question whose answer is discoverable from the codebase; go look instead.
- If an answer contradicts an earlier decision, flag the conflict immediately rather than silently taking the newest answer.

# Pitch packager

Reviewers start with the same unknowns the builder started with, plus one more: whether the builder accounted for the failure points an expert would probe. A good pitch doc kills both in one read.

## Steps

1. Collect the artifacts: the spec or plan, the prototype or demo, the implementation notes, and the diff. Ask for a demo recording or screenshots if any user-facing behavior changed — lead with that.
2. Structure the document in reading order for a skeptic:
   - **The demo** — what it looks like working, first. A GIF or screenshot beats prose.
   - **The problem and the bet** — two paragraphs max: what this solves and the approach chosen over the alternatives.
   - **What an expert would ask** — the 3-5 hard questions a reviewer in this domain would raise (edge cases, scale, failure modes, migration), each answered honestly, including "not handled, here's why that's acceptable for now."
   - **Deviations from plan** — lifted straight from implementation-notes, because surprises found in review cost trust.
   - **What's NOT in this change** — scope fences, so the review doesn't sprawl.
3. Keep it one page. Link out to the spec, notes, and diff rather than inlining them.
4. Match the medium to the venue: a Slack-pasteable doc, a PR description, or a standalone HTML page — ask which if unclear.

## Guardrails

- Never oversell: a pitch that hides a known weakness converts one approval into a permanent credibility loss.
- The "what an expert would ask" section is the heart. If it's easy to write, the questions aren't hard enough.
- If the work isn't actually ready, the honest pitch is a status update, and saying so is part of this skill.

# Progressive disclosure

A long instruction file is paid for on every single turn, including the turns that need none of it. The fix is not deletion — the material is real — but placement: keep what every run needs in the entry file, and move what only some runs need behind a pointer that fires when it's relevant. This skill restructures one artifact. To find out which artifacts need it, audit first.

## Steps

1. Read the whole artifact and identify its **branches** — the genuinely different ways a run can go through it. A verification section reached only when the user asks to verify is a branch; a rule that applies every time is not.
2. Sort every section into two piles: needed on every branch, and needed on one. The split is the entire decision, and it is usually less even than it looks — most files are a short universal core wrapped in branch-specific detail.
3. Keep the universal core in the entry file, ordered so the file still reads coherently on its own. An entry file that no longer makes sense without its children has been cut in the wrong place.
4. Move each branch into a sibling file named for what it holds, not for where it came from — `verification.md`, `glossary.md` — so the name alone tells the reader when to open it.
5. Write the pointer with care, because the pointer's wording is what decides whether the material is ever reached. Name the condition and the file together: "when the change touches migrations, read `migrations.md` before planning." A bare link at the bottom of a file is not a pointer.
6. Walk each branch end to end and confirm it still has everything it needs. Then report what moved, what stayed, and the new size of the entry file.

## Guardrails

- Splitting is not deleting. If a section is genuinely dead, say so and remove it outright rather than hiding it in a file nobody opens.
- Never split material that every branch needs. Two files that are always read together are one file with extra steps.
- A pointer that never fires has made the material invisible, which is worse than leaving it inline. When the triggering condition can't be stated crisply, that section stays put.
- Verify that the target harness actually ships sibling files alongside `SKILL.md` before relying on them; installers differ, and a pointer to a file that didn't travel is a broken skill.
- Stop when the entry file is legible. Splitting past that point trades one kind of unreadability for another.

# Reference hunt

Some requirements are too intricate or too tacit to write down, but working code somewhere already embodies them. The best reference is not a screenshot or a description — it's source. Read it like a spec, then reimplement the semantics, not the syntax.

## Steps

1. Get the reference: a repo path, a vendored folder, a library name, or a site whose underlying code can be read. Ask what specifically to extract from it — behavior, structure, visual system, API shape — so you don't imitate the wrong dimension.
2. Read the reference and produce a **semantics summary** before writing any code:
   - the behaviors and guarantees it implements (timing, ordering, error handling, edge cases),
   - the decisions that look deliberate versus incidental,
   - anything that won't translate to the target language or stack, with a proposed equivalent.
3. Have the user confirm the semantics summary. This is the moment misreadings get caught cheaply.
4. Reimplement in the target stack: same semantics, native idioms. Do not transliterate line by line, and do not copy code verbatim from references whose license doesn't allow it — note the license if it's unclear.
5. Close the loop: list each behavior from the summary and where the new implementation honors it, plus any place you consciously diverged and why.

## Guardrails

- The reference defines *what*; the target codebase's conventions define *how*.
- If the reference itself turns out to be buggy or inconsistent, surface that instead of faithfully reproducing the bug.
- Respect licenses: extracting semantics is fine; copying incompatible code is not.

# Test blindspots

Passing tests establish their assertions under their setup. The gap to investigate is where the implementation and its tests share the same untested assumption.

## Steps

1. Establish the intended behavior and scope from the request, specification, changed code, callers, and relevant tests. Run the relevant baseline when possible. If it is already failing, report that limitation rather than describing it as green.
2. Compare important behavior with what the tests actually assert. Look for a concrete gap: a mock replacing the boundary being claimed, an untested transition, a missing consumer expectation, or an invariant only exercised on the happy path. Choose by consequence and evidence, not by a generic checklist or coverage percentage.
3. For each selected gap, state the question and design a small exploratory probe that can distinguish correct from incorrect behavior. Use existing tooling and isolated data. Prefer the actual component over a mock when the mock is the source of uncertainty.
4. Execute the bounded probes within scope. Record observed behavior and the requirement it contradicts. If intended behavior is unclear, report a specification question; if execution is unavailable, report an untested risk. Neither is a confirmed defect.
5. For a confirmed failure, preserve a minimal reproducer. Add a focused regression test when test edits are within the task's scope; verify that it fails for the intended reason. Report any deliberately failing reproducer separately from the baseline. Do not silently repair production code.
6. Finish with confirmed defects first, then consequential untested risks or specification questions, the evidence for each, and what was not examined. Finding no consequential gap is a valid result.

## Guardrails

- Do not equate low coverage with a defect, or green tests with exhaustive correctness. A hypothetical scenario alone is not a finding.
- Preserve existing tests and assertions. Do not weaken a test, expand the refactor, or install an unrelated testing framework to produce a result.
- Keep probes away from production data and external side effects unless explicitly authorized. State when a local fixture cannot represent the real boundary.
- Keep this proportional to the change. Stop when further exploration is unlikely to alter the user's decision.