--- name: usdl-behaviour-nfr description: Element-targeted Skill that authors one USDL NFR (non-functional requirement) Element in behavior.xml. Owns the NFR Interview Script that collects the quality category from the closed enum (performance, availability, security, privacy, accessibility, operability, portability, maintainability, scalability, compliance, usability), the conditionally-required measure and threshold (mandatory when quality is performance or availability), the scope reference, and the arc42 quality-attribute scenario (source, stimulus, environment, artifact, response, response-measure). Trigger this Skill when the active task mentions "NFR", "non-functional requirement", "performance requirement", "availability requirement", "quality attribute", "arc42 scenario", "latency", "throughput", "uptime", "p95", "p99", "response-measure", "stimulus", or any other arc42 quality-scenario term 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/nfr.xml via usdl:templates and the parent skill then calls Bin through usdl:bin to validate. Carries no executable code. --- # usdl-behaviour-nfr ## What this Skill is This is the element-targeted Skill that authors **exactly one `` Element** for `behavior.xml`. It owns the NFR **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 for an NFR, draft the Element from the NFR 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 an `` 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 "shared NFRs" step (or any use case names an `` that does not exist yet), `usdl:behaviour` names this Skill in its response so the host may load it. - **Template authority:** `usdl:templates` — owns `templates/behavior/nfr.xml` (the canonical NFR 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:usecase`, `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/nfr.xml` — the canonical NFR 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 NFR's id and to confirm the `scope=` target (a `term.*`, a `beh.*` use case, or `system`) already exists. 3. The Behavior dictionary `` row, including the closed `quality` enum and the **conditional `measure`/`threshold` rule** — 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 quality enum (closed list) The `quality` attribute is drawn from a closed enum. The Skill enumerates these values to the Spec author and accepts no others: | Value | Typical scenario shape | |---|---| | `performance` | Latency / throughput / time-to-result thresholds. **`measure` + `threshold` required.** | | `availability` | Uptime / partition tolerance / recovery thresholds. **`measure` + `threshold` required.** | | `security` | Authn/authz, tamper-resistance, secret handling. `measure`/`threshold` optional. | | `privacy` | PII handling, retention, consent. `measure`/`threshold` optional. | | `accessibility` | WCAG conformance, assistive-tech support. `measure`/`threshold` optional. | | `operability` | Observability, runbook readiness, ops ergonomics. `measure`/`threshold` optional. | | `portability` | Cross-platform, cross-cloud movability. `measure`/`threshold` optional. | | `maintainability` | Extension without core change, change-cost, refactor surface. `measure`/`threshold` optional. | | `scalability` | Headroom, horizontal-scaling behaviour at growth points. `measure`/`threshold` optional. | | `compliance` | Regulatory / contractual obligations (GDPR, SOC2, PCI). `measure`/`threshold` optional. | | `usability` | Author / end-user cognitive load, time-to-first-task. `measure`/`threshold` optional. | If the author proposes a quality that is not in this list, the Skill restates the legal values once. If the second answer is still off-enum, it escalates per `beh.rule.escalate-not-fabricate` and does not invent a new quality value. ## The conditional `measure`/`threshold` rule The Behavior dictionary and the Stage 1 lint rule (in `how-to-use.md`) say: > **Every `` with `quality="performance"` or `quality="availability"` has both `measure` and `threshold`. Unmeasurable performance claims are spec-lint failures.** The Interview Script enforces this branch explicitly: - If `quality` resolves to `performance` or `availability`, the Skill **asks `measure` and `threshold` next, unconditionally**, before any other slot. The Skill must not write the draft without both attributes filled. - For every other quality value, `measure` and `threshold` are **optional**. The Skill surfaces them as an offer ("Do you have a measurable metric and threshold for this quality, or is it binary / qualitative?") and includes them only when the author supplies values. The Skill never invents a threshold value. Numbers like "500", "1000", "p95", "p99" are author-supplied or the slot stays open and the Skill escalates. ## The Interview Script (ordered) The Skill runs the questions below in order. **Required slots are asked unconditionally.** Optional slots are surfaced as offers and asked only when the author signals interest. This implements `beh.rule.minimum-interview`. ### Required slots (asked unconditionally) 1. **`id`** — the NFR id. Kebab-case, unique across the entire Spec, prefixed `nfr.`. Example question: "What kebab-case id should this NFR carry? (We'll prefix `nfr.` — e.g. `nfr.validation-latency`.)" 2. **`quality`** — one of the eleven closed-enum values listed above. Example question: "Which quality attribute does this NFR cover? (One of: performance, availability, security, privacy, accessibility, operability, portability, maintainability, scalability, compliance, usability.)" 3. **`measure` and `threshold` — conditionally required.** - **If `quality` is `performance` or `availability`:** The Skill asks both unconditionally. Example questions: "What metric name captures this NFR? (e.g. `p99-latency-ms`, `validation-latency-ms`, `uptime-percent`.)" and "What measurable threshold? (e.g. `500`, `99.95`.)" Both slots must be filled before drafting. - **Otherwise:** The Skill surfaces them as an offer (see optional slots below). They are not required. 4. **`scope`** — the locus the NFR fundamentally constrains. **Must resolve** to one of: - a `term.*` glossary-term id (e.g. `term.usdl`, `term.spec`) — when the NFR constrains a domain concept as a whole; - a `beh.*` use-case id (e.g. `beh.bootstrap-section`, `beh.validate-spec`) — when the NFR constrains one use case; - the literal token `system` — when the NFR constrains the entire system without a finer locus; - a comma-separated list of any of the above (no whitespace) — when the NFR straddles multiple loci. If the author names a target that does not exist in the Spec, the Skill pauses and tells the parent skill the target must exist first; it does not fabricate. (`scope` defaults to `system` per the dictionary, so if the author cannot point at a finer locus, `system` is the legal fallback — that fallback is author-confirmed, not Skill-invented.) 5. **`` — the arc42 quality-attribute scenario.** Exactly one is required (the Template declares one; the dictionary allows one-or-more, and the Skill prompts for a second only if the author signals interest). Each scenario carries **six children in this declared order**: 1. **``** — the entity that initiates the stimulus. Example question: "Who or what initiates this scenario? (e.g. `End user`, `Spec author`, `CI runner`, `Maintainer adding a new Element kind`.)" 2. **``** — what the source does or wants. Example question: "What does the source do? Describe the action that triggers the response. (e.g. `Issues a request for the relevant resource`, `Runs Bin validate against a complete Spec`.)" 3. **``** — operating conditions. Example question: "Under what operating conditions? (e.g. `Production, normal load`, `Spec contains up to 100 Elements`, `First USDL session, no prior training`.)" 4. **``** — the element being stimulated. Example question: "Which element is being stimulated? (The system component or subsystem whose quality is observed — e.g. `Read API`, `Bin validator`, `Skill ecosystem`.)" 5. **``** — the qualitative observable outcome. Example question: "What is the qualitative observable outcome? (e.g. `Returns the result successfully`, `Emits diagnostics and exits`, `Writes the first use case to behavior.xml`.)" 6. **``** — the quantitative threshold. Example question: "What is the measurable threshold? (e.g. `within 500 ms at p99 over a 5-minute window`, `within 1000 ms at p95`, `in at least 80% of first-time-author trials`.)" The arc42 ordering is **load-bearing**: the Template and the dictionary list the six children in this exact sequence, and the draft must follow it. ### Optional slots (surfaced as offers, asked on author interest) After the required slots are filled, the Skill offers the following only when relevant. Per `beh.rule.minimum-interview`, none of these is asked unconditionally: 6. **`measure` and `threshold` (for non-performance, non-availability qualities)** — surfaced together as one offer: "Do you have a metric name and measurable threshold to attach to this NFR, or is the property binary / qualitative?" Included only when the author supplies both. Either both are present or both are absent; the Skill never writes one without the other. 7. **Additional `` blocks** — surfaced as: "Would you like to add another scenario covering a different operating condition (e.g. partition, surge, cold-start)?" Each additional scenario follows the same six-child arc42 shape, in the same declared order. 8. **`status`** — defaults to `accepted`. The Skill confirms only if the author wants to deviate from the default; `status="accepted"` is not written explicitly. ## Example scenarios per quality category Every quality category gets a worked example so the Skill can ground the author quickly when they say "I don't know how to phrase this." Examples below are illustrative, not prescriptive; the Skill restates them as samples and asks the author to substitute their own values. - **`performance`** (with measure + threshold): - source: `Spec author or CI`; stimulus: `Runs Bin validate against a complete Spec`; environment: `Spec contains up to 100 Elements`; artifact: `Bin validator`; response: `Emits diagnostics and exits`; response-measure: `within 1000 ms at p95`. (Pattern of `nfr.validation-latency`.) - **`availability`** (with measure + threshold): - source: `Consuming agent`; stimulus: `Queries a deployed Spec store`; environment: `Production, normal load`; artifact: `Spec store`; response: `Returns the requested Section file`; response-measure: `99.9% over a rolling 30-day window`. - **`security`** (qualitative, no threshold): - source: `Untrusted external system`; stimulus: `Attempts to write to the schemas store via a non-Bin path`; environment: `Production`; artifact: `Spec store`; response: `Rejects the write and emits an audit event`; response-measure: `zero successful unauthorised writes per quarter`. - **`privacy`** (qualitative): - source: `Spec author`; stimulus: `Authors a Spec referencing user data terms`; environment: `Repository accessible to the team`; artifact: `Glossary`; response: `Holds no personal data values in the Spec`; response-measure: `zero PII strings present across the four Section files`. - **`accessibility`** (qualitative): - source: `Spec author using a screen reader`; stimulus: `Reads a rendered describe output`; environment: `Terminal with accessibility tooling`; artifact: `Bin renderer`; response: `Emits Markdown that is fully linearisable`; response-measure: `passes a WCAG 2.1 AA contrast and structure audit on the rendered Markdown`. - **`operability`** (qualitative): - source: `On-call engineer`; stimulus: `Receives a CI failure on a Spec change`; environment: `CI pipeline`; artifact: `Bin validator`; response: `Surfaces actionable diagnostics with file path and line number`; response-measure: `engineer can locate the failing Element without reading the raw Spec`. - **`portability`** (qualitative): - source: `Spec author on a new OS`; stimulus: `Runs Bin from a fresh install`; environment: `Linux, macOS, or Windows`; artifact: `Bin executable`; response: `Validates the same Spec to the same diagnostics`; response-measure: `byte-identical diagnostics across the three platforms`. - **`maintainability`** (qualitative): - source: `Maintainer adding a new Element kind`; stimulus: `Adds a new Element Template and dictionary entry`; environment: `USDL repo, current toolset`; artifact: `Skill ecosystem and Bin`; response: `Loads the new Template and validates new Elements of that kind`; response-measure: `zero core-code changes required for the new Element kind`. (Pattern of `nfr.extension-without-core-change`.) - **`scalability`** (qualitative or measured): - source: `Spec author`; stimulus: `Validates a Spec containing 10x the typical Element count`; environment: `Local agent host`; artifact: `Bin validator`; response: `Completes the validation without degradation`; response-measure: `validation latency scales sub-linearly in Element count`. - **`compliance`** (qualitative): - source: `External auditor`; stimulus: `Requests evidence the Spec authoring trail is reproducible`; environment: `Audit window`; artifact: `Bin validator and Spec store`; response: `Provides a deterministic validation report per commit`; response-measure: `100% of Spec commits have a matching CI validation record`. - **`usability`** (qualitative): - source: `Non-expert Spec author`; stimulus: `Attempts a Behavior Section after reading only README and section docs`; environment: `First USDL session, no prior training`; artifact: `Skill ecosystem`; response: `Completes a Behavior Section with at least one actor, one use case, and one acceptance block`; response-measure: `in at least 80% of first-time-author trials, in a single session under one hour`. (Pattern of `nfr.author-cognitive-load`.) ## Forbidden slots — no inverse-pointing attributes The Skill **explicitly forbids** every inverse-pointing attribute on the NFR being drafted. The script never asks for, never accepts, and never emits: - `applies-to` (would name use cases the NFR constrains inversely) — **forbidden**. - `subject-to` (would name rules whose enforcement points back) — **forbidden**. - Any attribute pointing into Topology, Interfaces, or Composition (`carried-by`, `realized-by`, `governed-by`, etc.) — **forbidden**. References flow forward from each use case's `` collection to this NFR's id; the inverse direction is recoverable by inspection and is not declared. This implements `inv.reference-direction-monotonic`. If the author asks "how do I link this NFR back to the use case that bound it?", the Skill answers: **you don't link it from here — the use case's `` collection carries the linkage**. ## 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 `quality` answer is "fast" (free text where the closed enum was expected), the Skill responds with the eleven legal values and asks again. If the `threshold` answer is "low" (qualitative where a measurable value was expected), the Skill responds: "I need a measurable threshold — a number, a percentile, a percentage. Examples: `500`, `99.95`, `p99 under 200 ms`." 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 threshold, fabricate a metric name, omit the slot, or write a malformed draft. 3. **Missing `scope` targets are escalated, not fabricated.** If the author names `scope="beh.send-notification"` but that use case does not exist, the Skill pauses and tells the parent skill: the target must exist first; do not invent it inline. The literal token `system` is always legal when the author cannot point at a finer locus. 4. **Thresholds are never invented.** Per the dictionary and `beh.rule.escalate-not-fabricate`, the Skill never substitutes a "reasonable-sounding" number like `500` or `99.9` without the author explicitly supplying it. If the author cannot supply a threshold and `quality` is `performance` or `availability`, the Skill escalates — the NFR is not drafted. The Skill never inserts placeholders (no `TODO`, no `threshold="?"`, 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/nfr.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 — attributes first (`id`, `quality`, optional `measure`, optional `threshold`, optional `scope`), then `` with its six ordered children. 2. **Apply the conditional check before draft handoff.** If `quality` is `performance` or `availability` and either `measure` or `threshold` is missing, the Skill refuses to emit the draft and returns to the script for the missing slot. 3. **Validate the draft against the Template** before writing — every required attribute present, no unknown attributes, every required child present, child order correct (the arc42 six-child order is enforced here). This is the `usdl:templates` Element-versus-Template conformance check, run on the draft in memory, per `beh.rule.template-validated-element`. 4. **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. 5. **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. The Stage 1 lint check that rejects a `performance` or `availability` NFR missing `measure` or `threshold` runs here — but the Skill's own pre-draft check should have caught it already. ## Response shape A successful pass returns to the parent skill: - The drafted `` XML, conforming to `templates/behavior/nfr.xml`. - The set of gathered answers, keyed by slot name. - The list of any **referenced ids that need to exist first** (use cases or glossary terms named in `scope=` that do not yet exist in the Spec). - 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 use cases, the peer `usdl:behaviour:usecase`). - 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 inverse-pointing or downward reference. The NFR carries no `applies-to`, `subject-to`, or lower-section attribute (`inv.reference-direction-monotonic`). - It does not invent quality values outside the closed enum, metric names, threshold values, or `scope` targets. Missing or unparseable input escalates per `beh.rule.escalate-not-fabricate`. - 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-nfr

Install this skill

Comments