Silver Spec

---
name: silver:spec
description: >
  This skill should be used for AI-guided Socratic spec elicitation: interactive dialogue producing SPEC.md + REQUIREMENTS.md from scratch or augmenting an existing draft
argument-hint: "<feature name or description>"
version: 0.1.0
---

# /silver:spec -- Spec Elicitation Workflow

SB orchestrator for requirements elicitation. Guides PM/BA through structured Socratic dialogue to produce canonical `.planning/SPEC.md` and `.planning/REQUIREMENTS.md` artifacts.

Never implements features directly -- orchestrates dialogue and writes spec artifacts only.

## Pre-flight: Load Preferences

Read the **User Workflow Preferences** section of `silver-bullet.md` to load user workflow preferences before any other step. Silently apply any stored routing, skip, tool, or mode preferences throughout this workflow.

```bash
grep -A 50 "^## [0-9]\+\. User Workflow Preferences" silver-bullet.md | head -60
```

Display banner:

```
SILVER BULLET ► SPEC ELICITATION

Feature: {$ARGUMENTS or "(not specified)"}
Mode:    {greenfield | augment — detected in Step 0}
```

## Step-Skip Protocol

When the user requests skipping any step:
1. Explain why the step exists (one sentence)
2. Offer: A. Accept skip  B. Lightweight alternative  C. Show me what you have
3. If user chooses A permanently: record in silver-bullet.md §10b and templates/silver-bullet.md.base §9b, then commit both files.

**Non-skippable gates:** `Step 3: Socratic Elicitation`, `Step 5: Assumption Consolidation`, `Step 7: Write SPEC.md`, `Step 7a: Review SPEC.md`, `Step 8a: Review REQUIREMENTS.md`, `Step 9a: Review DESIGN.md`. Refuse skip requests for these regardless of §10.

## Step 0: Mode Detection

Check whether `.planning/SPEC.md` already exists:

```bash
test -f .planning/SPEC.md && echo "augment" || echo "greenfield"
```

- **If `.planning/SPEC.md` exists:** augment mode. Read the existing spec, show the current `spec-version` and a one-line summary of each section present.
- **If `.planning/SPEC.md` does not exist:** greenfield mode. Proceed directly to Step 1.

Update the Mode field in the banner to reflect the detected mode before continuing.

## Step 1: Context Gathering

Ask the PM/BA for the following in a single prompt. Mark required items clearly; optional items are lettered:

> **Let's start with context for this spec.**
>
> 1. Feature name *(required)*
> 2. Feature description — 1-2 sentences on what it does and for whom *(required)*
>
> Optional — provide any that apply:
>
> A. JIRA ticket ID
> B. Figma URL
> C. Google Doc or PPT URL

If any URL is provided in A, B, or C, note it internally for artifact injection in Step 4.

## Step 2: Invoke product-management:write-spec

Invoke `product-management:write-spec` via the Skill tool. This generates a formal PM spec scaffold that provides structure for the Socratic dialogue to fill in.

If the skill is unavailable (invocation fails or skill not found), STOP and
notify the user instead of proceeding without it. Offer: A. Install the plugin
and retry  B. Continue only with an explicitly approved degraded path
  C. Stop / choose a different workflow.

## Step 3: Socratic Elicitation Dialogue

**NON-SKIPPABLE GATE.**

Run 9 questioning turns in sequence. Each turn addresses one requirements domain.

**After EACH answer from the PM/BA:**
1. State any implicit assumption you made interpreting the answer: "I'm assuming [X] — is that right?"
2. If the PM/BA says "I don't know yet", cannot resolve, or gives a vague answer: emit an assumption block immediately:
   `[ASSUMPTION: {what SB is assuming} | Status: Follow-up-required | Owner: TBD]`
3. Ask: "Anything else on this topic, or shall we move to the next?"

Collect all answers and assumption blocks for Steps 5-8.

**Turn sequence:**

| Turn | Domain | Question |
|------|--------|----------|
| 1 | Problem | "What problem does this solve? For whom?" |
| 2 | User goal | "When a user reaches this feature, what do they want to accomplish?" |
| 3 | Scope boundary | "What is explicitly OUT of scope for this feature?" |
| 4 | User stories | "Walk me through the main thing a user does with this feature, step by step" |
| 5 | Acceptance criteria | "How do we know this works correctly? List one criterion at a time" |
| 6 | Edge cases | "What happens when [common failure scenario]?" |
| 7 | Error states | "What should the user see when something goes wrong?" |
| 8 | Data model | "What data does this feature create, read, update, or delete?" |
| 9 | Open questions | "What do you not know yet that would affect the spec?" |

**Assumption trigger patterns (include in phrasing):**
- Turn 1: "I'm assuming the primary user is [X] — is that right?"
- Turn 2: "I'm assuming success means [X] for the user"
- Turn 3: "I'm assuming [related capability] is not included in this release"
- Turn 4: After each step the user describes: "I'm assuming [step detail] — confirm?"
- Turn 5: "I'm noting [criterion] as testable — does it have a measurable threshold?"
- Turn 6: "I'm assuming [edge case] is handled by [default behavior]"
- Turn 7: "I'm assuming error messages follow [language/tone]"
- Turn 8: "I'm assuming [data entity] already exists in the system"

**Minimum turn enforcement:**

Maintain an internal turn counter starting at 0. Increment after each completed turn.
Do NOT proceed to Step 7 (Write SPEC.md) until the turn counter reaches at least 4.
If the user requests to skip remaining turns before turn 4, respond:

> "Spec elicitation requires a minimum of 4 turns to ensure adequate coverage. We've completed {N} so far. Let's continue with Turn {N+1}."

After turn 4, remaining turns may be condensed if the user explicitly requests it and all
critical domains (Turns 1-4: problem, scope, user stories, acceptance criteria) are covered.

**Warning signs:** A completed elicitation with zero `[ASSUMPTION]` blocks is suspicious for any non-trivial feature. Surface at least one assumption check per domain.

## Step 4: Artifact Injection (conditional -- only if URL provided in Step 1)

If no URL was provided in Step 1, skip this step entirely.

For each URL provided:

1. Display the URL and describe what will be extracted.
2. Attempt extraction:
   - **Google Doc or PPT URL:** attempt text extraction via WebFetch tool. If accessible, show a 3-bullet summary of extracted content. If inaccessible, record the URL in `source-artifacts:` frontmatter for Phase 13 MCP ingestion.
   - **Figma URL:** record the URL in `figma-url:` frontmatter. Invoke `design:user-research` via the Skill tool for design context. If the skill is unavailable, STOP and notify the user. Offer install-and-retry first; only continue without design context if the user explicitly approves the degraded path.
3. Ask: "A. Incorporate this content into the spec  B. Skip"

If user selects A: incorporate the relevant content into the appropriate sections during Step 7.

## Step 5: Assumption Consolidation

**NON-SKIPPABLE GATE.**

Collect all `[ASSUMPTION: ...]` blocks surfaced during Steps 3 and 4. Present them as a numbered list.

For each assumption, ask:

> A. Resolve now (provide the answer)
> B. Accept as assumption (keep as-is in spec)
> C. Tag for follow-up (Status: Follow-up-required)

Update the `Status:` field of each assumption block accordingly:
- A → `Status: Resolved` (record the resolution text)
- B → `Status: Accepted`
- C → `Status: Follow-up-required`

If no assumptions were surfaced, note this and ask: "Before we write the spec, are there any open questions or unknowns you want to flag?"

## Step 6: Invoke design:design-critique (conditional)

Only if a design artifact (Figma URL or design-related Google Doc) was provided in Step 1 or referenced during elicitation:

Invoke `design:design-critique` via the Skill tool. If the skill is unavailable,
STOP and notify the user. Offer install-and-retry first; only continue without
design critique if the user explicitly approves the degraded path.

## Step 7: Write .planning/SPEC.md

**NON-SKIPPABLE GATE.**

1. Read `templates/specs/SPEC.md.template` to get the canonical structure.
2. **Determine spec-version:**
   - Greenfield mode: `spec-version: 1`
   - Augment mode: read existing `spec-version:` from `.planning/SPEC.md` frontmatter, increment by 1
3. Populate all sections from the elicitation answers collected in Steps 1-6:
   - `## Overview` — from Turn 1 (problem) and feature description
   - `## User Stories` — from Turn 4 (user stories)
   - `## UX Flows` — from Turn 4 (step-by-step flow)
   - `## Acceptance Criteria` — from Turn 5
   - `## Assumptions` — all `[ASSUMPTION: ...]` blocks with final Status values from Step 5
   - `## Open Questions` — from Turn 9 and any Follow-up-required assumptions
   - `## Out of Scope` — from Turn 3
4. Set frontmatter fields:
   - `spec-version:` — as calculated above
   - `status: Draft`
   - `jira-id:` — from Step 1 if provided, else empty string
   - `figma-url:` — from Step 1 if provided, else empty string
   - `source-artifacts:` — list of all URLs provided in Step 1 (empty list if none)
   - `created:` — today's date (greenfield) OR preserve existing value (augment)
   - `last-updated:` — today's date
5. Write to `.planning/SPEC.md` using the Write tool.

Every `[ASSUMPTION: ...]` block in the spec must include `Status:` and `Owner:` fields. No untagged assumptions.

### Step 7a: Review SPEC.md

**NON-SKIPPABLE GATE.**

Invoke `/artifact-reviewer .planning/SPEC.md --reviewer review-spec` via the Skill tool.

Do NOT proceed to Step 8 until /artifact-reviewer reports 2 consecutive clean passes. If issues are found, /artifact-reviewer will apply fixes and re-review automatically. If /artifact-reviewer surfaces an unresolvable issue after 5 rounds, STOP and present it to the user.

## Step 8: Write .planning/REQUIREMENTS.md

1. Read `templates/specs/REQUIREMENTS.md.template` to get the canonical structure.
2. Derive `REQ-XX` IDs from the acceptance criteria collected in Turn 5. Assign sequential IDs starting at REQ-01.
3. Derive `NFR-XX` IDs from any non-functional concerns raised during elicitation (performance, security, accessibility, reliability). Assign sequential IDs starting at NFR-01.
4. Mirror the Out of Scope section from SPEC.md.
5. Mirror the Open Questions section from SPEC.md.
6. Write to `.planning/REQUIREMENTS.md` using the Write tool.

### Step 8a: Review REQUIREMENTS.md

**NON-SKIPPABLE GATE.**

Invoke `/artifact-reviewer .planning/REQUIREMENTS.md --reviewer review-requirements` via the Skill tool.

Do NOT proceed to Step 9 until /artifact-reviewer reports 2 consecutive clean passes. If issues are found, /artifact-reviewer will apply fixes and re-review automatically. If /artifact-reviewer surfaces an unresolvable issue after 5 rounds, STOP and present it to the user.

## Step 9: Write .planning/DESIGN.md (conditional)

Only if a design artifact or Figma URL was provided:

1. Read `templates/specs/DESIGN.md.template` to get the canonical structure.
2. Populate from design context gathered in Steps 4 and 6.
3. Write to `.planning/DESIGN.md` using the Write tool.

### Step 9a: Review DESIGN.md (conditional)

**Only if Step 9 produced a DESIGN.md.**

Invoke `/artifact-reviewer .planning/DESIGN.md --reviewer review-design` via the Skill tool.

Do NOT proceed to Step 10 until /artifact-reviewer reports 2 consecutive clean passes. If issues are found, /artifact-reviewer will apply fixes and re-review automatically. If /artifact-reviewer surfaces an unresolvable issue after 5 rounds, STOP and present it to the user.

## Step 10: Commit artifacts

Stage and commit all spec artifacts:

```bash
git add .planning/SPEC.md
git diff --quiet .planning/REQUIREMENTS.md 2>/dev/null || git add .planning/REQUIREMENTS.md
git add .planning/DESIGN.md 2>/dev/null || true
git commit -m "spec: [feature-slug] v{spec-version} draft"
```

Replace `[feature-slug]` with a kebab-case version of the feature name from Step 1. Replace `{spec-version}` with the actual version number written in Step 7.

## Step 11: Summary

Display a closing banner:

```
SPEC ELICITATION COMPLETE

Feature:         {feature name}
Spec version:    {spec-version}
Sections:        {count of ## sections in SPEC.md}
Assumptions:     {count of [ASSUMPTION] blocks}
Open questions:  {count of open question items}
Status:          Draft

Next step: run /silver:feature to begin implementation planning.
```

If any assumptions have `Status: Follow-up-required`, add:

```
⚠  {N} assumption(s) require follow-up before implementation begins.
   Review .planning/SPEC.md §Assumptions before running /silver:feature.
```