ad-spec

name	ad-spec
description	Draft a feature-level specification at doc/specs/NNNN-<slug>.md following the kit's six-layer artifact stack (Constitution → Domain → Product → Spec → Plan/Decisions → Code). Adapts GitHub Spec Kit's mandatory sections (User Scenarios, Requirements, Success Criteria) to the kit's documentation discipline. Use when the user wants to write, draft, scaffold, or open a feature spec, feature brief, user stories, or success criteria for one feature multiple tasks will implement. Product-level scoping (PRD, multi-feature roadmap, target user, product success metrics) belongs to `ad-prd` (Layer 3); this skill is feature-level only. Status starts at draft; the file is the binding feature contract once accepted; references parent PRD for product-scope inheritance.
summary	Draft a feature spec at `doc/specs/NNNN-<slug>.md` (Spec Kit-aligned mandatory sections). Layer 4 of the six-layer artifact stack. References parent PRD (`ad-prd`, Layer 3) for product-scope inheritance.
allowed-tools	Read, Write, Glob, Bash

/ad-spec

Drafts doc/specs/<NNNN>-<short-slug>.md for one feature. Status lifecycle: draft → accepted → shipped | superseded by SPEC-NNNN. Spec is the layer-4 artifact in the kit's six-layer stack — Constitution (AGENTS.md + WORKFLOW.md) → Domain (CONTEXT.md) → Product (doc/product/PRD.md) → Spec (this skill) → Plan/Decisions (ARCHITECTURE.md + doc/adr/ + doc/tasks/) → Code. Multiple tasks implement one spec; ADRs may be driven by spec constraints. The Domain layer (CONTEXT.md, ubiquitous language per Evans 2003) is the source of canonical nouns the spec must use; if the spec introduces a new noun, resolve it through CONTEXT.md first. The Product layer (PRD.md) is the source of target user, product-level success metrics, and cross-feature constraints the spec inherits from; a feature spec whose target user or success metric contradicts the PRD is drift that ad-audit flags.

Step 1 — Determine NNNN and slug

List doc/specs/. NNNN = next available 4-digit number after the highest existing (mirrors the ADR and task conventions). If doc/specs/ does not exist, create it; start at 0001. Slug: kebab-case, ≤6 words, derived from the feature title.

Step 2 — Confirm scope

The spec captures one feature. If the user's request implies multiple features, ask which one to write first; the others become follow-up specs. A "feature" here is the smallest user-visible outcome that has its own success criteria — not a task (work unit) and not a binding architectural decision (ADR).

Step 3 — Interview to fill

Ask one question per missing field, in this order. Skip the philosophical questions and the questions whose answers are already obvious from the conversation.

• Context: business context first. Why the feature exists, the user / constraint / problem it addresses, the cost of not building it.
• User Scenarios: Given-When-Then for the key flows. Each scenario must be independently testable. Multiple scenarios when the feature has more than one path.
• Functional Requirements: testable statements. Plain bullets (no checkbox — Spec is decision-record, not tracking; implementation tracking lives in per-Spec tasks). "User can sign in with email and password" — yes. "Authentication should be secure" — no, that's not a requirement, it's a hope.
• Non-functional Requirements: performance, security, accessibility, observability — only the constraints that bind. Plain bullets. Skip when there are none.
• Success Criteria: measurable per WORKFLOW.md §1. Plain bullets — pass/fail must be observable, not aspirational. "Loads in under 2 seconds at p95 over 7 days" — yes. "Loads fast" — no. Per-criterion progress tracking lives in tasks; the Spec carries the criteria definitions and a single Status: field per ADR-0030 §1.
• Edge Cases: empty inputs, large inputs, concurrent access, missing prerequisites, permission errors. Surface them before code is written, not after a bug report.
• Out of Scope: explicit non-goals. Anything readers might assume is in scope but isn't. Prevents scope creep without an audit trail.
• Open Questions: deferred decisions. Each becomes a follow-up ADR or an explicit punt with a rationale.
• Related: ADRs touched by this spec, tasks implementing it (filled lazily as tasks are created), other specs this one supersedes or depends on.

Status starts at draft. Created: today, ISO format. Owner: ask. Do not invent values — when the user does not know, leave <TODO> and ask.

Interview UX

When the host exposes AskUserQuestion, use it for multi-choice prompts (Status: draft / accepted / shipped, owner selection from team members, scope-vs-multiple-features confirmation) and for confirmation gates with non-trivial branching. Inline text questions are an acceptable fallback only when the host lacks a structured-prompt primitive (Codex). One question per gate; do not chain three text questions when one AskUserQuestion card lists the options.

Step 4 — Write the file

Path: doc/specs/<NNNN>-<short-slug>.md. Use the template below.

Stop after writing. Do not flip status to accepted — that requires user review.

Step 5 — Editing guidance for later turns

When the user later works on the spec, edit the file by:

• Appending to Open Questions (close them with the resolution; never delete them).
• Flipping Status to accepted once the user signs off and tasks start being created.
• Flipping Status to shipped after release — once all per-Spec tasks complete.
• Flipping Status to superseded by SPEC-NNNN when a later spec replaces this one.
• Adding Tasks entries to Related as tasks are created against this spec.

Implementation tracking (per-criterion progress) lives in the per-Spec tasks, not in the Spec itself. The Spec is the contract; tasks track its construction.

Never rewrite existing prose — append rationale to Open Questions as a resolution paragraph rather than mutating the original requirement text.

Template — doc/specs/NNNN-<slug>.md

# Spec `<NNNN>`: `<short imperative title>`

**Status:** `<draft | accepted | shipped | superseded by SPEC-NNNN>`
**Created:** `<YYYY-MM-DD>`
**Owner:** `<name or role>`

## Context

`<Why this feature exists. The user, the constraint, the problem. What would break if this feature did not ship.>`

## User Scenarios

`<Given-When-Then for the key flows. Each scenario independently testable.>`

- **Scenario 1:** `<short title>`
  - Given `<starting state>`
  - When `<action>`
  - Then `<observable outcome>`

## Requirements

### Functional

- `<R1: testable statement>`
- `<R2>`

### Non-functional

- `<perf / security / a11y / observability — only when binding>`

## Success Criteria

Definitional. Measurable conditions; pass/fail observable, not aspirational. Per-criterion progress tracking lives in per-Spec tasks, not here.

- `<criterion 1: measurable, observable>`
- `<criterion 2>`

## Edge Cases

- `<empty input behavior>`
- `<large input / failure modes>`
- `<permission / concurrency / state-restoration cases>`

## Out of Scope

`<Explicit non-goals. Anything readers might assume is in scope but isn't.>`

## Open Questions

`<Deferred decisions. Each becomes an ADR or a documented punt.>`

## Related

- ADRs: `<list with links — written as the spec is accepted>`
- Tasks: `<doc/tasks/NNNN-... — appended as tasks are created>`
- Supersedes / Depends on: `<other spec links if any>`

Output contract

A single new file at doc/specs/<NNNN>-<short-slug>.md. Status draft. Tasks list empty (filled lazily as tasks land). No existing specs modified. No invented values.

The spec is a narrative document but is exempt from ADR-0008's no-dates rule for the same reason ADRs and tasks are: the Status lifecycle and Created field are part of the auditability primitive. The remaining documentation discipline rules apply at write time:

• No emoji anywhere in the file.
• Context is the business-context-first section — why the feature exists before what it does.
• One scope: one feature per spec. Multiple features implies multiple specs.
• No speculation. Open Questions go in their named section; everywhere else captures decisions.
• No commented-out requirements or TODO/FIXME — every deferred item references a tracked work item or lives under Open Questions.

Next

• /ad-ground for the four-source research pass before code (WORKFLOW §4 + §5).
• /ad-task to break the spec into work units; each task carries a Spec ref field pointing back to this file.
• /ad-adr if scoping the spec surfaced a binding architectural decision worth recording (one decision per ADR).
• Flip Status to accepted once you sign off and tasks start being created. Flip to shipped after release.