diff --git a/CLAUDE.md b/CLAUDE.md index e46d782..f9cb841 100644 --- a/CLAUDE.md +++ b/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 diff --git a/DESIGN.md b/DESIGN.md index d9178e0..a7530c5 100644 --- a/DESIGN.md +++ b/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 `. @@ -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 diff --git a/agents/specwright-architect.md b/agents/specwright-architect.md index 5679bdc..5844913 100644 --- a/agents/specwright-architect.md +++ b/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 diff --git a/protocols/assumptions.md b/protocols/assumptions.md new file mode 100644 index 0000000..4c3ab7f --- /dev/null +++ b/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. diff --git a/skills/sw-design/SKILL.md b/skills/sw-design/SKILL.md index 6270c4b..b4d210a 100644 --- a/skills/sw-design/SKILL.md +++ b/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 |