spec

Two modes:

• Interactive (default) — a developer is present; resolve ambiguity by asking.
• Autonomous — no human can answer (orchestrated or workflow runs); active when the task says "AUTONOMOUS", "non-interactive", "use defaults", or "use your judgment". Resolve ambiguity with recorded defaults.

• Three ingredients, all required: requirements (what must be true), constraints (what the implementer may not do), verification (the command that proves it).
• EARS: one requirement, one trigger, one response, a single shall; pattern by behavior type — Ubiquitous, When, While, If/then (unwanted behavior only, carrying the exact user-facing response), Where, While+when — never When-only. No pronouns, no vague terms (fast, robust, properly, gracefully, appropriate, some, several) — use numbers, thresholds, or lists; one term per concept.
• Requirements and proofs name only what an outside observer sees: inputs, outputs, messages, stored results, timings. Constant names, file locations, modules, lock/batch mechanisms, which client is called are implementation — cut, or move to Guardrails when the repo forces it. file:line belongs in Current Behavior and Context only.
• Every FR (FR-001…) is proven at least once in Acceptance by the lightest form — Scenario (literal values), Property (prefer for rules over an input space), or Check (budgets, non-functional only) — and each proof rejects a plausible wrong implementation. Cover, for what the change touches: error path per happy path, empty/invalid/boundary per input, concurrent case per multi-actor flow, unavailable case per external dependency. Don't invent unreachable corners.
• Say each behavior once. A small change (≤3 FRs) is Overview, Requirements, Acceptance, Guardrails, Verification in about 300 words. Behavior that must not change is Property (invariant): … in Acceptance, or an Invariant in Guardrails.
• Guardrails are boundaries, not instructions: protected surfaces, forbidden moves, measurable budgets, invariants. A forbidden move that seems necessary is a stop-and-report. Never dictate process.
• Code appears only as behavioral evidence (input→output pair, payload shape, error body), ≤10 lines, tied to its requirement — no function bodies, algorithms, class design, or pseudocode.
• Interactive clarification: max 5 numbered questions per round, highest impact first, each multiple-choice (2–4 lettered options, recommended marked) or answerable in ≤5 words, grounded in findings. Never ask what exploration answered, or about mechanism (storage, scheduling, libraries, which component).
• Autonomous clarification: ask nothing; apply your recommended option and record it under Assumptions with its reason. No safe default → inline [NEEDS CLARIFICATION: ], reserved for scope, security, privacy, and data-integrity divergences; security, privacy, or data-loss defaults must be the more restrictive reading. A silent default is a defect.
• One spec is one mergeable outcome — one review sitting; split per the skill (different Done commands, independently shippable, different risk, tasks.md past ~10–15 items), large changes as a thin parent plus child specs.
• Bug, refactor/performance, and brownfield specs use the task-type sections in the skill's reference/spec-template.md (brownfield requirements tagged ADDED / MODIFIED / REMOVED).

# Specification: <name>
## Overview
## Current Behavior      *(changes to existing behavior only)*
## User Stories         *(features only)*
## Requirements         *(FR-001 [ADDED|MODIFIED|REMOVED]: <EARS statement>)*
## Acceptance           *(Scenario | Property | Check (FR-001): … — every FR proven, none twice)*
## Assumptions          *(autonomous mode or "you decide" answers)*
## Guardrails           *(protected surfaces, forbidden moves, budgets, invariants)*
## Out of Scope
## Open Questions       *(only if [NEEDS CLARIFICATION] markers remain)*
## Context              *(bullet list, then <context> with verified path:range lines)*
## Verification         *(the exact command, mapped to the FRs it proves)*
SPEC STATUS: READY

Context block: verified paths only, narrow ranges, max 10, most relevant first, each also listed above with a one-line why — downstream agents batch-read exactly these. Omit sections with nothing real to say.

The last line of spec.md and of every reply is exactly SPEC STATUS: READY or SPEC STATUS: NEEDS CLARIFICATION — the latter iff a [NEEDS CLARIFICATION] marker remains.

Interactive reply — a plain behavior summary so the user catches a wrong call before anyone builds:

What changes for <who>, from <when> (spec: `specs/<NNN>-<slug>/spec.md`). Reconfirm each line; (mine) marks a call I made that you did not confirm.

<User-visible area>
- <What a user sees or can do, with concrete numbers.> (mine)

Your setup before <date>        *(only when the user must act: keys, accounts, approvals)*
- <action>

Open questions                  *(only if any remain)*
SPEC STATUS: READY

• One group per user-visible area, one plain complete sentence per behavior, with concrete amounts, limits, durations, dates. A small spec is one group of 1–3 bullets.
• (mine) on every behavior from an applied default or your own judgment; user-confirmed behaviors carry no tag.
• FR/AC numbers, function names, paths other than spec.md, test commands, and internal mechanics stay in the file.