--- name: usdl-behaviour-usecase description: Element-targeted Skill that authors one USDL use-case Element in behavior.xml. Owns the use-case Interview Script that collects the actor reference, goal, preconditions, ordered main-flow steps, optional named alternative flows, postcondition, and one or more acceptance blocks (default format gherkin), plus the four optional collections (events, rules, invariants, nfrs) when the author indicates the use case interacts with them. Trigger this Skill when the active task mentions "use case", "use-case", "actor", "goal", "gherkin", "acceptance criteria", "main flow", "alternative flow", "preconditions", or "postconditions" in the context of authoring or extending behavior.xml. Not user-invocable directly; surfaced as a See-Also Reference from usdl:behaviour (and preloaded by top.agent.behaviour-author). Drafts XML matching templates/behavior/use-case.xml via usdl:templates and the parent skill then calls Bin through usdl:bin to validate. Carries no executable code. --- # usdl-behaviour-usecase ## What this Skill is This is the element-targeted Skill that authors **exactly one `` Element** for `behavior.xml`. It owns the use-case **Interview Script** (`term.interview-script`): the ordered sequence of questions an element-targeted Skill asks the Spec author to fill one Element kind. Its sole job is to gather every required Template slot, draft the Element from the use-case Template, and hand the draft to the parent skill for validation and writing. It is **not user-invocable directly**. It is surfaced as a **See-Also Reference** from `usdl:behaviour` (per `beh.rule.peer-skill-cross-reference`) and preloaded by `top.agent.behaviour-author`. The agent host loads it when `usdl:behaviour` recognises that a `` Element is about to be drafted. ## How it fits with peer Skills - **Parent (See-Also source):** `usdl:behaviour` — the section-spanning Skill. When the section interview reaches the "actors and use cases" step, `usdl:behaviour` names this Skill in its response so the host may load it. - **Template authority:** `usdl:templates` — owns `templates/behavior/use-case.xml` (the canonical use-case Template) and the Element-versus-Template conformance check. Every draft this Skill produces is validated against the Template before being written. - **Persistence and structural validation:** `usdl:bin` — wraps the `usdl` CLI. After this Skill emits a draft, the parent skill calls `usdl validate` through `usdl:bin` to confirm the Section file is structurally sound and references resolve. - **Peer Element Skills (informational only):** `usdl:behaviour:nfr`, `usdl:topology:services`, `usdl:topology:communication`, `usdl:interfaces:contracts`, `usdl:composition:skatchbook` are siblings; none are called by this Skill. Routing between Skills is the host's job. This Skill does not invoke peers. It surfaces information so the host can route, per `beh.rule.peer-skill-cross-reference`. ## Authoritative inputs Before asking a single question, the Skill loads: 1. `templates/behavior/use-case.xml` — the canonical use-case Template (via `usdl:templates`). Every required Template slot becomes a required interview question; every optional slot becomes an optional question (asked only after author signals interest). 2. The current `behavior.xml` (via the parent skill) — to detect id collisions on the new use case's id and to know which `actor.*` ids already exist. 3. The Behavior dictionary `` row and the quick-reference required-attributes table — already encoded in this script's required-slot list below. The Skill never asks for an attribute or child the Template does not declare, and never omits one the Template requires. ## The Interview Script (ordered) The Skill runs the questions below in order. **Required slots are asked unconditionally.** Optional slots are surfaced as offers ("Does this use case interact with any domain events, rules, invariants, or NFRs?") and asked only when the author signals interest. This implements `beh.rule.minimum-interview`. ### Required slots (asked unconditionally) 1. **`id`** — the use-case id. Kebab-case, unique across the entire Spec, prefixed `beh.`. Example question: "What kebab-case id should this use case carry? (We'll prefix `beh.` — e.g. `beh.book-flight`.)" 2. **`actor`** — the primary actor reference. **Must resolve** to an existing top-level `` id (prefixed `actor.`). If the Spec author names an actor that does not exist in `behavior.xml`, the Skill **pauses and tells the parent skill to add the `` first** before resuming; it does not fabricate one. Example question: "Which actor pursues this goal? (Must reference an existing actor id such as `actor.spec-author`. If the actor doesn't exist yet, we'll add it first.)" 3. **``** — exactly one short, glossary-grounded sentence. Example question: "In one sentence, what does the actor want to accomplish? Use glossary terms; avoid UI affordances like 'clicks the orange button'." 4. **``** — one or more conditions that must hold before the flow starts. The Skill asks for at least one; loops "Anything else that must be true before the flow starts?" until the author signals done. (Cardinality is zero-or-more per the dictionary; in practice every accepted use case has at least one — the Skill prompts for one and accepts zero only on explicit decline.) 5. **`` with one or more ``** — the happy-path step sequence. The Skill asks "What is the first step of the happy path?", then "Next step?" until the author signals done. Each step is one sentence in glossary terms. **At least one step is required.** 6. **``** — at least one condition that holds after the flow completes. (Dictionary says zero-or-more; the Skill prompts for one because most accepted use cases need it. Author may decline explicitly.) 7. **``** — **at least one acceptance block is required** for any use case the author intends to set to `status="accepted"`. The Skill prompts for a Given/When/Then block in Gherkin (the default `format=`). If the author prefers EARS, the Skill accepts `format="ears"` instead. Example question: "Give me one acceptance scenario in Gherkin: a 'Given' precondition, a 'When' action, and a 'Then' observable outcome — in glossary terms." ### Optional slots (surfaced as offers, asked on author interest) After the required slots are filled, the Skill asks one umbrella question to gate the optional block: **"Does this use case have alternative flows (error or branch paths), or does it interact with named domain events, rules, invariants, or NFRs?"** If the author says no to everything, the Skill moves straight to drafting. If yes, the Skill drills into each affirmed optional in this order: 8. **``** — zero or more named alternative paths. For each one the author confirms, the Skill asks for the `name=` slug ("a short slug describing the divergence, e.g. `payment-declined`") and then loops `` prompts the same way as ``. 9. **``** — zero or one collection of `` children. The Skill asks "Which domain events does this use case emit, observe, or react to?" and accepts one or more ids. Each id must resolve to an existing top-level `` in `behavior.xml`; if the author names an event that does not exist, the Skill notes it and tells the parent skill the event must be added first. 10. **``** — zero or one collection of ``. "Which top-level rules apply during this use case?" Same resolution discipline. 11. **``** — zero or one collection of ``. "Which invariants must hold for this use case?" Same resolution discipline. 12. **``** — zero or one collection of ``. "Which NFRs constrain this use case?" Same resolution discipline. ### Status attribute (asked last, with default) 13. **`status`** — defaults to `accepted`. The Skill confirms ("Set status to `accepted`, `draft`, `proposed`, `deprecated`, or `superseded`? Default is `accepted`.") and only inserts the attribute if the answer differs from the default. ## Forbidden slots — no downward references on a use case The Skill **explicitly forbids** every downward-pointing attribute and the `` element on the use-case being drafted. The script never asks for, never accepts, and never emits: - `carried-by` (would point at Topology) — **forbidden**. - `realized-by` (would point at Interfaces operations) — **forbidden**. - `governed-by` (would point at Composition call-flows) — **forbidden**. - `priority` (would mix planning metadata into the domain layer) — **forbidden**. - `emits` (would duplicate the `` collection inversely) — **forbidden**. - A `` child element — **USDL has no `` element**; the cross-section spine is computed from inverse references on lower-level Elements (``, ``, ``). **Forbidden**. This implements `beh.rule.no-downward-reference` and `inv.reference-direction-monotonic`. If the Spec author asks "how do I link this use case to the operation that realises it?", the Skill answers: **you don't link it from here — the linkage lives on the operation in `interfaces.xml` via `realizes-behavior=""`**. The use case stays pure-domain and references nothing outside Behavior. If the Skill detects a downward attribute proposed by the author or by upstream context, it refuses the slot and explains the reference-direction rule. ## Escalate-not-fabricate The Skill follows `beh.rule.escalate-not-fabricate` for every slot. The flow on an unparseable or missing answer: 1. **Restate once with the legal shape.** If the actor-id answer is "the customer" (free text where an `actor.*` id was expected), the Skill responds: "I need an actor id matching `actor.`. The current `behavior.xml` defines `actor.spec-author` and `actor.ci-runner`. Either pick one, or tell me you'd like to add a new actor first." 2. **If the second answer is still unparseable, escalate and pause.** The Skill returns to the parent skill with the open question and the offered legal shapes; it does **not** invent a placeholder, omit the slot, or write a malformed draft. 3. **Missing referenced ids are escalated, not fabricated.** If the author says the use case emits `evt.booking-confirmed` but that event does not exist in `behavior.xml`, the Skill pauses and tells the parent skill: add the event first; do not invent it inline. The Skill never inserts placeholders (no `TODO`, no `actor.unknown`, no empty ``). Missing required input always escalates. ## Drafting and validation Once every required slot has a parseable answer (and any affirmed optional slots are filled), the Skill drafts the `` Element to match `templates/behavior/use-case.xml`: 1. **Load the Template** via `usdl:templates`. The Template is the slot map; the Skill fills each slot with the corresponding gathered answer in the order the Template prescribes. 2. **Validate the draft against the Template** before writing — every required attribute present, no unknown attributes, every required child present, child order correct. This is the `usdl:templates` Element-versus-Template conformance check, run on the draft in memory, per `beh.rule.template-validated-element`. 3. **Hand the draft to the parent skill** (`usdl:behaviour` or the spawning Agent). The parent owns Section-file mutation; this Skill never writes to `behavior.xml` itself. 4. **Parent calls Bin via `usdl:bin`** to run `usdl validate` against the updated `behavior.xml`. Per `beh.rule.self-validate-before-done`, completion is reported only after validation passes; on failure the parent applies trivial repair or escalates back into this Skill's script for the offending slot. ## Response shape A successful pass returns to the parent skill: - The drafted `` XML, conforming to `templates/behavior/use-case.xml`. - The set of gathered answers, keyed by slot name. - The list of any **referenced ids that need to be added first** (actors, events, rules, invariants, or NFRs the author named but that do not yet exist). - An empty list when no escalation is needed. An escalation pass returns instead: the open question, the legal shape that was rejected, the slot it belongs to, and the partial draft (never written). ## What this Skill does not do - It does not author any Element other than one ``. Authoring an ``, ``, ``, ``, ``, or `` is delegated to the parent `usdl:behaviour` (or, for NFRs, the peer `usdl:behaviour:nfr`). - It does not write `behavior.xml` directly. Mutations go through the parent skill, which uses Bin. - It does not call `usdl:bin` itself. Bin invocation is the parent's responsibility. - It does not invoke peer Skills. Routing is the host's job. - It does not surface any downward reference. The use case stays pure-domain (`inv.reference-direction-monotonic`). - It carries no executable code (`con.no-implementation-code-in-skill-md`). Everything above is prose describing what to ask, in what order, and what to forbid.

usdl-behaviour-usecase

Install this skill

Comments