---
name: assumption-log
description: Document assumptions, proceed with sensible defaults, surface for review at milestones. Use in research and planning workflows where context is incomplete. Blocks the "ask the user every 5 minutes" pattern and the "guess silently and break something" pattern. Every assumption becomes a named, reviewable artifact.
user-invocable: false
model-invocable: true
side-effects: file-writes
permission-profile: normal
triggers:
  - plan
  - research
  - "*"
---

# Assumption Log

## Iron Law

```
NEVER GUESS SILENTLY.
NEVER ASK FOR EVERY MISSING DETAIL.
DOCUMENT THE ASSUMPTION, PICK A SENSIBLE DEFAULT, SURFACE FOR REVIEW.
```

Silent guessing produces invisible errors. Asking for every missing detail breaks autonomous flow. The correct middle path: make the assumption explicit, pick a defensible default, continue, and surface the log at review gates.

## Recognize Your Own Rationalizations

- "I'll just ask the user." → Ask only when the decision is irreversible or the cost of a wrong assumption is high. For everything else: document and proceed.
- "I know what they meant." → If you know, document the inference explicitly. If you don't know, document the assumption and the default you chose.
- "It's obvious — I don't need to write it down." → What is obvious to you during planning is invisible to the reviewer and to your future self. Write it down.
- "I'll address it when it comes up." → When it comes up, you won't remember what assumption you made. The log is the memory.

## When to Run

- At the start of any research or planning phase with incomplete context
- When a planning decision depends on information that isn't in the codebase or spec
- When a scope decision must be made without explicit instruction
- Before each irreversible op (combine with `irreversible-ops` skill)

## Assumption Entry Format

For each assumption, record:

```
Assumption ID:   A-<NNN>
Category:        <scope | design | dependency | behaviour | constraint>
Statement:       <what you are assuming to be true>
Basis:           <why this default was chosen — evidence, convention, or reasoning>
Default chosen:  <the specific value, behaviour, or approach you will proceed with>
Confidence:      <high | medium | low>
Falsifier:       <what evidence would prove this assumption wrong>
Review gate:     <at what milestone or checkpoint this should be surfaced>
Impact if wrong: <what breaks if the assumption is incorrect>
```

**Confidence guidelines:**
- `high` — strong evidence from code, docs, or established convention; probably correct
- `medium` — inferred from partial evidence; plausible but should be confirmed
- `low` — no evidence; pure default; must be confirmed before the affected code ships

## Assumption Categories

**Scope** — what is in/out of this task
> "Assumption: the email notification feature is out of scope for this slice. Basis: spec says 'user profile update' with no mention of notifications. Default: skip. Review at slice completion."

**Design** — how something should be structured
> "Assumption: use SQLite for local state storage rather than JSON files. Basis: project uses SQLite everywhere else. Default: SQLite. Confidence: high."

**Dependency** — which version, API, or external behaviour to rely on
> "Assumption: the gateway API responds within 5 seconds. Basis: no SLA documented; 5s is standard for synchronous APIs. Default: 5s timeout. Confidence: medium."

**Behaviour** — what the system should do in an edge case
> "Assumption: on parse error, return empty array not null. Basis: existing code uses empty arrays for not-found cases. Default: []. Confidence: high."

**Constraint** — limits on resources, permissions, or side effects
> "Assumption: this migration is safe to run without a maintenance window. Basis: adds a nullable column, no lock required. Default: proceed without window. Confidence: medium. Falsifier: if table > 10M rows, lock time may matter."

## Review Gate Protocol

At each milestone or slice completion, surface all `medium` and `low` confidence assumptions:

1. List all logged assumptions for the current slice
2. Mark each: `CONFIRMED` (user or evidence validated it), `REVISED` (different default chosen), or `OPEN` (still unconfirmed)
3. Any `low` confidence assumption that remains `OPEN` blocks slice completion
4. Any `medium` confidence assumption that remains `OPEN` is a known risk — document it in the slice evidence

## Completion Criteria

- [ ] All assumptions made during the workflow are logged with full entry format
- [ ] All `low` confidence assumptions are confirmed or revised before the slice ships
- [ ] All `medium` confidence assumptions are surfaced at the milestone gate
- [ ] The assumption log is attached to the current unit artifact or recorded under `.sf/assumptions/<unit-id>.md`
