Spec

---
description: >
  Product specification — problem, acceptance criteria, boundaries.
  Lean by default; rigor preserved. AC is the canonical contract id.
    /spec            — auto-detect (discover if problem unclear; define otherwise)
    /spec discover   — force problem-space exploration
    /spec define     — problem understood, need structured requirements
---

# Spec

Define **what** to build and **why**, before engineering decides **how**.
One gate, streamed output, rigor preserved.

**This is read-only. No code changes.** For task breakdown into sequenced
work, use `/decompose`.

> Follows `rules/integrity.md` — evidence-based, state assumptions (I8),
> neutrality check (I9), forward-looking durability (I10), question inherited
> rules (I11). Shared formatting + Visual Emphasis in `skills/shared/formatting.md`
> (use **bold** for key terms, tables over prose for comparisons, `> ▸`
> blockquotes for gates, ASCII diagrams for layout changes).

---

## When to use

| Signal | Mode |
|--------|------|
| New idea, problem space unclear | `/spec` or `/spec discover` |
| User research exists, needs structuring | `/spec discover` |
| Problem understood, need structured ACs | `/spec define` |
| Existing PRD needs tightening | `/spec define` |
| Translating stakeholder request into actionable spec | `/spec` (auto) |
| Large goal that won't fit one `/eng` cycle | `/decompose` instead |

---

## Complexity routing

| Complexity | Signal | Behavior |
|---|---|---|
| **Small** | ≤3 ACs, clear problem | One response. 1 gate (final). |
| **Medium** | 3–8 ACs, known domain | Stream continuously. 1 gate (final — recommendation is expandable). |
| **Large** | Unclear problem, new domain, 8+ ACs | Stream with cascade-risk awareness. 1 gate (final). |

**Escape hatch:** the user says "show full" or "just dump it" → collapse to one
response, one gate.

---

## Before you start

- Read **Project Profile** in consumer `CLAUDE.md` (stack, architecture, constraints).
- Scan `.retro/` for relevant prior learnings — flag recurring user-facing issues as known context.
- Scan `specs/` if present — existing capability specs are the source of truth; modifications produce **delta specs** (see §Spec Registry).
- Read `CLAUDE.md`, `TODOS.md`, `docs/` if relevant to scope.
- Build the **Impact Map** (`skills/shared/impact-map.md`) — grounded files, existing utilities, missing capabilities. This is where guessing is shifted upstream.

---

## Output structure — Option A inverted pyramid

`/spec` follows the **Inverted-Pyramid Output** pattern defined in
`skills/shared/formatting.md`. Read that section once; the rules below specify
only `/spec`-specific bindings.

### Progress block

```
/spec ════════════════════════════════════════════════════════════════════════════════

  ▸ Phase 1  Scope
  ○ Phase 2  Spec

══════════════════════════════════════════════════════════════════════════════════════
```

No inline title. The skill name + phase block are the header; the topic
appears inside `★ THE OVERVIEW` below in plain English.

For Small complexity (1 gate): collapse all phases to a single `▸ Spec
(streaming)` marker.

---

## Flow

### Phase 1 · Scope (internal reasoning, no visible output yet)

Build the Impact Map per `skills/shared/impact-map.md`. **Reason fully but
don't emit yet** — the map is held in scratch context for on-demand expansion
(see §2b). Phase 1 closes with a single-line transition
`✓ Phase 1   ▸ Phase 2  Spec`.

### Phase 2 · Spec — emit header, ACs, boundaries, then single gate

Phase 2 combines the recommendation header with acceptance criteria and
boundaries into a single decision surface. The reader sees the full picture
before deciding. Receipts (file tree, problem block, per-Q rationale) are
reasoned through but **not emitted by default** — they expand only when the
user asks (§2b).

#### 2a · Inverted-pyramid header (must-read summary)

```
▎ ★ THE OVERVIEW
▎
▎ {2–4 plain-English lines on what's being built. Drawn from
▎ PROBLEM·Need + the recommended approach. The reader who only
▎ reads this block should know what they're approving.}

▎ ⚠ HEADLINE RISKS
▎
▎ • {plain-language risk, drawn from Impact Map · Risks}
▎ • {plain-language risk}
▎ • {2–4 bullets max — surface the most material; rest live in receipts}

▎ ✎ {N} QUESTIONS BEFORE LOCK
▎
▎ Q1  {plain-language question, ≤60 chars}     →  {recommended answer}
▎ Q2  {plain-language question}                  →  {recommended answer}
▎ ...

```

Heading rule: use `{N} QUESTIONS BEFORE LOCK` (e.g., `5 QUESTIONS BEFORE
LOCK`) so the reader knows the count without scanning.

If there are no open questions, drop the `✎` block entirely.

#### 2b · Receipts — on-demand, not inline

Receipts (file tree, problem & boundaries, per-question rationale) are
**reasoned through but not emitted by default.** Phase 2's chat output ends
at the gate prompt — the four `▎` blocks plus 2-line gate, ~30 lines total.
The reader who trusts the recommendation replies "go" without scrolling past
extra material; the reader who wants to verify expands on demand.

The gate prompt names the available expansions so the affordance is
discoverable. **Expansion vocabulary:**

| User reply | Expansion |
|---|---|
| `why Q{n}` or `Q{n}?` | Per-question rationale for that one Q only (2–4 lines) |
| `file tree` | Boxed Impact Map per `skills/shared/impact-map.md` |
| `problem` (or `problem & boundaries`) | Problem · Assumptions · Constraints · before/after diagram if applicable |
| `receipts` | All three — file tree, problem block, every Q's rationale |
| Override (e.g. `Q2: overlay`) | Treat as gate decision; expand the affected Q's rationale only if user follows up with "why?" |
| `go` | Approve all — proceed to Phase 3, no receipts emit |

**Internal reasoning is unchanged.** The Impact Map, problem block, and per-Q
rationale must all be fully reasoned before emitting `★ THE OVERVIEW`. They are
held in scratch context and surfaced only when asked. The recommendation,
risks, and question answers in the `▎` blocks must be defensible against the held
content — emitting on demand should not require new reasoning.

**Why on-demand, not inline:** receipts duplicate what eventually goes into
the durable spec at `specs/<slug>.md`. Inline emission rendered ~120 extra
lines per gate that most readers skipped past. On-demand keeps the four
blocks + gate as the entire visible decision surface (~30 lines) while
preserving the right to verify. Persistence beyond the session lives in
`specs/`, not in chat scrollback.

#### 2c · Receipts — content rules (when expanded)

When the user requests expansion, the content follows these rules. Same
rigor as before, just deferred emission.

**File tree** — render per `skills/shared/impact-map.md` (boxed form, `├──
└──` connectors, `★` marker on the single primary rework target, status tags
in `[brackets]`).

**Problem & Boundaries** — emit as a key-value block:

```
  PROBLEM
    Need      {plain-English what they need to do}
    Friction  {plain-English today's pain}
    Success   {observable outcome that signals "solved"}

  ASSUMPTIONS
    • {premise} — {plain why it holds}

  CONSTRAINTS
    • {hard limit}
```

**Drop `Who` from PROBLEM by default.** Audience is implicit; surface `Who`
only when the spec changes who it serves (segment shift). When surfaced, add
it as a fourth row above `Need`.

If the spec affects layout, architecture, or visual flow, append a small
ASCII before/after diagram after the Problem block.

Surface `EVIDENCE` (user research / data) under the same expansion when it
carries signal — narrative, not a matrix.

**Per-question rationale** — for `why Q{n}`, emit only that one Q. For
`receipts` (all), emit every Q. Format unchanged:

```
  Q{n}  {2–4 lines, hard-wrapped at ~70 chars, plain English — what makes
        this the right answer; what trade-off we're accepting; what we'd
        do instead if circumstances were different}
```

#### Internal reasoning (do NOT output)

Reason through these before writing `★ THE OVERVIEW`:
- What problem are we solving? (specific, observable — not a solution)
- Who has this problem, and what's the cost of not solving it?
- How do they solve it today? (workarounds, competing products, manual)
- How will we know it's solved? (observable outcome, not feature list)
- User research available? Weave findings into THE OVERVIEW. Not? State
  assumptions inline.
- Feasibility given Project Profile?
- Known risks or dependencies?
- **Interaction modality** — does any planned flow depend on sight, motor
  precision, color, or hover/gesture without an alternative? If yes, surface
  in CONSTRAINTS or QUESTIONS — `/eng` will gate on it.

This reasoning produces the content for `★ THE OVERVIEW`, `⚠ HEADLINE RISKS`,
`✎ QUESTIONS`, and the held problem block (expanded on demand per §2b/§2c).
Reason once; emit only what's asked for.

#### `/spec define` mode

When the problem is already well-understood (e.g., existing PRD), `★ THE OVERVIEW`
states the recommended approach directly without re-deriving the problem.
The held problem block still gets reasoned (durable record, surfaced into
`specs/` after the gate); it just doesn't render in chat unless asked.

#### Open questions — abbreviated in header, rationale on demand

In the `✎ QUESTIONS BEFORE LOCK` block above the gate, each question gets
**one line**:

```
Q1  {plain-language question, ≤60 chars}     →  {recommended answer}
```

This is the scan format — the reader sees what's being asked and what's
recommended at a glance. Rationale is held; emitted only when the user
replies `why Q{n}` or `receipts`.

When asked, each question expands to 2–4 hard-wrapped lines explaining
**why** the recommendation:

```
Q1  {rationale — what makes this the right answer; what trade-off
    we're accepting; what we'd do instead if circumstances were
    different}
```

**Question count rules:**
- 0 questions → drop the `✎` block; gate becomes "confirm or list concerns".
- 1–8 questions → emit one row per Q in header; rationale held, on-demand.
- 9+ questions → the spec is too large; recommend `/decompose` instead.

> Markdown tables stretch to the longest cell and bust terminal width when
> answers run long. The one-line `Qn  →` format is fixed-width by design.

#### 2d · Acceptance Criteria + Boundaries + Gate (single decision surface)

After the header blocks and on-demand receipts, Phase 2 silently reasons
about ACs, boundaries, and verification, then emits them inline before the
single gate. The reader sees recommendation + ACs + boundaries in one pass.

#### Internal reasoning (do NOT output)

**AC is the single contract id.** Each AC carries a one-line user-language
summary, a MoSCoW priority, and a Given/When/Then. Exhaustive test
variations belong in `/tdd`.

Apply this checklist before considering Phase 3 complete:
- For any UI feature: ACs MUST cover `happy`, `error`, `empty`, `loading`
  (state-completeness forcing function — known LLM failure mode otherwise).
- Edge cases — empty/invalid input, concurrency, external failure, permission
  edges, data-not-found, cross-cutting state. **Fold any user-facing edge into
  an AC.** Implementation-only edges belong in `/eng`.
- Interaction modality — if a flow needs sight/motor/color/hover with no
  alternative, raise it in BOUNDARIES · Constraint (don't bury it in an AC).

**AC rules:**
- **MUST / SHOULD / COULD** priority on every AC.
- Lead with the user-language summary, not the system-side requirement —
  "User can recover their account by email" beats "System sends reset link."
- One GWT per AC by default; add a second only if a single scenario can't
  capture the contract.
- Each AC independently deliverable. Describes user goal, not implementation.

**Boundaries** — track `Constraint`, `Security`, `Assumption`, `Out of scope`
as distinct kinds; surface each only if it carries signal. NFRs deviating
from project defaults go under Security or Constraint. Don't enumerate
defaults or restate obvious patterns.

**Verification** — every AC must have a GWT and be testable. Note any
exceptions (`AC-N  Testable=No — reason`) for surfacing in the gate.

#### Display sequence

Emit in this order after the header blocks: `══ Acceptance Criteria ══`
section, `══ Boundaries ══` section, then the gate `▎` block.

```
══════════════════════════════════════════════════════════════════════════════════════
  Acceptance Criteria
══════════════════════════════════════════════════════════════════════════════════════

  AC-1   MUST    {topic-tag}         — {one-line user-facing summary}
  AC-2   MUST    {topic-tag}         — {one-line user-facing summary}
  ...
  AC-N   COULD   {topic-tag}         — {one-line user-facing summary}

══════════════════════════════════════════════════════════════════════════════════════
  Boundaries
══════════════════════════════════════════════════════════════════════════════════════

  Constraints   · {one-line constraint}
                · {one-line constraint}
  Security      · {one-line security item}
  Assumptions   · {one-line assumption}
                · {one-line assumption}
  Out of scope  · {one-line out-of-scope item}
                · {one-line out-of-scope item}

▎ ▸ GATE — approve spec & run?
▎
▎ Problem:  {one-liner from THE OVERVIEW — ≤80 chars}
▎ Scope:    {S/M/L} · {N} ACs · {key boundary}
▎ Chain:    /spec → {/design (if UI) →} /eng → /tdd → /review → /ship
▎
▎ Principles (defaults in bold, override any with "P2: minimal"):
▎   P1  Scope       **balanced** — MUST + SHOULD ACs  |  strict — MUST only  |  expansive — all
▎   P2  Architecture **balanced** — good patterns      |  minimal — smallest diff  |  ideal — best arch
▎   P3  Risk        **moderate** — proceed on medium confidence  |  conservative — stop on ambiguity
▎   P4  Tests       **thorough** — all edge cases      |  essential — happy + error only
▎
▎ Reply "go" to accept defaults and run (lean output, auto-chain).
▎ Reply "go verbose" for full receipts and per-skill gates.
▎ Override: "P2: minimal, P3: conservative" or "AC-N: {revision}".
▎ Reply "write" to write the spec only — stop after.
▎ Escape: type "pause" at any time to halt after the current skill.
▎ After any skill: "receipts" to expand suppressed detail.
```

**Resolve `Chain:`** at emit time — include `/design` only if the feature
has UI/UX. The chain shows the user exactly what will run autonomously.

**Resolve `Scope:`** from the AC count and complexity assessment. Use
S (≤4 ACs, 1 module), M (5–8 ACs, 2–3 modules), L (9+ ACs, 4+ modules).

#### Acceptance Criteria — high-level inline format

One row per AC, fixed-width columns:

```
  AC-{n}  {priority}  {topic-tag}      — {summary}
```

- **AC id** — left-aligned to longest id width (`AC-1` through `AC-99`).
- **Priority** — `MUST` / `SHOULD` / `COULD`, padded to 6 chars.
- **Topic tag** — 2–3 words, lowercase, drawn from the AC's noun phrase.
  Examples: `drawer toggle`, `push/overlay`, `state persistence`,
  `feature flag`, `mobile sheet`. The tag is what the AC is *about*; the
  summary is what the user *does*.
- **Summary** — the one-line user-facing summary already reasoned above.
  Trim to fit terminal width (≤80 chars after the em-dash).
- Pad topic-tag column to align em-dashes vertically across all rows.

#### Boundaries — high-level inline format

Group by kind. Each kind gets a single label row, then `·`-bulleted entries
indented under it:

```
  {Kind}   · {one-line entry}
            · {one-line entry}
```

Pad the kind label column to a fixed width (`Constraints`, `Security`,
`Assumptions`, `Out of scope` — longest is 12 chars). Skip any kind with
zero entries — don't emit empty headers.

Lines stay ≤90 chars; truncate verbose constraint text (the full text lives
in the spec file).

#### Phase row formats

**Phase 2 row:**
- During gate prompt: `{N} ACs · {M} MUST · {K} SHOULD ·
  {L} COULD` — drop any priority with zero count.
- After write: `{N} ACs · written to specs/{capability-name}.md`.
- If verification has exceptions: append `· {X} testability gaps`.

#### Gate inner block — what to keep, what to drop

- **Keep** — `Problem` and `Next` (not visible elsewhere).
- **Drop** — `✓ SPEC · N ACs ·` count line (already in the progress block) and
  the `Boundaries: N constraints ...` count line (already shown by the
  Boundaries section above).
- The `▎` block becomes the gate prompt + brief context, not a summary card.

#### On-demand keywords at gate

Since high-level views emit by default, the keywords expand to **full detail**:

| Reply | Expands to |
|---|---|
| `ACs` | Full blockquote form for every AC, with GIVEN/WHEN/THEN clauses |
| `AC-{n}` or `AC-{n} full` | Full GWT clauses for that one AC |
| `boundaries` | Full text of each boundary (the high-level above is the truncated form) |
| `all` | Full ACs + full boundaries together |
| `why Q{n}` or `Q{n}?` | Per-question rationale for that one Q only (2–4 lines) |
| `file tree` | Boxed Impact Map per `skills/shared/impact-map.md` |
| `problem` (or `problem & boundaries`) | Problem · Assumptions · Constraints · before/after diagram if applicable |
| `receipts` | All — file tree, problem block, every Q's rationale |
| `go` | Write the spec file, re-emit the progress block, then immediately invoke the next skill (per the `Next:` line). No prompt between. |
| `write` | Write the spec file and stop. No chain. Use when the user wants to pause before the next skill. |
| Override (`AC-5: 50px strip`) | Apply, update Phase 3 row count if priority/total changed, re-render the AC row inline, prompt again |

#### Full-detail expansion (when user asks "ACs", "boundaries", or "all")

Emit inside `══` separators (matching the inline visual).

**Acceptance Criteria — use the blockquote form, never the wide table.**

```
══════════════════════════════════════════════════════════════════════════════════════
  Acceptance Criteria
══════════════════════════════════════════════════════════════════════════════════════

> **AC-1** · **MUST** · {one-line user-facing summary}
> - **GIVEN** {precondition}
> - **WHEN** {action}
> - **THEN** {expected outcome}

> **AC-2** · ...
```

The 6-column markdown table (`AC | P | Summary | Given | When | Then`)
**must not be used in chat** — column widths force every cell into multi-line
wraps and the table becomes unreadable. The table form is reserved for the
spec file (which renders in markdown viewers, not terminals); chat always
uses the blockquote form.

**Boundaries — two-column table fits at any width.**

```
══════════════════════════════════════════════════════════════════════════════════════
  Boundaries
══════════════════════════════════════════════════════════════════════════════════════

| Kind | Detail |
|------|--------|
| **Security** | rate-limit 5/hr/email; tokens 128-bit CSPRNG |
| **Constraint** | must use existing SendGrid — no new vendor |
| **Assumption** | users have email access — no SMS fallback |
| **Out of scope** | admin-initiated reset |
```

`all` emits both sections plus any verification exceptions.

#### After "go" — write, handoff, chain

Three actions in order, no pause between:

1. Write to `specs/{capability-name}.md` per §Spec Registry.
2. Emit the **handoff summary** (see §Handoff Summary) + re-emit the progress
   block with Phase 2 status updated to "written".
3. Immediately invoke the next skill resolved from the Next-step table —
   `/design`, `/eng`, `/research`, or `/decompose`.

```
/spec ════════════════════════════════════════════════════════════════════════════════

  ✓ Phase 1  Scope
  ✓ Phase 2  Spec — {N} ACs · written to specs/{capability-name}.md

══════════════════════════════════════════════════════════════════════════════════════

[handoff summary emits here — see §Handoff Summary]

[next skill's Phase 1 progress block emits here — no prose between]
```

**No prose between the handoff and the next skill's invocation.** No
"Spec written... has UI surface... let me start /design" sentence. The
progress block confirms the write; the handoff summary carries context;
the next skill's own output carries the visual transition.

#### After "write" — write only, stop

Same as `go` but skip step 3. Use when the user wants to pause before the
next skill (e.g. to review the spec file, switch context, or run something
else first). Output is just the re-emitted progress block.

---

## Spec Registry (appendix)

If the consumer repo has `specs/`, persist the spec to maintain the living
registry. If `specs/` doesn't exist, ask the user before creating it.

### New capability — write to `specs/{capability-name}.md`

```markdown
# {Capability Name}

> Last updated by /spec on {YYYY-MM-DD}
> Source: product-authored

## Acceptance Criteria

- **AC-1:** (MUST) {user-facing summary}
  - GIVEN {precondition} WHEN {action} THEN {outcome}
- **AC-2:** (SHOULD) {user-facing summary}
  - GIVEN {precondition} WHEN {action} THEN {outcome}

## Boundaries

- **Security:** {requirement}
- **Constraint:** {limit}
- **Assumption:** {premise}
- **Out of scope:** {item} — {reason}
```

### Modifying existing capability — write delta to `specs/deltas/{capability-name}-{YYYY-MM-DD}.md`

```markdown
# Delta: {Capability Name}

> Change: {one-line summary}
> Date: {YYYY-MM-DD}
> Modifies: specs/{capability-name}.md

## ADDED
- **AC-N:** (MUST/SHOULD) {user-facing summary}
  - GIVEN {precondition} WHEN {action} THEN {outcome}

## MODIFIED
- **AC-M:** (MUST/SHOULD) {user-facing summary}
  - Was: {previous behavior}
  - Now: {new behavior}
  - Reason: {why this changed}
  - GIVEN ... WHEN ... THEN ...

## REMOVED
- **AC-K:** {prior summary}
  - Reason: {why}
```

**Delta rules:**
- Include only sections with changes (omit empty ADDED/MODIFIED/REMOVED).
- Every MODIFIED needs Was/Now/Reason.
- Every REMOVED needs a reason.
- RFC 2119 keywords (MUST / SHOULD / MAY).
- AC numbering is append-only — never reuse an id, even after REMOVED.
- `/ship` merges deltas into the main spec during archival.

---

## Handoff Summary

After writing the spec, emit a compact handoff block. This is what the
downstream skill consumes — it does NOT re-read the full spec output from
conversation context. The spec file at `specs/{slug}.md` is the durable
record; the handoff is the working context.

```
HANDOFF → {next-skill}
  Problem:     {one-line from THE OVERVIEW}
  ACs:         AC-1 {MUST} {summary} · AC-2 {SHOULD} {summary} · ...
  Boundaries:  {key constraints, one line}
  Decisions:   Q1 → {answer} · Q2 → {answer}
  Principles:  P1={val} · P2={val} · P3={val} · P4={val}
  Spec file:   specs/{capability-name}.md
```

Rules:
- One line per field. ACs use `·`-separated compact form (no GWT — that's in the file).
- Decisions carry only the Q→answer pairs, not rationale.
- **Principles line:** include when user replied "go" or "go verbose".
  Omit when user replied "write". Downstream skills read `Principles:`
  for decision-making.
- **Verbose line:** include `Verbose: true` only when user replied
  "go verbose" (or legacy "go interactive"). Downstream skills check
  this flag — present means full receipts + gates, absent means lean.
- Total handoff: ≤10 lines. If ACs overflow one line, use 2 lines max.
- Downstream skills read the handoff, not the full conversation history.

---

## Next step

`/spec` chains automatically after the gate. The gate now serves as the
single decision point for the entire Feature recipe — one "go" approves the
spec AND authorizes the full downstream chain.

**User replies and their effects:**

| Reply | Spec written? | Chain behavior |
|---|---|---|
| `go` | Yes | **Lean mode (default).** Full chain runs with lean receipts, intermediate gates suppressed. Downstream skills read `Principles:` for decisions. |
| `go verbose` | Yes | **Verbose mode.** Chain runs with full receipts and per-skill gates. HANDOFF includes `Verbose: true`. Also accepts "go interactive" (legacy). |
| `write` | Yes | No chain. Output stops after spec write. |
| `P2: minimal` (etc.) | — | Override principle, then re-emit gate with updated defaults. |
| `AC-N: {revision}` | — | Apply AC revision, then re-emit gate. |

**Resolution table** (used to resolve the auto-chain target):

| Condition | Auto-chain target |
|---|---|
| Feature has UI/UX | `/hashb:design` |
| Pure backend / API / infra | `/hashb:eng` |
| Need library/API research first | `/hashb:research` |
| Goal too large for one `/eng` cycle | `/hashb:decompose` |

**Auto-chain semantics:**
- After write, emit HANDOFF block, then immediately invoke the auto-chain target.
- No prose between `/spec`'s post-write progress block and the next skill's
  Phase 1 emission.
- The downstream skill reads the HANDOFF block + the spec file as input.

**Escape hatches:**
- `write` — write spec without chaining.
- `pause` (during chain) — halt after the current skill completes,
  emit partial session summary.
- Auto-escalates on: spec challenge (tech impossibility),
  `/eng` swarm-eligible scope (8+ files or independent areas — always
  recommends `/swarm plan`), `/review` ESCALATE verdict, `/fix` 3-strike stop.

---

## Rules

| Rule | Why |
|------|-----|
| Read-only | No code changes. Writes `specs/` only on user approval. |
| Principles gate | Single gate after recommendation + ACs + boundaries. "go" authorizes spec write + lean auto-chain. "go verbose" enables full receipts and per-skill gates. See §2b, §2d, §Next step. |
| Two phases, one gate | Phase 1 silent (Scope), Phase 2 emits recommendation header + ACs + boundaries + gate + writes (Spec). |
| Handoff with principles | Emits HANDOFF block with `Principles:` line (always except "write"). Adds `Verbose: true` only on "go verbose". See §Handoff Summary. |
| Internal reasoning, signal-only output | Discovery questions, edge-case enumeration, verification checks all run internally. Output only what carries signal. |
| Plain English in prose | Use the simplest words a working engineer would use mid-task. Keep technical precision for code identifiers, file paths, CSS units, breakpoints, WCAG refs. See `skills/shared/formatting.md`. |
| Testable criteria only | Every AC must be verifiable. No "should be fast". |
| Problem before solution | Discovery defines the problem. Define structures the solution space. Neither prescribes implementation. |
| No implementation details | "System sends email" not "use SendGrid with retry queue." That's `/eng`'s job. |