Sw Design

---
name: sw-design
description: >-
  Autonomous solution architecture. Researches the codebase, designs a
  solution, challenges it adversarially, and produces design artifacts.
argument-hint: "[what you want to build or change]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task
---

# Specwright Design

## Goal

Research the codebase, design a solution, challenge it adversarially, and produce
design artifacts. Output is a design — not specs, not code. Operates autonomously
between research and gate handoff, applying `protocols/decision.md` for all decisions.

## Inputs

- The user's request (argument or conversation)
- `{projectArtifactsRoot}/CONSTITUTION.md` -- practices to follow
- `{projectArtifactsRoot}/CHARTER.md` -- vision and invariants
- `{projectArtifactsRoot}/config.json` -- project configuration
- `{worktreeStateRoot}/session.json` -- current worktree attachment, when present
- `{repoStateRoot}/work/*/workflow.json` -- other active works for collision checks
- The codebase itself

## Outputs

When complete, runtime and auditable artifacts exist in both locations:

- `{repoStateRoot}/work/{id}/stage-report.md` -- runtime-local design handoff digest with attention-required at the top
- `{workArtifactsRoot}/{id}/design.md` -- solution overview, approach, integration points, risk assessment
  - Required section: `## Blast Radius` listing: modules/files the design touches, failure propagation scope for each (local/adjacent/systemic), and what the design does NOT change.
- `{workArtifactsRoot}/{id}/context.md` -- research findings, file paths, gotchas (travels with downstream agents)
- design assumptions artifact under `{workArtifactsRoot}/{id}/` -- classified assumptions with resolution status
- `{workArtifactsRoot}/{id}/decisions.md` -- all autonomous decisions recorded per `protocols/decision.md`

When warranted: `data-model.md`, `contracts.md`, `testing-strategy.md`, `infra.md`, `migrations.md`.

## Constraints

**Stage boundary (LOW freedom):**
Follow `protocols/stage-boundary.md`. Produce design artifacts and research context.
NEVER write specs, decompose, implement, branch, or test. After gate handoff, STOP.

**Ownership guard (LOW freedom):**
- When the current worktree session is already attached to an existing work,
  resolve live ownership from `session.json`, not from branch names alone.
- If another live top-level worktree owns that work, STOP and point the
  operator to the explicit `/sw-adopt` flow rather than mutating design
  artifacts here.
- `/sw-adopt` may attach only the current worktree session. `sw-design` must
  never rewrite another worktree's `session.json`.

**Research (HIGH freedom):**
- Load LANDSCAPE.md, AUDIT.md, research briefs if they exist. Scan code, dependencies, patterns.md.
- Delegate to `specwright-researcher` and `specwright-architect` as needed.
- Derive hard constraints from constitution + charter (do not ask — these are documented).
- When the request itself is ambiguous, apply `protocols/decision.md` DISAMBIGUATION:
  infer intent from the argument, codebase context, and charter vision. Record the
  interpretation in decisions.md. If genuinely undetermined, surface at the gate.
- Research is complete when: integration is described, main risk is identified with
  mitigation, blast radius is bounded, no major gaps remain.

**Design (HIGH freedom):**
- Propose the simplest solution grounded in research. Justify abstractions.
- When choosing between alternatives, apply `protocols/decision.md` DISAMBIGUATION
  hierarchy. Record the choice and which rule resolved it in decisions.md.

**Critic (HIGH freedom):**
- For non-trivial requests, delegate to `specwright-architect` for adversarial review.
- Follow `protocols/decision.md#convergence-loop` for the iterative critic loop.
  Convergence at ≥4/5 on all dimensions with no BLOCKs auto-approves per
  `protocols/decision.md#approval`.
- Auto-revise BLOCKs (up to 2 iterations). Document WARNs in design.md.
- If critic rejects the entire approach: apply DISAMBIGUATION to choose the best
  alternative. Record in decisions.md.

**Assumption resolution (MEDIUM freedom):**
- Follow `protocols/decision.md#assumption-lifecycle` for format, classification,
  and autonomous resolution.
- After critic: auto-resolve per `protocols/decision.md#autonomous-resolution`.
  Clarify+technical → auto-ACCEPT. Reference/external → auto-DEFER to backlog per
  `protocols/backlog.md`.
- Assumptions contradicting an AC are Type 1 structural override — always blocking.
  Type 1 deficiencies halt and surface at the gate (do not auto-proceed).

**Change requests (MEDIUM freedom):**
- `design.md` exists + argument: change request, re-run critic.
- `design.md` exists + no argument: apply DISAMBIGUATION — if the user's prior message
  implies a change, treat as change request. Otherwise, present status at the gate.

**Approval target (LOW freedom):**
Per `protocols/approvals.md`, identify the design artifact set awaiting approval
for `/sw-plan`: `design.md`, `context.md`, `decisions.md`, the design
assumptions artifact, and any optional design supplements written in this run.
`sw-design` does not write `APPROVED` entries itself.

**Gate handoff (LOW freedom):**
On completion, emit the three-line handoff per the `protocols/decision.md`
Gate Handoff section. Write `{repoStateRoot}/work/{id}/stage-report.md`
before the handoff. The Artifacts line points at
`Artifacts: {repoStateRoot}/work/{id}/stage-report.md`. Detail lives in the
auditable artifact files under `{workArtifactsRoot}/{id}/` (`design.md`,
`decisions.md`, design assumptions artifact, `context.md`). The Next line
remains machine-parseable: `Next: /sw-plan`.

**State mutations (LOW freedom):**
Follow `protocols/state.md` for read-modify-write mechanics. Postconditions:
- New work created at `{repoStateRoot}/work/{id}/`.
- `{worktreeStateRoot}/session.json.attachedWorkId` is set to the new work ID for
  the current worktree only.
- Do not clear or rewrite unrelated active works in other top-level worktrees.
  Starting a new design in this worktree changes only this worktree's session
  attachment.
- If this worktree was previously attached to a shipped work and the user starts
  a new design, print exactly one informational notice before retargeting this
  worktree:
  `Clearing prior shipped work {unitId}. Run /sw-learn first if pattern capture is desired.`
  The notice is informational only; `sw-learn` remains optional.
- During legacy fallback migration, if prior `currentWork` has status `shipped`,
  clear that legacy attachment and reset `workUnits` to null before retargeting
  this worktree.
- The new selected work's `workflow.json.status` is `designing`.
- The new selected work's `targetRef` records the concrete remote, branch, role, resolution source, and resolution time for the selected work.
- The new selected work's `freshness` is seeded from the resolved `git.freshness` config at design time, carrying `validation`, `reconcile`, and `checkpoints`, with `status: "unknown"` and `lastCheckedAt: null`.
- The new selected work's `baselineCommit` is the SHA of the resolved target branch HEAD captured before any work begins and is never overwritten on re-entry.
- `targetRef` also written to `{workDir}/context.md` for historical reference.
- `baselineCommit` also written to `{workDir}/context.md` for historical
  reference.

## Protocol References

- `protocols/stage-boundary.md` -- scope, termination, and handoff
- `protocols/decision.md` -- autonomous decision framework, gate handoff, convergence loop, assumption lifecycle
- `protocols/state.md` -- workflow state updates and locking
- `protocols/context.md` -- anchor doc and config loading
- `protocols/delegation.md` -- agent delegation for research and critic
- `protocols/recovery.md` -- compaction recovery
- `protocols/landscape.md` -- codebase reference document format
- `protocols/audit.md` -- codebase health findings format
- `protocols/backlog.md` -- backlog item format and write targets
- `protocols/approvals.md` -- pending design artifact set and approval contract
- `protocols/research.md` -- external research brief format and consumption

## Failure Modes

| Condition | Action |
|-----------|--------|
| Request too vague | Apply DISAMBIGUATION from codebase + charter context. Record interpretation. If undetermined, surface at gate. |
| Active work in progress | Apply DISAMBIGUATION: if argument provided, start new. If no argument, continue existing. Record choice. |
| Selected work owned by another live top-level worktree | STOP with explicit `/sw-adopt` guidance |
| `design.md` exists, no argument | Apply DISAMBIGUATION: if user's message implies change, treat as change request. Otherwise, present status at gate. |
| Critic rejects entire approach | Apply DISAMBIGUATION to choose best alternative. Record in decisions.md. |
| User rejects design at gate | Revise per user feedback and re-run critic. User overrides critic — note in design.md. |
| Unresolved Type 1 assumptions | Surface at gate handoff as deficiencies. Do not auto-proceed. |
| Compaction during design | Read workflow.json, check which artifacts exist, resume next missing phase |