fatih-developer/assumption-checker

Assumption Checker Protocol

Before acting, stop and surface the assumptions you are making. Verify what you can, ask about what you cannot. Goal: catch wrong assumptions before building on them.

Core principle: Catching a wrong assumption now is far cheaper than discovering it 10 minutes later.

---

When to Activate

At Task Start

Run an assumption scan on every new task. Especially when:

• Task is ambiguous or missing information
• Phrasing is open to interpretation ("update", "fix", "clean up")
• Task involves irreversible actions
• External dependencies exist (API, files, database)

Before Critical Steps

Re-scan during execution when:

• Previous step output was unexpected
• A new dependency emerged
• User changed direction

---

4 Assumption Types

Technical Assumptions

Beliefs about environment, tools, and infrastructure.

• "Is this library installed?" → verifiable, check it
• "Is this API accessible?" → verifiable, test it
• "Does this work on this OS?" → platform-dependent

Data Assumptions

Beliefs about files, formats, and data structures.

• "Does this file exist?" → verifiable, check it
• "Does this CSV have headers?" → verifiable, inspect it
• "All rows are in the same format" → verify with sample

Business Logic Assumptions

Beliefs about rules, scope, and requirements.

• "Delete means soft delete" → ambiguous, ask
• "All users are affected" → scope unclear, ask
• "Date format is DD/MM/YYYY" → needs confirmation

User Intent Assumptions

Beliefs about what the user actually wants.

• "Refactor = don't change behavior" → ask
• "Quick = not production quality" → ask
• "Update = keep existing, add new" → ask
• "Clean up = delete? archive? organize?" → ambiguous, ask

---

Confidence Levels

Assign a confidence level to each assumption:

| Level | Meaning | Action | |-------|---------|--------| | VERIFIED | Checked and confirmed | Proceed | | VERIFIABLE | Can be checked with a tool/command | Check now | | UNCERTAIN | Cannot be verified, open to interpretation | Ask the user | | RISKY | If wrong, causes significant damage | Must ask |

---

Output Format

Task Start Scan

ASSUMPTION CHECK — Task Start
Assumptions found: N
Verified: N | Checking: N | Need to ask: N

## Technical
| Assumption | Confidence | Action |
|------------|------------|--------|
| [assumption] | VERIFIED/VERIFIABLE/UNCERTAIN/RISKY | [action] |

## Data
| Assumption | Confidence | Action |
|------------|------------|--------|
| [assumption] | ... | [action] |

## Business Logic
| Assumption | Confidence | Action |
|------------|------------|--------|
| [assumption] | ... | [action] |

## User Intent
| Assumption | Confidence | Action |
|------------|------------|--------|
| [assumption] | ... | [action] |

[Verifiable assumptions being checked now...]
[Questions for uncertain/risky assumptions:]

? [Question 1]
? [Question 2]

Pre-Step Scan (lighter format)

ASSUMPTION CHECK — Before [step name]
New assumptions: N found

| Assumption | Type | Confidence | Action |
|------------|------|------------|--------|
| [assumption] | Technical/Data/Logic/Intent | ... | ... |

[Questions or "All assumptions verified, proceeding."]

---

Verification Protocol

Check verifiable assumptions with tools before asking the user:

• File exists? → check filesystem
• Library installed? → check import
• JSON field present? → inspect data
• API reachable? → test endpoint

Update the assumption table: VERIFIABLE → VERIFIED or RISKY

---

Question Rules

• Ask at most 3 questions at a time — don't overwhelm the user
• Ask riskiest first — RISKY > UNCERTAIN
• Use yes/no or multiple choice — not open-ended
• Do not start the related step until answers arrive

---

When to Skip

• Task is single-step, clear, and easily reversible
• User said "just do it, make your own assumptions"
• All assumptions were already verified in previous steps
• Repeated task — same structure worked before

---

Guardrails

• Never skip assumption checking for irreversible actions, regardless of task simplicity.
• Keep scans concise — table format, not paragraphs.
• Verify before asking — don't ask the user things you can check yourself.
• Cross-skill: works with checkpoint-guardian (risk gates) and task-decomposer (plan validation).