## Process

1. **Resolve the slug.** A raw idea with no existing folder → propose a number
   (next free roadmap slot) and a kebab-case slug; confirm before writing. An
   existing `NN-slug` → that folder's `SPEC.md` (create the folder + copy the
   template if the roadmap has the row but no folder yet).
2. **Interaction rule (fixed — no interpretation):**
   - **Bare `design-feature <slug>`** (existing SPEC/decisions found): print a
     summary of what the feature currently does (or would do, from a fresh
     idea) → ask what to add / remove / change. This doubles as review mode.
   - **`design-feature <slug> <instruction>`**: apply the instruction
     directly, no questions — touch only what the instruction implies. Still
     re-reads the existing SPEC/decisions first (upsert, never blind).
   - **Nothing exists yet** (brand-new idea, no prior SPEC): go straight to
     step 3 (interview), since there is nothing to review or upsert.
3. **Raw-idea interview (folded in, only when starting from zero or the
   instruction leaves genuine gaps).** Fixed protocol — structural, not
   judgement:
   - **One form-turn, then at most 2 follow-up turns.** The first interview
     turn is ONE compact form covering every rubric slot below plus the
     identity slots, each row carrying a recommended default the user accepts
     with one word (or edits in place). Ask nothing the docs or the instruction
     already answer. Genuine ambiguity the form cannot resolve gets at most
     **2 follow-up turns** — never a third ask.
   - **Vagueness rubric (fixed slots — the form rows ARE this list).**
     Probe each slot until it is filled or explicitly `n/a: <reason>`:
     1. **Affected users/roles** — who uses it; who must not.
     2. **Error & edge states** — what happens on failure / empty / invalid.
     3. **Data shape** — what is stored and shown, roughly.
     4. **Boundaries & limits** — sizes, counts, rates, thresholds.
     5. **Out of scope** — what this deliberately does NOT do.
     6. **Success criteria** — how we verify it worked.
   - **Mandatory-question rule.** A stated requirement that has no verifiable
     acceptance criterion yet is automatically the next question — no
     requirement enters the SPEC without one.
   - **Reframe, don't interrogate.** Restate each vague requirement as
     measurable criteria ("fast" → "list renders < 200 ms at 1k rows") and
     ask: "are these the right targets?" — a yes converts directly into
     acceptance criteria.
   - **Deferred decisions.** An answer of "decide later" is recorded as a row
     in the SPEC's `### Deferred decisions` (with a decide-by trigger) —
     never dropped, never silently guessed.
   - **Escalation (structural).** If, after the interview, **≥ 3 rubric slots
     remain empty** (neither filled nor `n/a`), do not guess: end the turn
     `NEEDS_INPUT`, listing the empty slots verbatim as the pending
     questions — the feature is not designable yet. Ambiguity that survives the
     follow-up budget escalates the same way (`interview:ambiguity-cap`): the
     2-turn cap never licenses a third ask.
   - The identity questions ride the same form-turn: problem & goal, business
     goals, size estimate (`XS/S/M/L` — XS/S stays SPEC-only, M/L gets the
     full artifact set), non-goals / future work, traceability (offer a
     tracking issue; if created, the eventual PR will `Closes #n`).
4. **Proportional research.** Capability closure (step 5) is cheap and comes
   first. Reach for external or domain research **only** when the feature
   touches a domain genuinely new to the project (a regulation, an unfamiliar
   integration, an industry convention with no precedent in the codebase) —
   never as a systematic per-feature step.

## Turn contract — design closure boxes

```text
✓ Product half written with every capability-closure row resolved (filled surface
  or explicit `n/a: <reason>`) — zero blank rows
✓ Spec-lint product boxes ticked, and `## Design status` set to what they prove
  (never optimistically); roadmap row never written past `defined` here
✓ Evidence rows: every material claim `proven`/`decision` at `current` freshness,
  or `unknown` naming its owner and the next evidence step
✓ `stage: spec` readiness block printed; the artifact is handed off only on
  `READY-FOR-REVIEW`
✓ `artifactRevisionId` rotated for the bytes just written and named in the
  closing block
✓ Repair turns: one batch over the whole open findings set, each finding's repair
  class recorded, no receipt text touched
```

## Portability (agents other than Claude Code)

The workflow is the contract; Claude Code features are conveniences. On an
agent that lacks one, apply the fallback — never skip the step the feature
enables:

- **No slash-command menu** — where this skill says `/<skill>`, open that
  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
  literally, in a fresh conversation: hand-offs assume a clean context.
- **No per-skill `model:`/`effort:`** — on the `#claude` branch the
  frontmatter pins these tiers; here, pick tiers yourself: capability closure
  is judgment work — run it on your **strongest** model available.
- **No `/loop`** — re-invoke this skill by hand when a review round or an
  instruction-mode revision is needed; follow the closing `→ Next:` block each
  time.

## Repair a reviewed Product half

Load this resource only when the unit's `progress.md` carries a
`SPEC-REVIEW-FAIL` or `NEEDS-DESIGN` receipt from `review-spec`, or when the user
asks to close such findings. This is the author's repair pass — the reviewer's
findings are input, never a to-do list to be renegotiated.

### 1. Take the whole findings set as one batch

Read every open finding of the newest spec-stage receipt plus every open finding
this unit previously recorded. Classify each by root cause
(`product | plan | source | environment | runtime`) before touching any file.

Then apply **one evidence-bounded repair batch** to the owning artifact(s) and
request one re-review of the new snapshot. Rules:

- Do not fix one finding, re-review, fix the next, re-review. Findings from one
  review are one batch, because the root cause is usually shared (an un-inventoried
  obligation, a role the matrix never listed, an "obvious" domain convention that
  skipped the expectation sweep).
- Do not split a batch because the findings landed in different files; a Product
  half and its `decisions.md` are one owning artifact set.
- Findings classified outside `product` are **not** repaired here: leave them
  open, name their owner (`review-plan`/`plan-feature` for plan defects, the
  executor for source defects), and say so in the repair note. Repairing a plan
  defect by editing the Product half is scope creep with extra steps.
- Never dismiss a finding by re-arguing with it: dismissal requires recorded
  counter-evidence that falsifies the claim (`pre-execution-review/references/POLICY.md`
  §2), written into the
  `planning-findings.md` row's resolution evidence, never into chat.

### 2. Three repair classes — pick one per finding and record which

| Class | Allowed when | Who acts | Evidence required |
|---|---|---|---|
| Mechanical, intent-preserving | wording, heading order, pointer format, a copy-paste slip in a row that already resolves correctly | this skill, autonomously | a dated `decisions.md` line: which finding ids, why intent is unchanged |
| Closure completion | a blank/`n/a`-less closure row, a missing sweep row, an unlabelled criterion, an unowned unknown | this skill, after acquiring the evidence | new/updated evidence rows at `current` freshness |
| Product change | scope, intent, role, authority, or user outcome actually changes | the human, through this skill's interview | a dated SPEC `## Amendments` row or `Product decisions` entry quoting the user's decision |

The first two stay autonomous **only while reviewed product intent is
unchanged**. If the repair would add, remove, or redirect scope, it is the third
class: stop and ask, one bounded question at a time. The reviewer proved a gap
exists; it never chose how to fill it, and neither does this skill.

### 3. New revision, new review

1. Apply the batch to the Product half and, when a decision was made, to
   `decisions.md` (append, dated — never rewrite a prior decision).
2. Re-run the Spec-lint product boxes and the `stage: spec` readiness preflight;
   paste both results.
3. Mint a **new** `artifactRevisionId` — mandatory even when the bytes came back
   to a previous state. A revert is an authoring event; reusing the old id is how
   a stale PASS gets resurrected.
4. Hand off to `/review-spec <slug>` for a re-review of the new snapshot. Never
   self-certify the repair, never reuse the reviewer's verdict for the new bytes.

### 4. Second cycle = anomaly, not routine

Cycle rules have one owner: `pre-execution-review/references/POLICY.md` §4 — a repeat needs a changed
snapshot or a named falsifiable question plus a new evidence route, and entering
a second repair/re-review cycle prints the `CONVERGENCE-ANOMALY` block (repeated
and new finding ids, the snapshots that moved, the evidence or obligation missed,
the owning stage, and why the prior readiness/review/repair failed) **before** any
further edit, then routes to that owner. More cycles stay allowed when
correctness needs them; they never earn a PASS, and an exhausted cycle budget
does not downgrade an open finding.

A repair responding to a persisted verdict is **never** a loop defect (POLICY §4
scopes every guard to blind re-reviews): a unit whose `progress.md` carries an open
FAIL/NEEDS-DESIGN receipt is being repaired by definition, so no "already complete"
answer exists for it and no cycle cap converts its verdict into a dead end.

The spec-stage detail this skill adds: the owning stage of a Product-half miss is
`product` unless the evidence proves the plan asked for something the SPEC never
said — then it is `plan`, and it leaves this skill for `plan-feature`.

### 5. Guardrails

- Never edit `SPEC-REVIEW-PASS` text, a receipt block, or a finding's severity to
  make a gate pass. Receipts are the reviewer's output.
- Never create a forge issue to hold a current-unit obligation so this batch looks
  closed (descope guard). Amending scope requires the human's dated amendment
  first, an issue second, never the reverse.
- Never widen scope while "already in the file": new obligations re-enter the
  inventory pass with a dated note.
- Upsert rules still apply: append, date, and preserve recorded decisions.

## Interaction & upsert (worked shape)

```
design-feature <slug>                → print summary → ask what to add/remove/change
design-feature <slug> "<instruction>" → apply directly, no questions, scoped to the instruction
design-feature "<new idea>"           → interview from zero (no prior SPEC to review)
design-feature <slug> "delete and redesign, <new direction>" → the only from-zero reset path
```

## Closure, write, and upsert

0. **Inventory before drafting** (the `evidence-grounding` passes, Product stage).
   List every normative obligation, affected role/use case, failure state,
   compatibility boundary, recorded decision, and material unknown, then acquire
   one evidence row per material claim
   (`claim-or-obligation | authority-kind | source-and-location |
   observed-revision | freshness | status | owner-or-next-evidence`). Product
   conclusions freeze in the SPEC's Product half and `decisions.md`. A claim you
   cannot evidence stays `status: unknown` with an owner — it never becomes a
   plausible rationale. A repeated read that answers no new question is
   no-progress: stop and report the missing evidence.

5. **Capability closure (the core).** Walk the SPEC template's **three fixed
   checklists** (`docs/features/_TEMPLATE/SPEC.md` → `### Capability closure`
   is the authoritative block — instantiate it, never paraphrase it) and write
   the result into the SPEC's `### Capability closure` section. Every row
   resolves to a filled surface **or** an explicit `n/a: <reason>` — a blank
   row is not a valid state, it is an unfinished design:
   1. **Entity closure** — for every entity the feature introduces or
      touches: Create/Read/Update/Delete/state-transitions, each with UI
      entry point + API surface + test.
   2. **Integration closure** — reconcile the feature against **every**
      subsystem in the capability inventory (`docs/CAPABILITIES.md`), one row
      per subsystem, none skipped: how does this feature touch auth, ACL,
      navigation, notifications, search, audit, settings, …? ("blog" ⇒ ACL
      gets a `blog:write` permission; the dashboard gets an "Articles" link
      with drafts above published and a "New article" button; auth is
      required to write.) **No inventory file** → derive the inventory from
      the architecture doc + codebase, record it in the section, walk it, and
      offer to seed `docs/CAPABILITIES.md` from the template (upsert-safe,
      user confirms).
   3. **Role matrix** — for every capability, EVERY role in the inventory is
      explicitly `allowed` or `denied` — no role unlisted, no "admins
      obviously can" left implicit.

   The filled rows **become the Acceptance criteria** — copy each resolved row
   (or its `n/a` line) into `## Acceptance criteria` as an objective, checkable
   condition. Do not restate them loosely; the checklist row *is* the
   criterion.
6. **Expectation sweep (the implicit-knowledge gate).** Enumerate **≥ 10
   candidate expectations** (M/L; **≥ 5** for XS/S) a competent human would
   assume ship with a feature of this kind without being told — domain
   conventions, not project specifics ("a blog has drafts and a publish
   action", "a list has an empty state", "a delete asks for confirmation").
   Fill the SPEC's `### Expectation sweep` table: each row resolves to exactly
   one of `in-scope` (add/point to an acceptance criterion), `out-of-scope`
   (add to *Out of scope / non-goals*), or `deferred` (row in *Deferred
   decisions*) — **never left unmentioned**. Rows the user rejects are
   recorded as out-of-scope, not dropped: a rejected expectation is a future
   surprise defused. When a resolution genuinely needs the user's call, it
   rides the step-3 interview protocol (one question per turn, recommended
   default).
7. **Scale-down for XS features.** The gate stays uniform — every closure row
   and inventory subsystem is still walked, the sweep still runs (≥ 5 rows) —
   but for a small feature most rows resolve to `n/a: out of scope for this
   slice` in one pass, and the interview (step 3) may be a single confirming
   question. Passing the gate is cheap; the gate itself never opens.
9. **Per-feature tooling notes.** Check which installed skills/MCPs are
   relevant to *this* feature (e.g. a payments MCP for a billing feature) and
   record them in `## Tooling`. This is not a global discovery sweep — that is
   `product-audit`'s job; record only what this feature will actually use.
10. **Write the Product half.** Fill `Context`, `Business goals`, `Scope`
   (in/out), `Capability closure`, `Acceptance criteria`, `Tooling`,
   `Product decisions`, and `Deferred decisions` (`none` if empty) in the
   SPEC. When instantiating the closure, **replace** the template's fenced
   example block with the filled rows (keeping it fails the spec-lint's
   placeholder box). Record every non-obvious call in `Product decisions`
   with its rationale, and log any residual unknown as an open question in
   `decisions.md` rather than guessing.
11. **Run the Spec-lint product boxes, then stamp.** Mechanically check the
   SPEC template's `### Spec-lint` **product boxes**
   (`docs/features/_TEMPLATE/SPEC.md`) and paste the box results. All
   product boxes tick → set the marker to `designed` **and**
   set this feature's `docs/features/ROADMAP.md` row status to `defined` (the
   `idea → defined` transition this skill owns — see the roadmap's Status
   legend). If the row doesn't exist yet (brand-new feature, no prior `idea`
   row), add it first at `idea` (number, slug, dependencies), then promote it
   to `defined` in the same edit — no feature is ever registered directly at
   `defined` without passing through `idea`. Any spec-lint product box FAILing
   (a blank closure row, an unlabelled prose criterion, an in-scope item with
   no criterion, …), or an unresolved question blocking closure → leave
   `## Design status` at `not designed`, leave the roadmap row at `idea` (or
   unadded), and end the turn with the failed boxes / pending question stated
   plainly instead of a false `designed` stamp or a premature `defined` write.
12. **Confirm the roadmap row.** The row from step 11 carries the right number,
    slug, dependencies, and status (`defined`). Beyond `defined`, status
    transitions (`planned`, `in-progress`, `done`) are `plan-feature-scaffold`'s
    and `execute-phase`'s job — this skill never writes past `defined`.
12b. **Readiness preflight, then rotate the revision.** Before handing off, run
    the `stage: spec` readiness boxes owned by the internal
    [`evidence-grounding`](<../../evidence-grounding/SKILL.md>) skill (its ordered
    passes route to its own readiness reference) and paste the fixed
    `READINESS — <NN-slug> spec <outcome>` block. Only
    `READY-FOR-REVIEW` may hand off; `NEEDS-EVIDENCE` / `NEEDS-DESIGN` /
    `NEEDS-REPLAN` keep the artifact at home with the named missing row. Readiness
    is an authoring gate: it licenses a review request, never a review verdict.
    Then mint the new `artifactRevisionId` for the bytes just written (every write
    rotates it — a revert included) and carry it in the handoff.
13. **Upsert semantics (never destroy).** Re-running on an existing slug
    re-reads the SPEC and `decisions.md` first; a revision **appends** to
    `decisions.md` (dated, with what changed and why) — it never rewrites or
    deletes a prior decision. The only path that starts the product half from
    zero is an explicit "delete and redesign" in the prompt; even then, record
    that reset itself in `decisions.md`. **This is the retrofit path
    `audit-pr`'s closure-integrity gate routes to:** a legacy SPEC with no
    `Capability closure` block trips that gate's dated `design-debt:
    closure absent, SPEC predates the rule` warning (never a blocker) on the
    next PR touching the feature; re-running `design-feature <slug>` there
    fills only the missing closure rows via this same upsert — it never
    rewrites what's already recorded.
14. **Hand off.** Once `designed` and readiness-clean, print the closing block
    (see *Done when*) recommending `/review-spec <slug>` with the current
    `artifactRevisionId`. Do **not** recommend `/plan-feature`: engineering
    planning is gated on an independent Product review this skill cannot supply.