swain-design

What this skill does

<!-- swain-model-hint: opus, effort: high — default for artifact creation; see per-section overrides below -->

# Spec Management

<!-- session-check: SPEC-121 -->
Before proceeding with any state-changing operation, check for an active session:
```bash
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null
```
If the JSON output has `"status"` other than `"active"`, inform the operator: "No active session — start one with `/swain-init`?" Proceed if they dismiss.

This skill defines the canonical artifact types, phases, and hierarchy. Detailed definitions and templates live in `references/` (relative to this skill's directory). If the host repo has an AGENTS.md, keep its artifact sections in sync with the skill's reference data.

## Artifact type definitions

Each artifact type has a definition file (lifecycle phases, conventions, folder structure) and a template (frontmatter fields, document skeleton). **Read the definition for the artifact type you are creating or transitioning.**

| Type | What it is | Definition | Template |
|------|-----------|-----------|----------|
| Product Vision (VISION-NNN) | Top-level product direction — goals, audience, and success metrics for a competitive or personal product. | [definition](references/vision-definition.md) | [template](references/vision-template.md.template) |
| Initiative (INITIATIVE-NNN) | Strategic grouping of Epics under a Vision — provides a mid-level container for prioritization and decision tracking. | [definition](references/initiative-definition.md) | [template](references/initiative-template.md.template) |
| User Journey (JOURNEY-NNN) | End-to-end user workflow with pain points that drive epics and specs. | [definition](references/journey-definition.md) | [template](references/journey-template.md.template) |
| Epic (EPIC-NNN) | Large deliverable under a vision or initiative — groups related specs with success criteria. | [definition](references/epic-definition.md) | [template](references/epic-template.md.template) |
| Agent Spec (SPEC-NNN) | Technical implementation specification with acceptance criteria. Supports `type: feature \| enhancement \| bug`. Parent epic is optional. | [definition](references/spec-definition.md) | [template](references/spec-template.md.template) |
| Research Spike (SPIKE-NNN) | Time-boxed investigation with a specific question and completion gate. | [definition](references/spike-definition.md) | [template](references/spike-template.md.template) |
| Persona (PERSONA-NNN) | Archetypal user profile that informs journeys and specs. | [definition](references/persona-definition.md) | [template](references/persona-template.md.template) |
| ADR (ADR-NNN) | Single architectural decision — context, choice, alternatives, and consequences (Nygard format). | [definition](references/adr-definition.md) | [template](references/adr-template.md.template) |
| Runbook (RUNBOOK-NNN) | Step-by-step operational procedure (agentic or manual) with a defined trigger. | [definition](references/runbook-definition.md) | [template](references/runbook-template.md.template) |
| Design (DESIGN-NNN) | Standing design document covering interaction (UI/UX), data architecture, or system contracts. Domain selected via `domain: interaction \| data \| system` frontmatter field. | [definition](references/design-definition.md) | [template](references/design-template.md.template) |
| Training Document (TRAIN-NNN) | Structured learning material (how-to, reference, quickstart) that teaches humans how to use a feature or workflow. Tracks alongside source artifacts via commit-pinned `linked-artifacts` for staleness detection. | [definition](references/train-definition.md) | [template](references/train-template.md.template) |
| Chore (CHORE-NNN) | Lightweight cleanup work — small, bounded, and independently executable. Does not ship feature code. | [definition](references/chore-definition.md) | [template](references/chore-template.md.template) |

## Choosing the right artifact type

When the user's request doesn't name a specific type, infer it from their intent:

| User intent | Artifact | Signal words |
|-------------|----------|-------------|
| Product direction, why we exist | **Vision** | "product direction", "what should we build", "north star" |
| Strategic direction, group related work | **Initiative** | "focus on", "security effort", "group these epics", "strategic", "track" |
| Ship a feature or deliverable | **Epic** | "build X", "add Y feature", "implement Z" |
| One implementation unit | **Spec** | "fix this", "add a flag", "refactor", "small change", "bug" |
| Small cleanup | **Chore** | "cleanup", "organize", "move files", "relink", "small fix" |
| Research question | **Spike** | "should we", "investigate", "compare options", "what's the best way" |
| Record a decision | **ADR** | "decided to", "choosing between", "why did we" |
| Create training or documentation | **Train** | "how-to guide", "tutorial", "reference doc", "onboarding", "walkthrough", "training material", "teach someone" |

**Initiative vs Epic** — the key distinction:
- **Initiative**: a *direction* with multiple deliverables. "Harden security" is an initiative — it spans scanning, gates, policies. The operator steers it.
- **Epic**: a *deliverable* with multiple specs. "Build the scanning tool" is an epic — it has clear completion criteria. Agents execute it.
- **Rule of thumb**: if the work needs 2+ epics to describe, it's an Initiative. If it needs 2+ specs, it's an Epic. If it's one spec, just create the spec.

**Spec under Initiative (small work path)** — bugs, minor enhancements, and chores that relate to an Initiative's direction but don't warrant an Epic can attach directly to the Initiative via `parent-initiative`. If small work clusters, suggest promoting it to an Epic.

## Updating artifact metadata

When the operator asks to update a field on an existing artifact (e.g., "set VISION-001 priority to high", "re-parent EPIC-017 under INITIATIVE-001"):

1. Read the artifact's definition file to confirm the field name and valid values
2. Edit the frontmatter field directly (e.g., `priority-weight: high`)
3. Update the `last-updated` date
4. Run `bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" build` to refresh the graph cache
5. Commit the change

**Common updates:**
- `priority-weight` on Visions, Initiatives, Epics, and Specs — accepts `high`, `medium`, or `low`. Cascades: Vision → Initiative (can override) → Epic (can override) → Spec (can override). Affects downstream recommendation scoring and sibling sort order in `swain chart`.
- `parent-initiative` on Epics and Specs — re-parents them under an Initiative. A Spec can have `parent-epic` OR `parent-initiative`, never both.
- `parent-vision` on Initiatives — attaches to a Vision.

When the operator says "priority" or "weight" in the context of a Vision or Initiative, they mean the `priority-weight` frontmatter field.

## Creating artifacts

### Error handling

When an operation fails (missing parent, number collision, script error, etc.), consult [references/troubleshooting.md](references/troubleshooting.md) for the recovery procedure. Do not improvise workarounds — the troubleshooting guide covers the known failure modes.

### Complexity tier detection (SPEC-045)

Before running the full authoring ceremony, classify the artifact into a complexity tier:

**Low complexity (fast-path eligible)**:
- SPEC with `type: bug` or `type: fix` and no `parent-epic` and no downstream `depends-on` links
- SPIKE with no `parent-epic`
- Any artifact where the user uses language like "quick", "simple", "trivial", or "fast"

**Medium/High complexity (full ceremony)**:
- Feature SPECs (`type: feature`)
- Any SPEC or SPIKE with a `parent-epic`
- EPICs, INITIATIVEs, Visions, Journeys, ADRs — always full ceremony
- Any artifact where the user describes significant architectural decisi