/done

description: Close increment with PM 3-gate validation (tasks, tests, docs). Use when all tasks complete and saying "close increment", "we're done", or "finish up".
version: 1.0.0
argument-hint: "<increment-id> [--auto]"

Close Increment (PM Validated)

Tool-Use Rationale

• **Bash**: Invoke the CLI closure gate (`specweave complete`), run `npx vitest run` and `npx playwright test` to verify the suite is green, and read `jq` values from `.specweave/config.json`.
• **Read**: Load `code-review-report.json`, `grill-report.json`, `judge-llm-report.json`, and `rubric.md` to evaluate gate outcomes.
• **Edit**: Update `metadata.json` status and any inline docs (CLAUDE.md, CHANGELOG.md) touched by the closure step.

Prompt Caching

`sw:done` is a closure orchestrator that chains `code-reviewer`, `simplify`, `grill`, and `judge-llm`. Because the same increment context is loaded four times over, Anthropic's ephemeral prompt caching gives closure a substantial cost/latency win.

**Files cached by default** (via `static-context-loader`):

• `CLAUDE.md` (project root)
• `.specweave/config.json`
• The active increment's `spec.md`
• The active increment's `rubric.md` (if present)

**Cache window**: 5-minute TTL (Anthropic's `cache_control: { type: "ephemeral" }` breakpoint). Consecutive gate invocations within the TTL read the cached prefix instead of re-tokenizing it.

**Extending the list**: Add paths to `cache.staticContextFiles` in `.specweave/config.json`:

{
  "cache": {
    "staticContextFiles": [
      "CLAUDE.md",
      ".specweave/config.json",
      ".specweave/docs/internal/specs/team-conventions.md"
    ]
  }
}

**Disable caching**: Set `cache.staticContextFiles: []` in `.specweave/config.json`. Closure gates will still run but without the shared prefix cache.

See `.specweave/docs/internal/specs/config-reference.md` and `opus-47-migration.md` for the full caching setup.

Project Overrides

**Skill Memories**: If `.specweave/skill-memories/done.md` exists, read and apply its learnings.

**PM-Led Closure**: Validate tasks, tests, and docs before closing.

**AUTO-CLOSURE DEFAULT**: After `sw:do` completes all tasks, `sw:done` runs automatically — no user confirmation needed. Quality gates (code-review, simplify, grill, judge-llm, PM validation) provide the safety net. If something is wrong, the user can re-open the increment.

Context Overflow Prevention

For large multi-agent sessions (via `sw:team-lead`), running `sw:done` directly may cause context overflow due to loading 4+ skill definitions into an already-full context. Instead, `sw:team-merge` spawns `sw:sw-closer` subagents that run the full closure pipeline in isolated fresh contexts -- one per increment. The `sw-closer` agent definition is at `plugins/specweave/agents/sw-closer.md`.

If you are closing an increment from a normal (non-team) session, use `sw:done` directly as documented below.

Usage

sw:done <increment-id> [--auto]

Argument: Required increment ID (e.g., "001", "0001", "0042", "0153-feature-name"). Numeric portion extracted and zero-padded to 4 digits.

Options

| Option | Description | |--------|-------------| | `--auto` | Legacy flag, now a no-op. Auto-closure is the default for all modes. All quality gates (code-review, simplify, grill, judge-llm, Gate 0, PM gates) always enforced. |

---

Workflow

Step 1: Self-Awareness Check (OPTIONAL)

If closing a SpecWeave framework increment, show post-closure reminders: update CHANGELOG.md, CLAUDE.md, consider version bump, run `npm test && npm run rebuild`, check for breaking changes. Informational only, not blocking.

Step 2: Code Review (MANDATORY — STOP GATE with Fix Loop)

**The CLI blocks closure if `code-review-report.json` is missing (when required).** Do NOT skip this step.

1. Check config: `jq -r '.codeReview.required // true' .specweave/config.json` — if `false`, skip to Step 3 2. Read max iterations: `MAX_ITER=$(jq -r '.codeReview.maxFixIterations // 5' .specweave/config.json 2>/dev/null)` — default cap is **5** in SpecWeave 1.1.0 (Opus 4.7 converges faster per iteration, so a higher cap catches edge cases without stalling closure) 3. Read blocking severities: defaults are `critical`, `high`, `medium` (configurable via `codeReview.blockingSeverities`) 4. **Iteration loop** (ITERATION=1): a. Invoke `Skill({ skill: "sw:code-reviewer", args: "--increment <id>" })` b. **Verify report written**: `Bash({ command: "test -f .specweave/increments/<id>/reports/code-review-report.json && echo OK || echo MISSING" })` c. If report MISSING: write it manually from code-reviewer output using the Write tool d. Read the report JSON: parse the `summary` object for severity counts e. **Evaluate blocking findings**: Sum counts for `critical` + `high` + `medium` (or configured severities) f. If no blocking findings → PASS, continue to Step 3 g. If blocking findings exist AND ITERATION < MAX_ITER:

• Display findings summary
• Implement fixes for all critical/high/medium issues from the report
• Increment ITERATION
• Delete the stale report: `rm -f .specweave/increments/<id>/reports/code-review-report.json`
• Go back to step 4a (re-run code-reviewer)

h. If blocking findings exist AND ITERATION >= MAX_ITER:

• **STOP closure** — display remaining findings
• Log: "Code review failed after {N} fix iterations. {X} findings remain."
• Increment stays in-progress

Step 3: Simplify (Non-Blocking Cleanup)

Code review passed. Run simplify to clean up code before the grill examines it.

1. Invoke `Skill({ skill: "simplify" })` — this is a built-in Claude Code skill, NOT a `sw:` skill 2. `/simplify` spawns 3 parallel agents checking: duplication, readability, efficiency 3. Apply any suggested improvements 4. **Non-blocking**: Even if simplify finds issues, proceed to Step 4 (Grill) 5. Purpose: Clean code before grill reduces grill findings and improves ship readin