--- name: assumption-surfacing description: "Use when: surfacing implicit assumptions in a spec, plan, design, or estimate before work starts: data shapes, ordering, scale, auth context, environment, compatibility, dependency behavior, and people-process expectations, classifying each as verify-before-build or accept-with-risk." argument-hint: "The spec, plan, design, or estimate text to sweep for implicit assumptions, plus any context about the system it targets." user-invocable: true --- # Assumption Surfacing Enumerate the implicit assumptions a spec, plan, design, or estimate silently depends on, and decide for each whether it must be verified before building or can be consciously accepted with a named risk. Unsurfaced assumptions become mid-build surprises; surfaced ones become a checklist. ## When to Use Use before implementation starts, when a spec, plan, design doc, or estimate is about to be committed to. Out of scope: verifying the assumptions themselves (this skill produces the verification worklist, not its results), reviewing finished code, challenging whether the work should happen at all, and general red-team critique of the design's decisions — this skill only extracts unverified premises the plan depends on. ## Required Inputs - The spec, plan, design, or estimate text. - Optional: system context (architecture notes, known constraints, prior incidents); used to ground assumptions, never required. If no text is provided, emit the BLOCK template; do not invent a plan to analyze. ## Assumption Categories Sweep the text once per category. For each, ask: what must be true for this plan to work that the text does not state or verify? 1. `data`: shapes, formats, encodings, nullability, uniqueness, volume, quality of existing data. 2. `ordering`: event order, idempotency, exactly-once vs at-least-once, race windows the plan ignores. 3. `scale`: load, growth, payload sizes, concurrency the design implicitly fits. 4. `auth-context`: who is authenticated, what tenant/role context is available where the code runs. 5. `environment`: runtime versions, infra availability, network topology, config presence. 6. `compatibility`: API consumers, stored-data formats, migration coexistence, rollback paths. 7. `dependency-behavior`: what third-party services, libraries, or sibling teams' components actually do under error, latency, or limit conditions. 8. `people-process`: review availability, deploy windows, on-call coverage, stakeholder sign-off the timeline presumes. ## Classification Each assumption gets exactly one disposition: - `verify-before-build`: a wrong guess would invalidate the design or cause rework larger than the verification cost. Carries a one-line verification step (who checks what, against which source). - `accept-with-risk`: verification costs more than the plausible damage, or the assumption is overwhelmingly likely and a wrong guess would not cause rework larger than the verification cost. Carries the named risk if wrong and the earliest signal that would reveal it. Tie-breaks, in order: when damage-if-wrong is structural (schema, contract, security, data loss), classify `verify-before-build` regardless of likelihood; when both definitions still apply, classify `verify-before-build`. ## Rules - Every assumption quotes or paraphrases the plan text that depends on it, with location. - State the assumption as a falsifiable claim ("the orders table has no rows with null customer_id"), not a topic ("data quality"). - Do not list universal background facts no plan could verify ("the compiler is correct"); an assumption is in scope when a realistic check exists or a realistic failure has been seen. - Assign each `verify-before-build` item an owner only from names/roles in the input; otherwise write `Owner: none named in input`. - Do not perform the verifications; produce the worklist. ## Output Format ```markdown ## Assumption Surfacing Report - Target: | # | Category | Assumption (falsifiable claim) | Disposition | |---|----------|--------------------------------|-------------| ### Verify before build For each, numbered as in the table: - Depends on: - Verification: - Owner: ### Accepted with risk For each, numbered as in the table: - Depends on: - Risk if wrong: - Earliest signal: ### Categories with no findings - : ``` Empty sections are written with `None`. When a category genuinely yields nothing, list it under categories with no findings rather than padding it. The report has no verdict line; `Verdict: BLOCK` appears only in the insufficient-input template below. ## Error Handling (BLOCK Template) Use this reduced template only for missing or unreadable input. ```markdown ## Assumption Surfacing Report Verdict: BLOCK - Missing input: - Smallest addition to proceed: ``` ## Example Plan step: "Backfill script copies all files from /var/avatars to the bucket, keyed by user ID." Table row: `| 1 | data | every file under /var/avatars maps to exactly one existing user ID, with no orphans or duplicates | verify-before-build |` Under `### Verify before build`: - Depends on: backfill step 1, which keys uploads by user ID. - Verification: run a dry-run listing pass comparing filenames against the user table before the copy. - Owner: none named in input ## Anti-Patterns - Topic-shaped assumptions ("data quality") instead of falsifiable claims. - Classifying by likelihood alone; the structural-damage tie-break overrides "it's almost certainly fine". - Performing the verifications or reporting their results; this skill ends at the worklist. - Padding every category with filler instead of using the no-findings line. - Inventing owners for verification steps when the input names none. ## Definition of Done All eight categories were swept and each is represented by findings or a no-findings line, every assumption is a falsifiable claim with a location anchor and exactly one disposition, every `verify-before-build` item has a verification step, and every `accept-with-risk` item has a risk and an earliest signal.