assumptions

# Assumption Ledger Maintain a project-wide **Assumption Ledger** — durable memory of what was assumed, how sure we were, and how it was proved or disproved. Supports fresh context per slice without losing epistemic continuity. ## Input Mode + context: $ARGUMENTS Modes: - `create` — initialize a new ledger - `update` — add/update assumptions from a card, spike verdict, or slice result - `review` — summarize current ledger and recommend what to validate next ## Ledger location Default: `docs/assumptions.md`. If it exists, update — don't duplicate. ## Ledger schema Each entry MUST include: - **ID**: `A-###` (stable identifier) - **Statement**: one sentence, falsifiable if possible - **Type**: Requirement | Architecture | Implementation - **Confidence**: 0-100% - **Status**: Proposed | Validated | Invalidated | Obsolete - **Introduced by**: (card / spike / slice / commit) - **Validated by**: (test name, command, spike evidence) — required for Validated/Invalidated - **Last reviewed**: YYYY-MM-DD ## Graduation Protocol Assumptions track uncertainty and confidence. They are not permanent authority. When assumptions stabilize, promote them to their canonical home: - **Capsule promotion**: durable semantic law or glossary boundary → `docs/capsule.md` or `docs/capsule-<feature>.md` - **Roadmap/decision promotion**: strategic initiative choice with reversibility/rationale → `docs/roadmap.md` (and/or decisions log) - **Milestone promotion**: temporary phase sequencing or deferment → `docs/milestone.md` - **Contract promotion**: enforceable invariant now ready for code-level checks → `/pragma:contract` + tests When promoted, keep the assumption entry for history and add a "Promoted to" reference with path/anchor. ## Procedure ### Mode: create Create `docs/assumptions.md` with sections: Active (Proposed), Validated, Invalidated/Obsolete, Open Questions. Seed with 3-10 initial assumptions if obvious from capsule/card. ### Mode: update 1. Extract assumptions from context ("ASSUMPTION:" lines in cards, spike verdicts, slice summaries) 2. Match against existing entries → update confidence/status/evidence. New → assign ID, add under Active. 3. **Confidence < 70%** → mark High Risk, recommend clarification or `/pragma:spike` 4. Disproved by spike/test → move to Invalidated, note "Replaced by A-###" if superseded 5. For any stabilized assumption, apply the graduation protocol and add cross-reference links to the promoted artifact ### Mode: review 1. List Active (Proposed) sorted by: lowest confidence first, highest impact first 2. Recommend: `/pragma:spike` for unknowns, `/pragma:card`+`/pragma:slice` for E2E-validatable assumptions, `/pragma:characterize` for behavior already in code 3. Identify stale assumptions (not reviewed recently, weak evidence) 4. Identify promotable assumptions and their target authority document ## Constraints - **No vague assumptions.** "Should be scalable" → rewrite as falsifiable statement. - **Validated/Invalidated requires evidence.** Cite test, command output, or spike verdict. - **Do not delete history.** Invalidated assumptions stay recorded. - **Assumptions are not features.** The ledger records knowledge state, not work. - **Do not treat assumptions as semantic authority.** Durable definitions and laws must be promoted to capsule. ## Output 1. The updated `docs/assumptions.md` diff summary 2. The top 3 highest-risk active assumptions 3. Promotion summary (assumptions promoted, with destination artifacts) 4. The recommended next step (often `/pragma:spike` or `/pragma:card`) 5. **Lifecycle**: `State: governance`, `Next: /pragma:consult` (or the explicitly recommended next step), `Loop: /pragma:consult` (default unless user explicitly continues directly)