feat(design): add assumption surfacing and resolution to design workflow

CLAUDE.md

@@ -11,7 +11,7 @@ Spec-driven app development with quality gates. Ensures the user gets what they
 | Skill | Purpose |
 |-------|---------|
 | `sw-init` | Project setup. Creates constitution + charter. Configures gates and hooks. |
-| `sw-design` | Interactive solution architecture. Research, design, adversarial critic. |
+| `sw-design` | Interactive solution architecture. Research, design, adversarial critic, assumption surfacing. |
 | `sw-plan` | Decompose design into work units with testable specs. |
 | `sw-build` | TDD implementation of one work unit. |
 | `sw-verify` | Interactive quality gates. Shows findings, validates against spec. |
@@ -53,6 +53,7 @@ Skills reference shared protocols in `protocols/` for fragile operations:
 - `insights.md` -- External Claude Code insights data access
 - `learning-lifecycle.md` -- Compaction triggers and tiered memory
 - `landscape.md` -- Codebase reference document format and freshness rules
+- `assumptions.md` -- Design assumption format, classification, and resolution lifecycle
 - `audit.md` -- Codebase health findings format, IDs, and lifecycle
 
 ## Key Rules

DESIGN.md

@@ -49,7 +49,7 @@ Persistent record of systemic issues that per-change gates miss: architecture de
 | Skill | Purpose | Key Innovation |
 |-------|---------|----------------|
 | `sw-init` | Project setup | Ask, detect, configure. Creates constitution + charter |
-| `sw-design` | Interactive solution architecture | Research, design, adversarial critic, user approval throughout |
+| `sw-design` | Interactive solution architecture | Research, design, adversarial critic, assumption surfacing, user approval throughout |
 | `sw-plan` | Decompose + spec | Reads design artifacts, breaks into work units, testable acceptance criteria |
 | `sw-build` | TDD implementation | Tester → executor delegation. Context doc travels with agents |
 | `sw-verify` | Interactive quality gates | Shows findings, not badges. Orchestrates gate skills in dependency order |
@@ -76,9 +76,10 @@ Invoked by verify, not directly by users.
 Solution architecture and implementation planning are separate skills:
 
 **sw-design** (interactive solution architecture):
-- Research codebase and external systems. Produce `design.md` + `context.md`.
+- Research codebase and external systems. Produce `design.md` + `context.md` + `assumptions.md`.
 - Conditional artifacts when warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strategy.md`, `infra.md`, `migrations.md`.
-- Adversarial critic challenges the design before approval.
+- Adversarial critic challenges the design and surfaces implicit assumptions before approval.
+- Assumptions are classified by category (technical, integration, data, behavioral, environmental) and resolution type (clarify, reference, external). User must resolve or accept each before design approval.
 - Adaptive phases: small requests skip critic, large requests get full treatment.
 - Design is per-request (shared across work units). Change requests via `/sw-design <changes>`.
 
@@ -115,9 +116,10 @@ Extracted once in `protocols/`, referenced by skills. Loaded on demand.
 | `insights.md` | External CC insights data access | ~150 |
 | `learning-lifecycle.md` | Compaction triggers, tier structure, theme format | ~150 |
 | `landscape.md` | Codebase reference doc format, freshness, updates | ~180 |
+| `assumptions.md` | Design assumption format, classification, and lifecycle | ~200 |
 | `audit.md` | Codebase health findings format, IDs, matching, lifecycle | ~180 |
 
-Total: ~2210 tokens (loaded on demand, not all at once).
+Total: ~2410 tokens (loaded on demand, not all at once).
 
 ## Skill Anatomy
 

agents/specwright-architect.md

@@ -18,6 +18,7 @@ You are Specwright's architect agent. Your role is strategic analysis and review
 
 - Review specs, plans, and designs for completeness and correctness
 - Challenge assumptions and identify what was missed (adversarial critic)
+- **Surface and classify design assumptions** -- identify statements treated as true without verification, categorize them, and recommend resolution paths
 - Verify implementations match specifications
 - Analyze architecture decisions against project charter and constitution
 - Identify risks, edge cases, and failure modes
@@ -34,6 +35,7 @@ You are Specwright's architect agent. Your role is strategic analysis and review
 - State your assumptions explicitly before analyzing. If uncertain about intent, flag it as a finding.
 - Flag over-engineering as a WARN finding. Prefer simpler architectures that meet the spec.
 - Scope your review to what the spec requires. Don't suggest improvements beyond the request.
+- When reviewing designs: actively hunt for implicit assumptions. Flag any statement that relies on unverified behavior of APIs, data shapes, third-party systems, infrastructure, or user behavior.
 
 ## How you work
 
@@ -48,4 +50,9 @@ You are Specwright's architect agent. Your role is strategic analysis and review
 Always structure your response as:
 - **Summary**: 1-2 sentence verdict
 - **Findings**: Numbered list with severity, description, file:line reference
+- **Assumptions**: Identified assumptions, each with:
+  - Title (concise statement of what is assumed)
+  - Category: `technical`, `integration`, `data`, `behavioral`, or `environmental`
+  - Resolution type: `clarify` (user answers questions), `reference` (needs API docs/schemas/types), or `external` (needs input from other teams)
+  - Impact (what breaks if the assumption is wrong)
 - **Verdict**: APPROVED or REJECTED with clear rationale

protocols/assumptions.md

@@ -0,0 +1,105 @@
+# Assumptions Protocol
+
+## Purpose
+
+Design assumptions are statements treated as true without verification. Untracked assumptions become risks. This protocol makes them visible, classified, and resolvable before implementation begins.
+
+## Artifact
+
+**File:** `.specwright/work/{id}/assumptions.md`
+
+Produced by sw-design during the critic phase. Travels with design artifacts to sw-plan and downstream.
+
+## Format
+
+```markdown
+# Assumptions
+
+Status: {resolved-count}/{total-count} resolved
+
+## Blocking
+
+### A1: {title}
+- **Category**: {technical | integration | data | behavioral | environmental}
+- **Resolution**: {clarify | reference | external}
+- **Status**: UNVERIFIED
+- **Impact**: {what breaks if this assumption is wrong}
+- **Needs**: {specific action to resolve}
+
+## Accepted
+
+### A2: {title}
+- **Category**: ...
+- **Resolution**: ...
+- **Status**: ACCEPTED
+- **Rationale**: {why the user accepted the risk}
+
+## Verified
+
+### A3: {title}
+- **Category**: ...
+- **Resolution**: ...
+- **Status**: VERIFIED
+- **Evidence**: {what confirmed it — doc link, user confirmation, code reference}
+```
+
+## Classification
+
+**Categories** (what the assumption is about):
+
+| Category | Description | Example |
+|----------|-------------|---------|
+| `technical` | How a technology works, its capabilities or limits | "Redis supports pub/sub at our expected throughput" |
+| `integration` | How an external system behaves, its API contract | "The payment API returns idempotency keys" |
+| `data` | Shape, volume, quality, or availability of data | "User records always have an email field" |
+| `behavioral` | How users or upstream systems will interact | "Requests arrive at most 100/sec" |
+| `environmental` | Infrastructure, permissions, network, deployment | "Lambda has access to the VPC subnet" |
+
+**Resolution types** (how to resolve):
+
+| Type | Meaning | Action required |
+|------|---------|-----------------|
+| `clarify` | Ambiguity the user can resolve with more detail | User answers specific questions |
+| `reference` | Needs authoritative documentation | User provides API docs, schemas, interface definitions, types, or specs |
+| `external` | Requires input from another team or third party | User escalates and reports back |
+
+**Statuses:**
+
+| Status | Meaning | Blocks design approval? |
+|--------|---------|------------------------|
+| `UNVERIFIED` | Not yet resolved | Yes |
+| `ACCEPTED` | User acknowledges the risk, proceeds anyway | No |
+| `VERIFIED` | Confirmed with evidence | No |
+
+## Lifecycle
+
+1. **Identification** -- Critic phase surfaces assumptions from the design. Research phase may also flag assumptions encountered during codebase analysis.
+2. **Classification** -- Each assumption gets a category and resolution type.
+3. **Presentation** -- All UNVERIFIED assumptions are presented to the user grouped by resolution type, so the user sees a clear action list:
+   - "These need your clarification: ..."
+   - "These need reference docs: ..."
+   - "These need answers from other teams: ..."
+4. **Resolution** -- User resolves each assumption by answering, providing docs, or accepting the risk.
+5. **Gate** -- Design cannot be approved while BLOCK-category assumptions remain UNVERIFIED. The user may move any assumption to ACCEPTED (risk acknowledged) to unblock.
+
+## Identification Heuristics
+
+Flag as an assumption when the design:
+
+- References an API, schema, or interface not verified against documentation
+- Assumes a third-party service behaves a certain way without evidence
+- Depends on data being in a specific format without validation
+- Assumes infrastructure or permissions exist without checking
+- Relies on performance characteristics not benchmarked
+- Expects another team's system to support a specific interaction pattern
+- Uses phrases like "should work," "probably supports," "typically returns"
+
+## Downstream Usage
+
+- **sw-plan** reads `assumptions.md` to ensure work unit specs don't depend on UNVERIFIED assumptions.
+- **sw-verify** (gate-spec) can reference VERIFIED assumptions as supporting evidence.
+- Assumptions with `external` resolution type may become dependencies in the plan.
+
+## Size
+
+Target: 10-30 assumptions for a complex design. Skip the artifact entirely for Quick-intensity designs. Lite-intensity designs produce assumptions inline in `context.md` rather than a separate file.

skills/sw-design/SKILL.md

@@ -37,6 +37,7 @@ When complete, ALL of the following exist in `.specwright/work/{id}/`:
 
 - `design.md` -- solution overview, approach, integration points, risk assessment
 - `context.md` -- research findings, file paths, gotchas (travels with downstream agents)
+- `assumptions.md` -- classified assumptions with resolution status (Full intensity only; Lite inlines in context.md; Quick skips)
 
 When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strategy.md`, `infra.md`, `migrations.md`. Only produce conditional artifacts when needed.
 
@@ -67,14 +68,25 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate
 - Reference charter (vision) and constitution (practices). Present alternatives when reasonable.
 
 **Critic (HIGH freedom):**
-- For non-trivial requests, delegate to `specwright-architect` to find flaws. Show user findings and resolutions.
+- For non-trivial requests, delegate to `specwright-architect` to find flaws AND identify assumptions. Show user findings and resolutions.
 - Skip for straightforward requests.
 
+**Assumption resolution (MEDIUM freedom):**
+- Follow `protocols/assumptions.md` for format and classification.
+- After critic, present UNVERIFIED assumptions to the user grouped by resolution type:
+  - `clarify` -- ask the user specific questions to resolve ambiguity
+  - `reference` -- ask the user to provide API docs, schemas, interface definitions, or types
+  - `external` -- flag items the user must resolve with other teams or third parties
+- User resolves each: answer the question, provide the doc, accept the risk, or mark as resolved.
+- Design CANNOT be approved while UNVERIFIED assumptions remain. User may ACCEPT any assumption (acknowledging risk) to unblock.
+- For Lite intensity: capture assumptions inline in `context.md` instead of a separate artifact.
+- For Quick intensity: skip assumption tracking entirely.
+
 **Change requests (MEDIUM freedom):**
 - `design.md` exists + argument: change request, re-run critic. No argument: ask — redesign, continue, or changes.
 
 **User checkpoints:**
-- Ask for hard constraints before research. Share findings after research, alternatives after design, resolutions after critic. User approves design before saving.
+- Ask for hard constraints before research. Share findings after research, alternatives after design, resolutions after critic, assumption resolution before approval. User approves design before saving.
 
 **State mutations (LOW freedom):**
 - Follow `protocols/state.md` for all workflow.json updates.
@@ -88,6 +100,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate
 - `protocols/context.md` -- anchor doc and config loading
 - `protocols/delegation.md` -- agent delegation for research and critic
 - `protocols/recovery.md` -- compaction recovery
+- `protocols/assumptions.md` -- assumption format, classification, and lifecycle
 - `protocols/landscape.md` -- codebase reference document format
 - `protocols/audit.md` -- codebase health findings format
 
@@ -100,4 +113,6 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate
 | `design.md` exists, no argument | Ask: redesign from scratch, continue to `/sw-plan`, or describe changes? |
 | Critic rejects entire approach | Present rejection to user with alternatives. Don't silently override. |
 | User disagrees with critic | User wins. Note disagreement in design.md for the record. |
+| Unresolved assumptions block approval | Present grouped by resolution type. User must clarify, provide references, or accept risk. |
+| User cannot resolve external assumption now | Mark as ACCEPTED with note. Design proceeds; assumption becomes a tracked risk in plan. |
 | Compaction during design | Read workflow.json, check which artifacts exist, resume next missing phase |