Specification Capture

You capture three specification elements that complement an issue's acceptance criteria, and you persist them to the decision journal so every downstream phase (PLAN, CODE, VERIFY) and every related command (/flow:design, /flow:brainstorm) can read from the same source of truth.

This skill owns the capture lifecycle and the journal contract — every consumer (/flow:start, /flow:design, /flow:brainstorm) invokes the skill instead of re-implementing it. Two failure modes the skill prevents:

1. No persistence-side check — without a single owner, a command can claim "captured all three" while writing only a partial set to the journal, and the gap silently flows into PLAN.
2. No shared source of truth — commands/design.md and commands/brainstorm.md would otherwise address overlapping elements (non-goals especially) without reading from or writing to the same .decisions/ artifact, so a user running /flow:design first and /flow:start second would get duplicate or contradictory specifications.

Iron Law

EVERY ISSUE GETS THE THREE ELEMENTS BEFORE PLAN. Acceptance criteria scope WHAT the user-visible outcome is. The three elements scope what the implementation IS NOT, how it behaves under failure, and what schemas it must honor. PLAN cannot fence the implementation without all three.

A captured specification is the contract between the issue and the per-task atomic units the implementation-planner agent produces. Without it, tasks lack failure-mode coverage and interface contracts — the Stranger Test (end-of-PLAN gate in commands/start.md) will fail.

Inputs

The invoking command MUST pass these in the prompt:

1. Issue context — title, body, labels, comments. The skill parses these for any specification language already in the issue.
2. Journal path — typically .decisions/issue-{N}.md (where {N} is the issue number). The skill reads this path first to detect prior captures.
3. Invocation reason — one of start, design, brainstorm. Used to scope which elements the skill focuses on (see "Per-invoker scope" below).

If any required input is missing, halt with SPEC_CAPTURE_BLOCK: missing input <name>. Partial inputs are NOT acceptable for this skill — without them, the capture cannot be authored or verified.

Process

Step 1: Read the journal first

Before parsing the issue or prompting the user, check the journal for an existing ## Specification heading:

JOURNAL="$1"  # path passed by invoker
if [ -f "$JOURNAL" ]; then
  awk '/^## Specification$/,/^## (Stranger Test|Decision|Implementation|Verification)$/{print}' "$JOURNAL"
fi

If the section exists, parse it for the three elements: ### Non-goals, ### Failure modes, ### Interface contracts. Record which are present and which are missing.

If the section exists AND all three elements are present AND the issue body has not been updated since the journal was last written (use git log -1 --format=%cd .decisions/issue-{N}.md for journal mtime, compare against issue's updatedAt field from gh issue view), return the existing specification verbatim. No re-prompting. The journal IS the source of truth.

If the journal section is partial (some elements missing) or stale (issue updated after journal write), proceed to Step 2 to fill the gaps.

Step 2: Extract from the issue body

For each missing element, scan the issue body and comments for prior statements:

If an element is found verbatim, capture it as-is and mark it extracted-from-issue. Do NOT prompt the user for elements that the issue already specifies — that wastes their time and creates friction.

Step 3: Prompt for missing elements

For each element that is still missing after Steps 1 and 2, draft a 3-5 item proposal based on the issue's domain, then surface a Proactive-Autonomy escalation per references/escalation-format.md using AskUserQuestion. The six fields per element prompt:

• Situation — Issue #{N} is missing the {element-name} portion of its specification. Without it, downstream phases cannot {phase-specific consequence: PLAN cannot fence implementation / CODE cannot test failure paths / VERIFY cannot evaluate adversarial cases}.
• What I tried — Read issue body and {N} comments. Searched for cues ({list of cues from the table above}). No prior statement found.
• Options — (1) Accept the agent's proposal as written. (2) Accept with edits (the agent will prompt for changes). (3) Reject — the specification is incomplete and the issue should be updated first.
• Recommendation — Option {1|2} based on the proposal's specificity. Option 3 only when the agent cannot produce a credible proposal from the issue context.
• Blocking? — Yes. Blocks PLAN; the Spec Validation Gate cannot proceed until this resolves.
• Risk — Choosing Option 1 with a wrong proposal locks the implementation into the wrong fence; the agent will surface a Stranger Test failure later but the user will have wasted PLAN cycles. Choosing Option 3 means the issue must be updated before re-running the workflow.

Surface ONE escalation per missing element. Do not bundle (a compound prompt forces the user to make multiple decisions in one click; see references/escalation-format.md anti-patterns).

Step 4: Write the journal

Write the captured specification to the journal under the canonical heading. Idempotent (rewrite the section if it exists; append it if it doesn't):

## Specification

_Captured by specification-capture skill on YYYY-MM-DD. Source: {extracted-from-issue | user-confirmed | mixed}._

### Non-goals

- {non-goal 1}
- {non-goal 2}

### Failure modes

- **Timeouts** — {expected behavior when an upstream call exceeds expected latency}
- **Partial failures** — {expected behavior when some operations succeed and others fail}
- **Invalid input** — {expected behavior when input violates the contract: error type, fallback, user-visible message, log signal}
- **Missing context** — {expected behavior when required config, env vars, or state are absent}

### Interface contracts

- {Contract 1: schema, signature, or shape; format depends on what the change touches}
- {Contract 2}

The four failure-mode sub-bullets are the minimum coverage. The skill MUST NOT skip any of them — if a category genuinely doesn't apply, capture it as none — {one-clause reason} per the none-as-positive-statement discipline used in references/evidence-bundle-format.md. Bare blank is not permitted.

After writing, verify by re-reading: awk '/^## Specification$/,/^## /{print}' "$JOURNAL" should produce the section back. If it doesn't, halt with SPEC_CAPTURE_BLOCK: journal write verification failed.

Step 5: Return the captured specification

Return the captured specification to the invoking command in this shape:

## Captured Specification

**Issue**: #{N}
**Journal**: .decisions/issue-{N}.md
**Source**: {extracted-from-issue | user-confirmed | mixed}

### Non-goals
{...}

### Failure modes
{...}

### Interface contracts
{...}

Downstream consumers (implementation-planner agent, Stranger Test gate, Phase 4 evidence bundle producer) read these elements and reference them by name (Non-goals touched, Failure modes covered, Interface contract).

Per-invoker scope

The skill always writes the elements it captures to the journal regardless of invoker. A /flow:brainstorm call that captures non-goals first will pre-populate that element for a later /flow:start call on the same issue, eliminating duplicate prompting.

Anti-patterns

Verification gates

The invoking command MUST verify after this skill returns:

1. The journal contains a ## Specification heading
2. All three element subsections are present and non-empty (or none — {reason} for failure-mode categories that don't apply)
3. The skill's return payload matches the journal contents

If any check fails, the invoking command halts and re-invokes the skill with the failure noted. Silent acceptance of partial specs is forbidden.