Assumption Inventory

Assumption Inventory

Before a long run, the cheapest bug to fix is a wrong premise. This skill is a preflight: surface the assumptions the next stretch of work rests on, separate what you can cite from what you are guessing, and confirm the load-bearing guesses before the work starts — not after the diff lands.

The mechanism is one distinction held strictly: a fact is something on disk or stated by the user (it gets a citation); an assumption is everything else (it does not). The danger is an uncited assumption quietly becoming load-bearing — the work builds on it, and the divergence only surfaces hours later. This skill drags those assumptions into the open and gates the load-bearing ones on evidence or confirmation.

This is the front end of the triad: assumption-inventory (before), reground (mid-drift), fresh-eyes (after). Run it in order; do not skip to step 4.

1. Decide whether to run

Run this when the work ahead is long, expensive, hard to reverse, or multi-step and the target is not already crisply pinned. Skip it for a one-line change with an explicit target — the ceremony is not free. When in doubt on a big task, run it.

2. Draft the inventory

Fill every slot. For each, tag the basis: [cited: file:line / user said X] for a fact, [assumption] for a guess. Do not leave a slot blank — "unknown" is a valid, important answer.

• Goal — what outcome am I trying to produce, in one sentence? Why now?
• Root / scope — which repo, directory, or workspace is this rooted in? Is it

workspace-wide or one repo? What platform(s) must it run on?

• May edit — which files / areas am I allowed to change?
• Must not touch — what is off-limits (generated files, other repos, prod config,

contracts other code depends on)?

• Done means — what concrete, checkable state counts as complete? How will I know?
• Open questions — what do I not know yet that could change the above?

3. Stress the assumptions

For each [assumption], ask: what is the cheapest evidence that would settle this, and have I looked? Then look. Read the file, run pwd / git remote -v, check for a CLAUDE.md or ADR, grep for the symbol. Cheap checks turn guesses into citations now, before they cost anything. See [REFERENCE.md](REFERENCE.md) for the catalog of assumptions that are silently wrong most often (platform, scope, auth, volatile contracts) — check those by default even when they feel obvious.

4. Classify and gate

Sort every surviving [assumption] by whether it is load-bearing — would the work be wrong, wasted, or harmful if it turned out false?

• Load-bearing and unconfirmed → blocking. List it as an open question and ask the

user before proceeding. This is the whole point of the skill.

• Not load-bearing → state it explicitly as a stated assumption and proceed; the

user can correct it cheaply because it is visible.

Pressure-test the acceptance criteria specifically. The plan usually carries the "done means" criteria — but this is the moment to test them, not inherit them. Flag any criterion that is either weak (vague, unmeasurable, or untestable — "works well", "is fast", "handles errors") or built on an unproven assumption (it presumes a behavior, contract, schema, or file that step 3 could not cite). A criterion no one could objectively mark true or false, or one resting on a guess, is a blocking item — the plan looked done but its bar is soft. Surface these alongside the load-bearing assumptions; they are often the most valuable thing this preflight catches.

5. Ask the blocking questions, then proceed

Show the user the filled inventory as the written report (template in [REFERENCE.md](REFERENCE.md)) — that technical record stays. But for the blocking items, do not just list them in prose: ask them with the AskUserQuestion tool. A structured question forces a decision and makes the boundary explicit, where a prose note is easy to skim past. Reach for it whenever the uncertainty is about what to do or where the edge of the task is — the things the plan should have settled but didn't. Typical questions worth raising:

• Boundary — "Is X in scope or out?" / "Does this stop at the API, or include the UI?"
• Interpretation — "The goal could mean A or B — which?"
• Acceptance criteria — "This criterion is unmeasurable / rests on an unproven

assumption — how should 'done' actually be judged here?"

Offer concrete options (e.g. in scope / out of scope / defer) so the answer is a click, and recommend the one the evidence favors. Keep it tight — only genuinely load-bearing uncertainties become questions; the do not over-ask guardrail still holds, and if nothing is truly uncertain, say so and skip straight to proceeding. Stated non-blocking assumptions need no sign-off — they proceed unless corrected. Once the blocking questions are answered, the inventory (plus those answers) is the brief for the run; carry it forward and check work against it.

Guardrails

• Never silently upgrade an assumption to a fact. If you did not cite it, it is still

a guess, no matter how confident it feels.

• Default to portable, not this-machine-first. "Works on my OS / with my logins / in

this repo" is an assumption, not the goal — surface it, do not bake it in. See [REFERENCE.md](REFERENCE.md).

• Do not over-ask. Only load-bearing, unconfirmed assumptions block. Burying the user

in confirmable trivia is its own failure mode — check the cheap ones yourself first.

• This skill plans, it does not build. Its output is the confirmed inventory, not a

started implementation. Begin the work only after step 5.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adamlinscott
• Source: adamlinscott/claude-skills
• License: MIT
• Homepage: https://adam.icu

Install and usage instructions live in the source repository linked above.