/design-feature

name: design-feature
user-invocable: true
version: 3.4.0
argument-hint: <idea | NN-slug> [<instruction>]
author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Turn a raw idea or existing feature into a designed product SPEC by completing
  entity, integration, role, and expectation closure. Upserts never destroy
  recorded decisions. Triggers: "design-feature", "design this feature",
  "define product scope".

Design Feature

Product definition — the stage that turns an idea or a feature request into an exhaustive, checkable set of acceptance criteria, before any engineering planning happens. **Docs only — no code, no branch.**

Turn contract

Load and verify the **canonical** [Turn contract](.claude/skills/orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn. Design-specific closure boxes (product half, capability/role matrix, expectation sweep, upsert) live only in [INTERVIEW.md](references/INTERVIEW.md). Missing reference → STOP.

When to use

• A rough idea, no issue yet, and no SPEC: `design-feature "<idea>"`.
• An existing feature slug whose SPEC is not yet marked `designed`:

`design-feature <NN-slug>`.

• Revising an already-designed feature's product definition:

`design-feature <NN-slug> "<change>"` (instruction mode), or bare `design-feature <NN-slug>` for review mode (see *Interaction & upsert*).

• `plan-feature` redirects here when it detects an undesigned feature or a

product choice a `review-spec` `NEEDS-DESIGN` verdict returned to the human.

Step 0 — Discover the project (always first)

Per the agent guide's **Workflow conventions** + **documentation map**, then read what THIS skill needs: `docs/features/_TEMPLATE/SPEC.md` (the two-halves layout + `## Design status` marker), the roadmap (`docs/features/ROADMAP.md`), the **capability inventory** (`docs/CAPABILITIES.md` — the substrate the Integration closure walks; if the project has none, derive an ad-hoc inventory from the architecture doc + codebase during step 5 and offer to seed the file from the template), and — if the slug already has a folder — its existing `SPEC.md` and `decisions.md` in full (upsert never starts blind). Skim the architecture and domain docs relevant to the idea's area only far enough to ground capability closure in the project's real entities and roles — deep engineering research is the Engineering half's job, not this one.

Consume the internal [evidence-grounding](<../evidence-grounding/SKILL.md>) capability for the ordered passes and the readiness preflight: inventory → evidence → draft → cut → readiness. Its outcomes (`READY-FOR-REVIEW | NEEDS-EVIDENCE | NEEDS-DESIGN | NEEDS-REPLAN`) are an authoring gate, never an approval: only `review-spec` can approve a Product half.

Research gate (mandatory, fail-closed)

Before the Product half is emitted, run the research gate in the evidence pass (step 2 of the ordered passes):

• **Fetch the domain** — acquire **at least two externally fetched sources** on

the capability's domain (fetch/WebFetch/browser): how the domain defines and solves this capability. Repo evidence alone cannot ground a design; the bias this gate closes is designing from what the repository already believes. Each fetched source becomes an evidence row (URL and access date).

• **Cover the full definition** — the rows must state what the capability **is

and what it is not**, and the **user's expectation of it** — accepted and rejected inputs, boundaries, semantics — not just the project's current framing of it.

• **Decompose every enunciated expectation** — expand each expectation the

user enunciates into the implicit case decomposition it implies **before** the Product half is cut: valid and invalid values and limits, interaction states, degraded mode, backend validation/filtering/parsing, alternate user paths. The canonical case: a "phone number input" is not a field — it is the whole case vector (prefixes/suffixes, lengths, non-text rejection, focus, no-JS/JS behavior, backend filtering/validation/parsing) that the product owner's one-liner hides.

• **Fail closed** — offline, or a material question the fetches do not answer,

returns `NEEDS-EVIDENCE` with the named owner and next fetch: never a guess, never an invented citation.

• **Research before encode** — platform semantics a test will encode are

verified against authoritative documentation before the test exists (the prevention half of `verification-contract`'s test-immutability contract).

Progressive loading — resolve status before product detail

The reference allowlist is exactly the paths linked below. Never invent or read another `references/` path; in the DEFER column, bare names live in the same directory as the links.

**Hard stop for an incomplete raw-idea interview:** LOAD exactly `references/INTERVIEW.md` and no other reference. Present its ONE compact form-turn — the ≤ 6 fixed rubric slots plus the identity rows, each carrying a recommended default the user can accept with one word — then return `NEEDS_INPUT` and end the turn when slots remain unresolved; genuine ambiguity gets at most **2 follow-up turns**, never a third ask. `WRITE_AND_UPSERT.md` is forbidden until every mandatory interview slot is resolved; that resource then owns closure rows and writing.

| Condition now | LOAD now | DEFER / SKIP now | |---|---|---| | Bare existing slug, no instruction | [interview](references/INTERVIEW.md) through its interaction rule; report status and stop | `WRITE_AND_UPSERT.md`, `UPSERT_EXAMPLE.md`, `REPAIR.md`, `PORTABILITY.md` | | Brand-new idea with any mandatory interview slot unresolved | [interview](references/INTERVIEW.md) only; present exactly one form-turn (≤ 6 slots + identity, each with a default) and stop | `WRITE_AND_UPSERT.md`, `UPSERT_EXAMPLE.md`, `REPAIR.md`, `PORTABILITY.md` | | New idea after every mandatory interview slot resolves | [interview](references/INTE