/define

name: define
description: >
  Phase 0 of AI Closed-Loop Programming — Definition: engineers the WHAT the
  loop converges on. Writes and evolves the FSD — atomic, falsifiable,
  provenance-tagged requirements each carrying its verification contract —
  plus architecture, data model, interface definitions, state models,
  configuration catalogues, and a security profile; installs the three
  documentation planes (FSD / Method / UserDocumentation). Works for embedded,
  cloud, mobile, networking, and SDR projects. Use this skill whenever the
  user mentions an FSD, functional spec, requirements, a spec delta or
  amendment, the three planes, a runbook or handbook — even if they never say
  "FSD". Exit gate: Load defined. Test design, the test plan, audit and
  reconcile live in /build, not here.

Define — Phase 0 (FSD skill)

Creates and maintains the **WHAT**: what the system must do, stated so that compliance can be demonstrated. Every approved Must/Should carries a **verification contract** — the requirement and its proof are co-engineered, because attempting the contract *is* the quality gate: a requirement whose stimulus cannot be stated is not finished.

**Interface with the loop:** contracts flow down — `/build` consumes them, never edits them. Spec-defect findings flow up — when a declaration or an executable test proves a contract unsatisfiable, `/build` reports and this skill amends. A change request's Definition delta lands here (`/build` → `../build/references/change-request.md`).

0. Scope — what this skill does and does not do

**Three things it must never do**: claim a requirement is verified because code or a test merely exists; turn a recommendation into an approved requirement silently; invent a normative threshold, tolerance, security assumption, or failure behaviour.

| Activity | This skill | `/build` (Method) | Dev skills | Testbench skills | |---|:--:|:--:|:--:|:--:| | Define scope, requirements, states, interfaces | Yes | No | No | No | | Write verification contracts | Yes | Consumes | No | No | | Architecture decisions | Yes (records) | No | May propose | No | | Design and declare tests, own the plan | No | Yes | No | No | | Generate firmware and executable tests | No | Dispatches | Yes | Support | | Execute tests, capture evidence | No | Sequences | Processes | Captures | | Decide unresolved product questions | No | No | No | No |

**GitHub is the system of record.** The FSD, the plan, tests, and evidence are version-controlled artefacts; chat history is not authoritative. If the project has no repository, create it as the first act — `git init`, the §10 skeleton, an initial commit — and commit each artefact as it is finished. An untracked Method plane is unshared and therefore undocumented.

1. Scale and reach

Depth scales to inferred complexity. The core is domain-neutral — embedded, networking, SDR, IoT, cloud, mobile, hybrid — with optional packs (§14).

2. Invocation

**The path to a new FSD is three steps**: sketch the rough idea → `/grill-me` (shipped in this repo) until the design tree is resolved → this skill writes it up. `/harness` sequences this as the journey's Phase 0 when a project starts from nothing.

Grilling sits outside this skill because the person being interviewed is the right judge of when it is done. Step 2 must end with the decisions **absorbed into the planes** — a decision living only in a transcript is re-assumed next session, and there is **no decisions file**: a settled decision leaves its *effect* as present-state content in the plane it governs (a rejected alternative that is load-bearing becomes a stated negative requirement; mere preferences leave no residue and may be legitimately re-decided when the environment changes).

Four modes. Pick by what already exists and what the user is asking for.

| Mode | Invoke | Use when | |------|--------|----------| | **create** | `/define` + description | No FSD yet. **Harvest first** (§4), then ask only what is still open — 1–3 questions per round — and generate. | | **update** | `/define update <path>` + delta | An FSD exists. Apply the delta surgically — never regenerate the whole file, never renumber a stable ID. Change-request deltas land here. | | **grill** | `/define --grill` + description | **Cold start only** — no prior conversation, a brief too thin to infer architecture from. One question at a time, depth-first, each with a recommended answer. | | **planes** | `/define --planes [path]` | Write the Method and UserDocumentation planes, or retrofit an existing doc set into the three planes. Preview the move plan and get confirmation **before** moving anything. |

Test design, audit, and reconcile are `/build` modes — the loop's, not the spec's.

One rule holds across every mode: **never renumber a stable ID.** Obsolete items are `deprecated` or `superseded`, never deleted. A value this skill proposed stays `status: proposed` until accepted (`references/requirement-quality.md` §2).

Per-mode steps, the `update` search order, and grill discipline: `references/authoring.md`.

3. Tools

Use **Edit** rather than **Write** in `update` mode so unaffected chapters stay byte-identical, and **AskUserQuestion** for clarifications so each one carries its recommended answer.

4. Clarifying questions

**Harvest before asking.** Look in order: decisions settled earlier in the conversation (a `/grill-me` session), a prior FSD, then the repo itself — config files, protocol usage, `README.md`, `CLAUDE.md`. Tag each harvested decision `[user]` so it is never mistaken for something the skill assumed. Re-asking an answered question earns a shorter answer the second time.

Then ask only when what is *still* missing affects architecture, protocol choice, interface definition, safety or regulatory constraints, phase decomposition, platform, or an external integration. Everything else is inferred and marked `(assumed)`.

**Every question carries a recommended answer.**

(The two unh