Assumption Surface

assumption-surface

Force assumptions into the open. Do not start work while high-blast gaps remain.

Trigger on

• "before you start"
• "what would you assume"
• "what am I missing"
• "think this through first"
• "is this clear enough to build"
• Any request where scope, format, data source, or target is not specified

Blast radius

| blast | meaning | handling | |-------|---------|----------| | high | wrong guess → rework everything | mandatory question | | medium | wrong guess → section rework | recommended question | | low | wrong guess → easy patch | proceed with stated default |

Common assumption categories

| category | example | |----------|---------| | scope | all rows / filtered subset / just new ones | | format | JSON / CSV / XML / proprietary | | delivery | file / API response / email / webhook | | performance | best-effort / bounded latency / hard SLA | | concurrency | single user / many users / batch | | failure mode | fail loud / fail silent / degrade | | data source | prod DB / staging / cached / user-provided | | auth | authenticated / public / service-to-service | | target env | dev / staging / prod / all three | | persistence | in-memory / disk / database | | existing code | greenfield / extend existing / replace |

Process

1. Read the request. List every decision the implementer must make that was not stated.
2. Map each to a category above.
3. For each, note the default most LLMs would assume silently.
4. Rank by blast radius.
5. Extract questions for high + medium. Low proceeds with a noted default.
6. If no answer comes, generate 2–3 candidate interpretations ranked by likelihood.

Output

request: {one-line summary}

assumptions (high blast):
- {category}: {assumption} → default: {typical guess} → ask: {question}
- ...

assumptions (medium):
- {category}: {assumption} → default: {guess} → ask: {question}

assumptions (low — proceeding with defaults):
- {category}: {default}

minimum questions to proceed:
1. {question}
2. {question}

interpretations if no answer comes:
A. {reading 1} → implies {concrete choice chain}
B. {reading 2} → implies {concrete choice chain}
C. (optional) {reading 3}

recommended path: {A | B | C | hold for answers}
reasoning: {one line on why this path}

Worked example

Input: "add a way to export users"

request: export users functionality

assumptions (high blast):
- scope: all users vs filtered subset → default: all → ask: scope?
- delivery: file download vs API response → default: API → ask: how delivered?
- fields: which columns → default: id+name+email → ask: which fields (privacy)?

assumptions (medium):
- format: JSON vs CSV → default: JSON → ask: format?
- volume: thousands vs millions → default: thousands → ask: scale?

assumptions (low — proceeding with defaults):
- persistence: no caching needed
- auth: admin-only endpoint

minimum questions to proceed:
1. Scope + field set (privacy-critical)
2. Delivery mechanism
3. Expected volume (affects pagination / streaming choice)

interpretations if no answer:
A. Admin API endpoint → paginated JSON, id+email+name, admin-auth
B. One-off data dump → CSV file, all fields, run via script

recommended path: A
reasoning: API is safer default — paginated, auth-bound, does not need ops support

Hard rules

• List assumptions before writing code, prose, or structure.
• If zero high-blast assumptions exist, say "no hidden assumptions" and proceed.
• Never exceed 5 minimum questions. More = request is too broad, recommend decomposition.
• Never ask about style preferences unless the task is style-bound (writing, naming, UI).
• Defaults come from project context first, general conventions second.
• If the request is one sentence and hits 3+ high-blast assumptions, flag "request underspecified" at the top.
• Never proceed on low-blast defaults if user explicitly asked you to enumerate everything.

Source & license

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

• Author: Vix0007
• Source: Vix0007/vixero-skills
• License: MIT
• Homepage: https://vixdev.cloud/

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