--- name: semantius-skill-maker description: >- Generate ONE consolidated, domain-specific Agent Skill (agentskills.io format, usable by Claude Code and any other agent harness that loads Agent Skills) from a Semantius semantic-model file (`*-semantic-model.md`). The output packages the model's domain glossary, jobs-to-be-done, enum lifecycles, FK shapes, label composition rules, and guardrails into a single SKILL.md so a calling agent can use that specific Semantius model efficiently, without re-deriving the schema or loading the source model file at runtime. Use when the user wants "a skill for the CRM model", "wrap the workforce model in a skill", "generate a domain skill from this semantic model", or any phrasing that asks for a model-specific skill on top of an existing `*-semantic-model.md` file. Also trigger when the user wants to rebuild, reanalyze, re-author, or holistically regenerate an existing generated skill against the current model (e.g. "rebuild the `` skill from scratch", "the model has drifted, regenerate everything", "throw out the existing skill folder and start over"). The generated SKILL.md delegates platform mechanics (CLI install, PostgREST encoding, cube DSL) to `use-semantius`, which is expected to load alongside. --- # semantius-skill-maker Turn a semantic-model markdown file (the artifact produced by `semantic-model-analyst`) into **one** task-aware Agent Skill that captures the domain knowledge needed to act on that model efficiently. The generated skill does not duplicate `use-semantius`, it sits on top of it, focusing exclusively on the domain (entities, lifecycles, label rules, cross-FK invariants) that a generic platform skill cannot know. The generated skill is plain Agent Skills format, a `SKILL.md` with YAML frontmatter under a folder named after the model, and works in any agent harness that loads Agent Skills, including Claude Code. ## Writing conventions (apply to every file and message this skill produces) These rules apply to chat output, the generated SKILL.md, the generated README.mdx, every reference file, and every script this skill writes. **1. US English spellings, always.** Never British English. Examples (left = correct US form, right in backticks = banned British form): optimize (not `optimise`), behavior (not `behaviour`), modeling (not `modelling`), customize (not `customise`), recognize (not `recognise`), labeled (not `labelled`), materialize (not `materialise`), organization (not `organisation`), summarize (not `summarise`), categorize (not `categorise`), uncategorized (not `uncategorised`), normalize (not `normalise`), harmonize (not `harmonise`), analyze (not `analyse`). When in doubt between two spellings, pick the `-ize` / `-or` / `-er` form. **2. No em-dashes (`—`, U+2014).** Banned everywhere this skill writes: SKILL.md, README.mdx, semantic-model citations, references, scripts, and chat output. **This propagates.** LLMs mirror the style of their context, so an em-dash inside generator prose causes generated skills to emit em-dashes too. Replace with: `X — Y` parenthetical → `X (Y)` or `X, Y`; `X — but Y` contrast → `X. But Y.` or `X; Y`; `A — B — C` triplet → split into two sentences. The en-dash (`–`) and hyphen (`-`) are fine in number ranges and compound words; the ban is on `—` used as punctuation. Before writing any file, literal-search for `—` and convert each instance. **3. Singular-subject grammar in confirmation prompts.** "Looks good?" not "Look good?"; "Sounds right?" not "Sound right?". Use the form that agrees with the singular implicit subject. **4. README.mdx catalog-description rules.** The README.mdx this skill generates is rendered side-by-side with other skills in a catalog gallery. These are hard constraints for catalog readability: - **Front-matter `description`**: one sentence, ≤140 characters, unique value-prop for *this* skill. **Never** starts with "This skill" and **never** contains the substring "this skill". Do not just restate the domain. **Shape: verb-led, names actual capabilities** (e.g. "Manages the recruiting funnel from requisition through application, interview, offer, and hire."). Do **not** use the "[verb] [object] so [outcome]" shape; the "so..." clause reads as trigger-fodder, not a capability list. - **Front-matter `title` and the `#` heading**: must always contain the word "Skill", and must read as natural English. If the source `system_name` ends in "System" (e.g. "Applicant Tracking System"), drop "System" and append "Skill" → "Applicant Tracking Skill". Otherwise append "Skill" directly: "Workforce Planning Skill", "Product Roadmap Skill", "Customer Relations Skill". - **Body, immediately after heading**: repeat the *model's* domain description verbatim (or near-verbatim), pulled from the model file's `domain` front-matter or §1 narrative. The body describes the SYSTEM, not the skill. The skill's unique angle lives only in the front-matter `description`. - **No `generated_from` key** in README front-matter. - Validate before declaring done: literal-search for "this skill" (must be zero hits) and `—` (must be zero hits), and check the heading contains "Skill". **5. Semantius entity-label symmetry (when the generated SKILL.md cites entity labels).** `singular_label` is the bare singular noun matching `plural_label`. ✅ `Product` / `Products`. ❌ `Product Name` / `Products`. The skill-maker reads these from the source model file; if the source has an asymmetric pair, treat the source as buggy and ask the user to fix the model via the analyst before re-running the skill-maker (do not paper over it in generated output). --- ## Schema compatibility: `EXPECTED_MAJOR = 3` This skill expects model files written by `semantic-model-analyst` major `3`. The model file's front-matter `version: "MAJOR.MINOR"` is checked at the start of Step 2. **Major must equal `EXPECTED_MAJOR`**, minor is informational and not compared. Files with a different major are rejected; the resulting per-domain skill would bake in stale recipes. Three cases: - **Older major**, the file was written using a structure this skill no longer understands (different section numbering, different table shapes, missing fields). Tell the user to run `semantic-model-analyst`; its archived-knowledge mode reads the older file and re-authors a current-major file from the same semantic content. Re-run skill-maker against the new file. - **Newer major**, the file was written by a newer analyst than this skill knows. Tell the user to update `semantius-skill-maker` before retrying. - **Missing `version` key** (legacy, pre-versioning), treat as major `0`; same response as older-major. When the analyst's major bumps, this skill's `EXPECTED_MAJOR` must be bumped in lock-step (same commit when feasible). The trio of analyst, deployer, and skill-maker share the major. The history of the skill-maker's contract changes lives in [`CHANGELOG.md`](./CHANGELOG.md) — what each analyst-lockstep bump changed in the parser, indices, generated-skill preambles, and self-review principles. That file is not loaded at runtime; the body of this SKILL.md is the **current contract**, the CHANGELOG is the **history**. --- ## Inputs - `MODEL_PATH`: absolute path to a `*-semantic-model.md` file with valid frontmatter (`system_slug`, `system_name`, `entities`, etc.) and §3 entity definitions. ## Output A single folder under the user's Claude skills root. Two top-level files are always written; `references/` and `scripts/` subfolders are written only when the JTBD classifier in Step 3 (Pass 3) puts work there. ``` // ├── SKILL.md # for the calling agent: glossary, JTBD outlines, guardrails ├── README.mdx # for humans browsing a catalog: narrative + diagram ├── references/ # optional, per-JTBD detail, loaded on demand │ └── .md └── scripts/ # optional, deterministic ops, invoked not loaded └── .sh ``` `SKILL.md` is what an agent harness loads at runtime. `README.mdx` is a human-facing catalog entry: a downstream system renders these into a gallery so a person can browse available skills, understand each one's purpose at a glance, and decide whether to install it. The two files share a folder, but their audiences and formats are different, do not collapse them, and do not skip the README. The `references/` and `scripts/` subfolders exist to keep SKILL.md small. SKILL.md is loaded into context *every* time the skill triggers; a reference file is loaded only when the agent enters that specific JTBD; a script is never loaded, the agent invokes it. A 400-line SKILL.md plus a handful of focused 80-line reference files costs less per trigger than a 900-line monolith, because the agent typically engages one JTBD at a time. The classifier in Step 3 (Pass 3) decides which JTBD belongs in which file. `` is the model's `system_slug` converted to kebab-case , **underscores become dashes** (e.g. `customer_relations` → `customer-relations`, `product_roadmap` → `product-roadmap`). Every multi-word skill in Claude Code uses kebab-case (`use-semantius`, `semantic-model-analyst`, `skill-creator`); mashing words together (`customerrelations`) breaks the convention and makes the description text harder to read. The folder name and the SKILL.md `name` frontmatter match exactly. `` resolution order: 1. **Project skills root**, the nearest `.claude/skills/` directory walking up from the model file's location, or from the current working directory. Prefer this if found. 2. **User skills root**, `~/.claude/skills/` (on Windows: `%USERPROFILE%\.claude\skills\`). If both exist, ask the user which to use; default to the project root. If neither exists, ask before creating one. ### Source-of-truth and the model reference The generated SKILL.md is **self-contained at runtime** for the cross-cutting facts (glossary, enums, recipes resolve every value at generation time so the calling agent never needs to open the model file to act). FK shape and audit-logging detail live with the JTBD that uses them, not in SKILL.md, see "Where FK detail lives" below. The model file is still referenced, but only as **provenance metadata in frontmatter** (`semantic_model:` key, see the template below), not as a clickable link in the body. Two reasons: - A body link invites the agent to fetch a 400+ line file the SKILL.md has already condensed. That defeats the point of generating the skill. - Provenance still needs to live somewhere, for re-generation, audit, and drift detection, and frontmatter is the right place because it's machine-readable and the agent doesn't render it as a follow-up action. Set `semantic_model` to the model's `system_slug` value (e.g. `product_roadmap`), not a path. The slug is stable across machines and re-locations of the model file; an absolute path bakes in the generator's working directory and breaks the moment the file moves or the skill is shared with another user. The downstream tools that consume this provenance (re-generation, drift detection) resolve the slug against the current `*-semantic-model.md` files in the working directory, so the slug is sufficient. --- ## Workflow ### Step 1, Load the Semantius reference Before writing recipes, read the `use-semantius` skill so the JTBD recipes use the right CLI patterns: ``` Read: /use-semantius/SKILL.md Read: /use-semantius/references/data-modeling.md Read: /use-semantius/references/crud-tools.md Read: /use-semantius/references/cube-queries.md ``` You will not run `semantius` yourself in this skill, but the recipes you bake in must be valid CLI invocations. If `use-semantius` cannot be located, stop and ask the user. ### Step 2, Parse the model Read `MODEL_PATH` and **gate on the version first** before extracting anything else. Compare the file's front-matter `version` major against this skill's `EXPECTED_MAJOR` (see "Schema compatibility" near the top). Major equal → continue. Major older or missing → stop with a message naming the file's version, this skill's expected major, and the recommended fix (run the analyst's audit to migrate). Major newer → stop and ask the user to update this skill. Do not parse anything else when the gate fails; the file's structure may not match what the rest of Step 2 assumes. Once the version gate passes, extract: - `system_slug`, `system_name`, `domain`, and **`module_type`** (`"domain"` or `"master"`; absent → treat as `"domain"`) from frontmatter. `module_type` controls two things downstream: the generated SKILL.md's "Module type" preamble line (Step 5), and the JSON-array merge note (master-module entities' `computed_fields` / `validation_rules` entries carry an extra `source_module` reconciliation tag — see the per-entity extraction note below). - Entity list with `singular_label`, `label_column`, fields (name, format, required), enum values (§5), FK relationships (§4), parent/cascade-child flags, `audit_log`, **`computed_fields`** array, **`validation_rules`** array, and (analyst v3.0+) any **`**Shared master cluster:** `** annotation under the §3 entity heading. The two latter JSON blocks are platform-enforced JsonLogic — they change what the calling agent must do and what the calling agent must NOT do. See "Pass 2" merit-test adjustments below. When the entity belongs to a master module (`module_type: master` in frontmatter), its `computed_fields` and `validation_rules` entries may each carry a `source_module` key naming the consuming module that contributed the entry. Treat `source_module` as opaque reconciliation metadata: surface its existence in the preamble note but never use it to filter entries (every entry applies regardless of which module contributed it). Domain-module entities never carry `source_module`. Record the cluster annotation per-entity into a `master_cluster_by_entity` index. The annotation is informational for skill-maker: it signals that the entity is a classic master concept (vendors → `parties`, cost_centers → `finance`, etc.) and that writes to it may have cross-domain visibility. Use it to surface a "shared across domains" callout in the generated skill's preamble (Step 5) and as a guardrail on every write recipe touching the entity (Step 6). Treat each entry's **JsonLogic body as opaque** and read only the human-readable metadata (`name` and `description` for `computed_fields`; `code`, `message`, and `description` for `validation_rules`). All matching downstream, Pass 2 suppression, gap-tracking, SKILL.md preamble copy, JTBD failure-mode wiring, uses that metadata. The analyst's job is to write `description` / `message` text precise enough that a candidate transition or derivation can be matched against it by reading. If the analyst's text is too vague to match, that is a model defect to send back; do not try to evaluate the JsonLogic to recover. **One exception: scan each rule's JsonLogic body literally (string-match only) for the two platform-extension operators.** Both are first-class JTBD signals: - **`require_permission`**, i.e. `{"require_permission": ""}` somewhere inside the rule body. Extract `(entity, rule_code, rule_description, permission_code)` for every match into a `conditional_permissions` index. This index drives the new "Conditional-permission gate" merit signal in Pass 2 and the `Platform-enforced permissions` SKILL.md preamble (Step 5). The match is purely literal; *which* condition gates the permission still comes from the rule's `description` text, not from interpreting the JsonLogic. - **`value_changed`**, i.e. `{"value_changed": ""}` somewhere inside the rule body. Note `(entity, field)` pairs into a `transition_gated_fields` index. This is informational, not a merit signal on its own; it helps Pass 2 confirm that a `require_permission` rule actually fires on transition rather than on every write (a quality check that the analyst's audit also runs). In analyst v2.0+ files, the **§2 Permissions summary table is the canonical source** for the module's full permission catalog (not §8 step 1). Parse the table verbatim — five columns: `Permission | Type | Description | Used by | Hierarchy parent`. Build a `permissions_catalog` index from the rows. Use this index for everything: the SKILL.md "Platform-enforced permissions" preamble (one row per workflow permission), the role-hint lookup for each `conditional_permissions` entry (the `Description` and `Used by` cells give the role-hint richer than v1.11's §8 prose), and the cross-check that every `conditional_permissions[].permission_code` appears in the table. A mismatch is a model defect; refuse to generate and route back to the analyst. §8 step 1 in a v2 file is a procedural pointer to the table and no longer enumerates permissions itself; do not parse §8 for the permission list. **v3.0 cross-module hierarchy rows.** The `Hierarchy parent` cell may reference a permission in a *different* module (e.g. an ITSM module's `itsm:read` row carrying `Hierarchy parent: parties:read`); this is a cross-module bridge to a master module that the deployer materializes via `permission_hierarchy` rows tagged `origin = "model_master"`. Recognize these by the presence of a `:` value in the cell where `` is not this module's `system_slug`. Record cross-module parents into a `master_inclusions` index keyed by `(this_permission, master_permission)`. The index drives a one-line note in the SKILL.md "Platform-enforced permissions" preamble: every permission with at least one cross-module parent gets a *"includes : from the `` master module"* sub-note so the calling agent knows that holding it grants visibility into shared data. Same-module hierarchy rows still surface as the regular rollup chain; the index split only matters for the preamble note. - **Inbound-FK delete-mode index).** Walk the §4 relationship table once more and build a `restrict_inbound` index per entity: for every row whose `Kind` is `reference` and `Delete` is `restrict`, record `(child_entity, fk_field)` against the *target* (the entity on the right side of the relationship). This index drives the new "Restrict-chained cleanup" merit signal in Pass 2 and is consumed by Pattern J (delete / archive of a parent entity that has restrict-children). The pattern matters because the platform refuses to delete a row that has live `reference + restrict` children; the calling agent must clean them up first, in dependency order, and a generic `use-semantius` `DELETE` will surface only a single per-row constraint failure rather than the full chain. Also note inbound `reference + cascade` and `reference + clear` rows separately; they don't trigger Pattern J but the SKILL.md preamble should still call out the cascade-delete / orphan-clear behavior for downstream awareness. - **Read-side rule indices).** Two new optional §3 sub-blocks per entity. Build one index for each; both stay opaque on the JsonLogic body and read only the human-readable metadata. - **`row_visibility_rules`** — for every entity that declares a non-empty `Select rule` sub-block, record `(entity, jsonlogic_object, description?)`. `description` is the entity-level prose that explains "what the rule restricts" — if the analyst didn't write one, walk §3 prose for a sentence that names the per-row predicate (e.g. *"a note is visible to its author, or to anyone when its `visibility` field is `public`"*). Surface a defect to the user if neither the sub-block carries a `description` nor §3 prose names the scope; the SKILL.md preamble and per-JTBD guardrails need readable scope text. **Critical (v2.2): the rule applies uniformly to every caller with `view_permission`.** The platform evaluates the JsonLogic body per row with `$today` / `$now` / `$user_id` as reserved variables; there is no documented mechanism by which holding a specific permission causes the rule to be skipped for that caller. If the analyst's model contains a §7 architectural decision naming a documented broadening mechanism (Stage 12 option C separate-entity surface, option D Postgres `BYPASSRLS` role attribute), record it under `row_visibility_broadening` keyed by entity so the SKILL.md preamble can name the actual mechanism the user resolved. **Never invent a "view_all bypass" the model file does not explicitly resolve in §7.** This index drives the **Row-level read scope** SKILL.md preamble (Step 5), the **Row-level read scope** cross-cutting guardrail attached to every read recipe against a scoped entity (Step 6 / Step 7), and a new severity row in Step 9 self-review. - **`dynamic_input_types`** — for every `Input type rules` entry across every entity, record `(entity, field, jsonlogic_object, description?)`. The `description` field describes *when* the rule changes the field's UI mode — `"hidden until status=approved, then readonly"` is the canonical shape. Walk the JsonLogic body literally (string-match only, same posture as `require_permission` / `value_changed`) for one pattern that bears on JTBD shaping: a return value of `"required"` triggered by a sibling-field comparison (e.g. `status=approved → "required"`) flags the field as a **conditional-required side-effect** on the same transition, which co-fires with Pattern A's side-effect-fields-on-transition merit signal. Record those into a sub-index `conditional_required_fields` keyed by `(entity, trigger_field, trigger_value, dependent_field)`. This index drives the **Conditional field UI states** SKILL.md preamble (Step 5), additional side-effect-fields-on-transition coverage in Pattern A recipes (Step 6 / Step 7), and a new severity row in Step 9 self-review. Skip both indices entirely when the model declares no entity-level `Select rule` and no field-level `Input type rules`. v2.1 and earlier files have neither. Compute `modelslug = system_slug.replace(/_/g, "-")`. Refuse if §7.1 lists open blockers, the model is not finished and the skill would bake in wrong recipes. ### Step 3, Plan jobs to be done JTBD discovery is a two-pass process: **nominate** broadly with the pattern catalog below, then **filter** with the merit test. The merit test matters because every section sits in one file, slack adds noise to every load. #### Pass 1, Nominate with the JTBD pattern catalog The catalog below is generic across domains, not just transactional business models. Walk **all nine patterns** every time, regardless of what the model "looks like" at first glance. **Pattern A, Lifecycle transitions on status enums.** Shape test: entity has a `*_status` enum + side-effect fields like `approved_at`, `committed_at`, `rejected_at`, `closed_at`. Each non-trivial transition (more than a status flip) is a candidate. Pure status flips with no side effects collapse into the entity's primary lifecycle JTBD. **Sub-shape: approval / sign-off / workflow gate), broadened in v1.12).** Any transition whose `validation_rules` entry invokes `{"require_permission": "..."}` (look up the entity's `conditional_permissions` index from Step 2) is automatically a strong JTBD candidate. The agent calling this skill is the one that will trip the permission check, so it needs an explicit recipe: name the permission, name the role(s) that typically hold it (read from §8 step 1 description), and tell the agent how to recover from the platform's throw (surface the rule's `message`, propose escalation paths like "ask an offer-approver to confirm" or "defer to the user who is signed in as the approver"). This sub-shape **does not get suppressed by the merit-test "platform-enforced" rule**, because the platform enforces *the check* but the calling agent still owns the *workflow* around it (the read of who-approves-what, the confirmation prompt, the failure-message phrasing). Treat every entry in `conditional_permissions` as one JTBD candidate (or a branch inside the entity's primary lifecycle JTBD), even if Pattern A would otherwise collapse the transition. The sub-shape covers three distinct trigger fields, all flagged the same way once `value_changed` + `require_permission` co-occur in the rule body: 1. **Status-transition gates**: `value_changed: "status"` → one of `approved` / `signed` / `released` / etc. Recipe: confirm with the user, then PATCH `status`. 2. **Submit-then-lock gates**: `value_changed: "is_submitted"` (or `is_locked` / `is_final` / `is_complete`) → `true`. Recipe: confirm the user is the row's owner (or holds the override permission); compose the PATCH that flips the lock; after the flip, treat the row as immutable except via the override. 3. **Closure / cancellation gates**: `value_changed: "status"` → one of `closed` / `cancelled` / `void` / `hired` (when §3 prose names weight). Same recipe shape as (1). **Sub-shape: housekeeping field appears on transition).** For each entry in the `conditional_required_fields` sub-index (built in Step 2 from `Input type rules`), the transition JTBD that fires the trigger condition must include the dependent field as a same-PATCH side-effect. Concretely: when `dynamic_input_types` says *"`offers.approved_at` hidden until status=`approved`, then readonly"*, the "approve offer" JTBD's PATCH body MUST set `approved_at = $now` in the same call as `status = "approved"` — the UI rule controls when the form renders the field, but a recipe that drives the transition through the API has no form to render and would silently leave `approved_at` empty. This is the same merit signal as the existing "Side-effect fields on transition" row (the `*_at` field that must be set in the same PATCH as the status flip), but the `input_type_rule` makes the pairing **mechanical and detectable** instead of relying on the analyst remembering to mention it in prose. Cross-reference with the entity's `validation_rules`: a paired family-5 conditional-required rule (server-side `must be non-null when status='approved'`) confirms the intent and gives the JTBD's Failure modes block the platform `code` to surface on bad writes. When the UI rule fires but no server-side family-5 rule exists, surface as a `platform_enforceable_gaps` entry of kind `validation_rule` (the UI says the field must be set; the server doesn't enforce it; the recipe enforces it client-side as a stopgap). **Pattern B, Polymorphic action / event staging.** Shape test: entity named `*_actions`, `*_events`, `*_transactions`, `*_movements`, with a polymorphic `*_type` enum that fans out behavior. Nominate **one** JTBD with branches per type value, do not split per enum value (that produces overlapping recipes). **Pattern C, Materialization / handoff.** Shape test: entity exists so another entity can be created from it; look for `originated_from_*_id` back-pointers, or "approved → real" flows where a staging row spawns rows in a different table. These are the highest-value candidates because they touch multiple tables and are the most error-prone for a calling agent to derive from the schema alone. **Pattern D, Hierarchy operations.** Shape test: self-referencing FK like `parent_*_id`, `manager_*_id`, `backfill_for_*_id`; tree-shaped data. Candidates: reparent without orphaning, roll-up, cycle prevention. Skip if the self-FK is purely informational ("previous version of this row") with no operation that restructures the tree. **Pattern E, Ownership / sharing.** Shape test: `owner_*_id` field, sharing tables. Candidates: transfer ownership of X, share X with, revoke access to X. (Multi-tenant scoping is not a Semantius concern: each customer organization runs its own Semantius deployment against its own database, so a single instance never holds rows for two different tenants.) **Sub-shape: owner-or-manager edit gate).** Entity carries a `created_by` / `author_id` / `owner_id` / `assignee_id` field AND its `conditional_permissions` index includes a rule that references the owner field against `$user_id` plus an elevated `:manage_all_` permission. The agent calling this skill is often *not* the original owner (it acts on behalf of users who may be different from the record's creator), so the recipe must surface: "editing this record requires that the caller is the original `` OR holds `:manage_all_`; if neither holds, the platform will reject with `: `, propose handing off to the original owner or to a user who holds the override permission." Treat as a JTBD candidate even when no other Pattern-E shape fires. **Pattern F, Publication / versioning.** Shape test: `draft`/`published` states distinct from approval; version chains (`*_version`, `previous_version_id`); `published_at` separate from `created_at`. Candidates: publish X, unpublish X, create new version of X. Distinct from Pattern A approval, publication is about distribution, not sign-off, and the side effects differ (cache invalidation, notification, visibility scope). **Pattern G, External-system handoff.** Shape test: fields like `external_*_url`, `*_external_id`, `webhook_*` entities, or a status value such as `synced` / `failed`. Candidates: sync X to external, replay failed X, reconcile X. **Pattern H, Bulk ingest.** Shape test: model declares webhook receivers explicitly, or has an entity whose typical population unit is a batch (a CSV-shaped table with no parent beyond the batch). See "pattern-level adjustments" below, in this skill, bulk ingest usually becomes a one-line pointer rather than a JTBD. **Pattern I, Cross-entity reporting.** Shape test: 3+ entities joined by FKs and at least one numeric measure (cost, count, duration, FTE, amount). See "pattern-level adjustments" below, in this skill, reporting becomes a `## Common queries` appendix, not a JTBD section. **Pattern J, Restrict-chained cleanup).** Shape test: an entity that appears as the *target* of at least one inbound `reference + restrict` FK from another entity in the model (read the `restrict_inbound` index from Step 2). The platform refuses to delete a row that has live restrict-children; the calling agent needs an explicit cleanup recipe naming each restrict-child entity in dependency order, with a per-child query shape ("find all `` where ` = `") and a delete loop before the parent delete itself. This pattern is the v1.13 parent-vs-reference rule's direct downstream consequence: when the analyst flips a `parent (cascade)` FK to `reference (restrict)` because the child has divergent permission scope, the analyst is *deliberately* moving the cleanup decision into the application layer rather than letting the platform silently cascade-delete permission-scoped rows. The skill-maker materialises that decision as a recipe. Candidates: "delete ``", "archive ``", "merge two `` records" (where merge ends with a delete of one). Skip when the entity has zero inbound restrict-FKs (the platform's own `DELETE` is enough) or when the restrict-children themselves carry no permission-scope divergence (then the analyst's choice of `restrict` was overly cautious; flag to the user but still emit the recipe). ##### Skip rules Do **not** nominate any of the following, they fall outside the "job to be done" frame: - **Single-row CRUD on master-data tables** with no lifecycle (insert one department, edit a job code). The calling agent uses `use-semantius` directly; an extra section is just noise. - **Seed / sample / test-data population.** One-off developer work, not a recurring job. If the user wants a seed script, ask separately. - **Entities listed in §7.2 "Future considerations"**, they don't exist yet. - **Pure read-by-id lookups**, the calling agent uses `postgrestRequest` directly. ##### When none of the patterns fire If a model has shapes none of the patterns recognize (rare, but possible for unusual domains), name the unmatched shape explicitly in the Pass-2 confirmation step and ask the user whether it warrants a custom JTBD. Do not invent a job to fill space. ##### Pattern-level adjustments specific to this skill - **Pattern I (cross-entity reporting) does not become a JTBD section here.** Promote it instead to a `## Common queries` appendix at the end of the SKILL.md, 3–5 pre-shaped cube queries the calling agent can adapt. Reporting is largely `use-semantius` territory once the schema is known; baking in *example queries* is useful, but framing it as a "job" misleads the calling agent into routing every analytic question through this skill. - **Pattern H (bulk ingest) becomes a one-line pointer**, not a recipe, unless the model declares webhook receivers explicitly. If it does, write a JTBD; otherwise the SKILL.md just notes "for CSV import, see `use-semantius` `references/webhook-import.md`". #### Pass 2, Apply the merit test (earn-its-place filter) For each candidate from Pass 1, ask: *would the calling agent get this right with `use-semantius` alone?* If yes, drop the candidate, an extra section is just noise, the calling agent should call `use-semantius` directly. A candidate **earns** a section only if it answers YES to ≥1 of the following: | Merit signal | What to check in the model | |---|---| | **Caller-populated label** | Junction or sub-entity has a required `*_label` column distinct from any `label_column`, with no DB-level default. The recipe must compose the label client-side, not obvious from the schema alone. | | **Computed field** | A stored derived field (e.g. `rice_score`, `total_amount`, `days_open`) whose value depends on sibling fields. Match by exact `name` against the entity's `computed_fields[].name` array, then resolve to one of three cases. **(a) Field is in `computed_fields`** → signal is **suppressed; does NOT earn a section on its own**. The platform overwrites caller payloads on every write, so the calling agent must not include the derived field in any POST/PATCH body and must not recompute it client-side. That rule is documented globally in the SKILL.md `Platform-derived fields` preamble (resolved at generation time); no per-JTBD recipe is needed. A candidate whose only merit signal is this row, in case (a), is dropped and listed under skipped. **(b) §3 prose names a derivation but no matching `computed_fields[].name` entry exists** → gap-tracked (record under `platform_enforceable_gaps`; see below). The signal earns a section ONLY when the candidate also passes one of the other merit signals (cascade, side-effect, junction without uniqueness, etc.); the recipe enforces the derivation client-side as a stopgap until the analyst adds the rule to the model. **(c) Neither field-name match nor §3 prose names a derivation** → signal does not fire. | | **DB-unguarded lifecycle gate** | Status enum where some transitions are valid and others aren't, but the DB accepts any value. Suppression here is **per-transition, matched by `description` / `message` text**, not per-block: walk the entity's `validation_rules[]` and ask "does any entry's `description` or `message` text name *this specific transition*, or the invariant it gates?" Then resolve. **(a) A `validation_rules[]` entry covers the transition** → signal is **suppressed for that transition; does NOT earn a section on its own**. The platform rejects the bad write with `{ "errors": [{ "code", "message" }, ...] }`; the recipe just surfaces that. The `code` is documented globally in the SKILL.md `Platform-enforced invariants` preamble; no per-JTBD recipe is needed for the gate. A candidate whose only merit is this row, in case (a), is dropped and listed under skipped. (Scripts that exist for *other* merit reasons may name the platform `code` in their stderr diagnostics so the agent surfaces a clean recovery hint; they must not duplicate the JsonLogic check.) **(b) §3 prose names the invariant but no matching `validation_rules[]` description does** → gap-tracked. The signal earns a section ONLY when the candidate also passes another merit signal (cascade, side-effect, etc.); the recipe enforces the gate client-side as a stopgap. **(c) Neither prose nor `validation_rules` names the invariant** → signal does not fire. | | **DB-unguarded invariant across FKs** | E.g. `features.release_id` and `features.product_id` must agree on product. The recipe must read both rows and check before patching. Cross-row constraints are out of scope for `validation_rules` (entity-level only), so this signal is **not** suppressed by the platform. | | **Cascade flow** | Flipping one parent row should flip a filtered set of children in the same logical operation (e.g. release-shipped → its planned/in-progress features → shipped). | | **Junction without uniqueness** | M:N junction without a DB-level unique constraint on the natural key. The recipe must dedupe-before-insert. | | **Materialization / handoff** | One entity row spawns rows in a different table (Pattern C). The order, FK back-pointers, and source-status flip are easy to get wrong. | | **Side-effect fields on transition** | `approved_at`, `committed_at`, `actual_release_date`, etc. that must be set in the same PATCH as the status flip, easy to forget. | | **Audit-trail read** | Audit-logged entity (`audit_log: true`) where "who/when changed X" is a likely user question. Worth a short recipe even though writes need no special handling. | | **Conditional-permission gate** | The entity's `conditional_permissions` index from Step 2 carries one or more entries (i.e. at least one `validation_rules` rule invokes `{"require_permission": ""}`). Unlike the basic "DB-unguarded lifecycle gate" row, this signal is **never suppressed** by the platform-enforces-it rule, the platform enforces the *check* but the calling agent still owns the *workflow*: detecting that the caller lacks the permission before the write attempt (cheap UX win), surfacing the rule's `message` cleanly on the throw, and proposing the right escalation path (which role typically holds the permission, who to hand off to). One JTBD per `(entity, permission_code)` pair, or one combined JTBD per entity when several conditional gates share the same approver role. Cross-reference the §8 step 1 description for the permission to know what role typically holds it. | | **Restrict-chained cleanup** | The entity appears in at least one other entity's `restrict_inbound` index (i.e. is the target of at least one `reference + restrict` inbound FK). Pattern J fires. The recipe walks the dependency tree of restrict-children, naming each one and providing the find-and-delete query shape, then performs the parent delete. The merit signal is the chain itself: a generic `use-semantius` `DELETE` against the parent will surface only one row's constraint failure per attempt, never the full chain; the recipe makes the order explicit. | | **Row-scoped read** | The entity appears in the `row_visibility_rules` index from Step 2 (i.e. carries a non-empty `Select rule`). Like the conditional-permission gate above, this signal is **never suppressed** — the platform filters rows from the result set, but the calling agent still owns the workflow of surfacing the limit to the user. **Critical (v2.2): the rule applies uniformly to every caller with `view_permission`.** A read recipe against a scoped entity must surface that as a uniform limit ("every caller sees only ``"), not as a tiered limit. If the analyst's model has resolved an architectural-decision §7 entry that names a documented broadening mechanism (option C separate-entity surface, option D Postgres `BYPASSRLS` role), the recipe can name it as the path to broader access; otherwise the broader-access path is "talk to a user with that role" and the recipe says so. **Never invent a `view_all_` permission bypass.** The signal earns a section when the entity is a target of meaningful read recipes (list, search, look up by non-id) — those recipes need a preamble noting the scope. Pure write recipes on the entity (insert, update with the id already known) are not affected and don't need a separate JTBD; the cross-cutting **Row-level read scope** preamble in the SKILL.md body covers them. Entities whose only operations against them are writes-by-known-id get the preamble entry but no per-JTBD section. | | **Conditional field UI state** | The entity has at least one field in the `dynamic_input_types` index. By itself, this is **not** a merit signal that earns a section: an `input_type_rule` is UI control only, the platform doesn't gate writes on it, and recipes that POST/PATCH bypass the UI entirely. The exception is the `conditional_required_fields` sub-index (UI rules that go `default → required` on a transition): those compose with Pattern A's existing "Side-effect fields on transition" signal and the housekeeping-field-appears-on-transition sub-shape above, and earn coverage *inside* the transition JTBD that fires the trigger. Cross-cutting documentation of every `input_type_rule` lives in the **Conditional field UI states** SKILL.md preamble (Step 5), not in per-JTBD sections — same posture as **Platform-derived fields**. | > **Trap, the most common defect:** when a candidate's only merit > signal is **Computed field** and the field is in `computed_fields`, > OR only **DB-unguarded lifecycle gate** and a `validation_rules[]` > entry covers the transition (matched by description), the candidate > is **dropped**, not earned. The platform owns the rule end-to-end; > a JTBD section would just restate what the SKILL.md preamble already > documents globally. List under skipped with a reason like > `pure CRUD; is platform-derived` or > `pure CRUD; transition is platform-enforced via `. The "Score > with RICE" anti-pattern is the canonical example: every input has a > `validation_rules` range check and `rice_score` is in > `computed_fields`, so the recipe is one PATCH and the platform > handles the rest, no JTBD section earns a place. If the only thing a candidate does is single-table CRUD with the platform defaults (no merit signals), drop it. List dropped candidates in the Step 4 summary as `skipped: pure CRUD against , calling agent uses use-semantius directly`. This is not a failure; it is the design. ##### Track platform-enforceable gaps While walking the merit table, maintain a side list `platform_enforceable_gaps` keyed by entity. Append an entry whenever the **Computed field** or **DB-unguarded lifecycle gate** signal fires **and** the entity's model block does not already capture the rule: - **Computed-field gap.** A field's §3 prose names a derivation (`(reach × impact × confidence) / effort`, "subtotal of line amounts", "days between open_date and close_date") and the entity's `computed_fields` array carries no entry whose `name` matches that field. Record `{entity, field, kind: "computed_field", evidence: ""}`. - **Lifecycle-gate gap.** The §3 prose for a status enum (or any field-level invariant) names a constraint ("only set X once Y is committed", "X cannot decrease", "X required when Y is `paid`") and no `validation_rules` entry on the entity encodes it. Record `{entity, field, kind: "validation_rule", evidence: ""}`. The detection is **conservative**: only fire when the §3 prose names the derivation or constraint explicitly. Do not infer rules the analyst did not write down — that is the analyst's job, not the skill-maker's. A gap by itself does **not** earn a JTBD section. A candidate still has to pass the merit test on at least one *other* signal (cascade, side-effect on transition, junction without uniqueness, materialization handoff, caller-populated label, etc.). When it does, the gap-tracked rule earns a stopgap recipe inside that JTBD until the analyst adds the matching `computed_fields` / `validation_rules` entry to the model. The gaps list itself is purely the Step 3 confirmation checkpoint, so the human can decide whether to pause and add the rule via the analyst skill, or accept the stopgap recipe. #### Pass 3, Classify each surviving JTBD into a file For each JTBD that passed the merit test, decide where its body lives. The default is **reference**. Inline and script are exceptions earned by specific shape. **Inline (kept in SKILL.md body).** Reserve for JTBDs whose entire recipe is one POST or PATCH with no read-first, no client-side composition, no branching. Rare; most JTBDs that earned a merit signal have at least one of these. If the inline body would exceed ~5 lines of recipe, promote to reference. **Script (`scripts/.sh`).** The decision rule for "script vs reference" is **one** test, not a checklist: > Does any branch in this recipe require the **agent** to ask the > **user** something before continuing? If no, it's a script. The script reads its parents, composes any labels internally, recomputes any stored values internally, validates preconditions, and either succeeds (exit 0) or refuses with a diagnostic message and non-zero exit. The agent invokes it with a small set of arguments (titles, emails, codes, dates) and checks the exit code; the script body never loads into context. What is *not* a judgment branch (these all stay in scripts): - Label composition. `feature_vote_label = "{user_full_name} -> {feature_title}"` is mechanical: read the parents, format the string, no agent involvement. The script reads the rows it composes from. - Computed values. `rice_score = (reach * impact * confidence) / effort` is mechanical: read current values, overlay caller's deltas, arithmetic, PATCH the result. Round to the column scale; if the inputs make the result undefined (effort null/zero), set the computed field to null and exit 0 with a diagnostic, do not exit non-zero. - Mechanical preconditions ("refuse if release_status is `released` or `cancelled`", "refuse if effort_score is null"). The script checks, exits 1 with a clear message, and the agent surfaces the message to the user. That is *not* the agent asking the user something; that is the script telling the agent it cannot proceed. - Dedupe-on-junction. "PATCH if the row exists, POST if not" is a fixed branch on what the read returned; the agent does not intervene. What *is* a judgment branch (these belong in references): - "Ask the user before rewriting a committed row's history." - "Ask the user before charging this work to an inactive cost center." - "Ask the user whether to abort or recreate when the parent was deleted." Anything that needs a yes/no from the user **mid-operation** is a reference. Everything else is a script. The script must also satisfy two structural requirements that follow from being callable by the agent: - Idempotent: re-running with the same inputs is safe. Filter writes to "rows that still need the change", not "all rows in the parent set"; running twice is then a deterministic no-op on the second run. - Failure messages are diagnostic: name the step that failed and what the agent should tell the user (e.g. "step 1: feature '' not found, ask the user for the correct title"), so the agent can recover or escalate without re-reading the script body. **Reference (`references/<jtbd-slug>.md`).** Use this when the recipe has a judgment branch that needs the agent to mediate a user confirmation (the test above). The reference file owns the read-first calls, the branching prose, the user-prompt phrasing, and the long failure-mode discussion. The agent loads the reference only when it enters the JTBD; reading it is part of the operation. A JTBD's classification controls the SKILL.md template body for that section: inline carries the full recipe; reference and script carry only Triggers, Inputs, a one-line Recipe pointer, Validation, and a terse Failure-modes summary, with the long body living in the linked file. The classification belongs in the Step 10 summary so the user can sanity-check it. **Pass 3 is mandatory. "Inline" is a rare exception, not a default.** Every merit signal that earned a JTBD a section in Pass 2 (caller-populated label, computed field, DB-unguarded lifecycle gate, cascade flow, junction without uniqueness, materialization handoff, side-effect fields on transition) is *also* a reason the JTBD belongs in `references/` rather than inline. If you find yourself classifying every surviving JTBD as inline, you have not classified, you have skipped Pass 3. Re-read the merit table: each signal's recipe needs read-first, branch, compose, recompute, or cascade logic that runs to ~30+ lines including comments. None of that fits the inline criterion (≤5 lines, no branching, no composition). Concrete shape of a healthy classification, derived from prior generations applied with the sharpened "user-prompt branch" rule: - A skill with 5–10 JTBDs typically produces 3–5 reference files, 3–5 script files, and 0–2 inline JTBDs. A run that produces zero reference files is suspicious (most domains have at least one user-confirmation branch); a run that produces zero script files is almost always a misclassification (most domains have at least one cascade or pure-mechanical operation). - The ratio of reference + script to inline should be at least 3:1. If your classification gives you 7 inline + 1 reference, walk back through the merit table and force yourself to name, for each inline JTBD, why it has *zero* of: read-first, label composition, computed recompute, cascade, branching. If you cannot, the JTBD is at least a reference, possibly a script. - Cascade-shaped JTBDs (Pattern A side effects + Pattern C materialization, e.g. "ship the release" with a feature-status sweep) are scripts, unless they carry a user-confirmation branch. - Dedupe-on-junction JTBDs (Pattern junction-without-uniqueness, e.g. "vote on a feature", "tag a feature") are scripts. The label composition is mechanical and the script reads the parents to compose; do not promote to reference just because the label is caller-populated. - Computed-field recompute JTBDs (e.g. "score with RICE", "recalculate total amount") are scripts. The arithmetic is mechanical; the script reads current values and writes the new ones in one PATCH. - Lifecycle-gate JTBDs (Pattern A, e.g. "triage", "schedule", "approve") are references when at least one transition needs a user confirmation, scripts otherwise. #### Sizing After filtering, aim for **5–10 sections** plus the optional `Common queries` appendix. - Fewer than 5 sections after filtering: the model may be too thin to justify a domain skill. Tell the user; ask whether to ship it anyway or extend `use-semantius` with a glossary file instead. - More than ~10 sections after filtering: a single skill that long under-triggers, the description gets diluted and the matcher loses signal. Run Step 3.5 (Cluster check) below; it inspects the entity graph for natural cut points and proposes a split when one exists. If no clean split surfaces, push back to the user: drop the lower-merit candidates, or split the model file itself. Proceed with one oversized skill only if the user confirms. ### Step 3.5, Cluster check After Pass 3 classifies every JTBD, before presenting the confirmation checkpoint, inspect the model for natural sub-domain cuts. Most models generate cleanly as one skill; a minority (typically ITIL-shaped or multi-process domains) read as two or three loosely coupled sub-domains stitched into one model file. A skill that spans loose sub-domains under-triggers for the same reason an oversized skill does, the description has to cover too many vocabularies and the matcher loses signal. Run this step on **every** generation, regardless of JTBD count. The size-based threshold in Sizing is one trigger for splitting, not the only one; a 7-JTBD model split into two clear clusters of 4 and 3 still benefits from being two skills. #### Compute the cluster signal 1. **Build an undirected graph.** Nodes are the model's entities (§3). Edges are FK relationships from §4, weighted by count (multi-FK pairs get higher weight). Skip edges to ubiquitous hub entities, `users`, `departments`, and any §6 cross-model targets, they connect to almost everything and obscure the real clustering. 2. **Find candidate clusters.** A simple greedy modularity walk is enough; you do not need a full community-detection library here. Start with each entity in its own cluster and merge the pair whose merger most improves the within/cross edge ratio until further merges stop improving it. Aim for 2–4 clusters; stop merging when only one cluster remains or when the next merge would drop the ratio. 3. **Assign each JTBD to a cluster.** A JTBD lives in the cluster that owns the majority of its touched entities (parents, children, joined targets in lookups). JTBDs that span clusters (e.g. one that joins entities from both) count as cross-cluster and are flagged separately. 4. **Compute the cut score.** `cross_edges / (within_edges + cross_edges)`. Lower is better, a model with two genuine sub-domains scores < 0.20; a tightly interlocked single-domain model scores > 0.40. #### Surface a split proposal only when all of these hold - ≥ 2 clusters with ≥ 3 JTBDs each. (Smaller clusters are not skill-shaped; fold them into the larger neighbor.) - Cut score < 0.25. - ≤ 2 cross-cluster JTBDs. More than that means the recipes routinely span both halves and splitting forces the calling agent to load both skills anyway, defeating the point. - Each cluster has its own distinct trigger vocabulary (the cluster's JTBD verb-phrases would not naturally appear in the other cluster's description). If the same verbs (`approve`, `assign`, `close`) dominate both clusters, the matcher will thrash even with a split. If any condition fails, the model generates as one skill and Step 3.5 produces no extra prompt. #### When all conditions hold, propose the split Add this to the Step 3 confirmation checkpoint as a fourth list, **before** writing files. Example shape: > The entity graph splits cleanly into two clusters: > > **Cluster A: `<slug>-incidents`** (entities: incidents, > incident_comments, incident_categories; JTBDs: log incident, > resolve incident, link to problem, post comment). > > **Cluster B: `<slug>-changes`** (entities: changes, change_tasks, > change_approvals; JTBDs: submit change, approve change, schedule > change, execute change). > > Cross-cluster: 1 JTBD (problem-resolved-by-change) would need > both skills loaded. > > Cut score: 0.12. Each half has its own trigger vocabulary > ("incident / ticket / outage" vs "change / deployment / > maintenance window"). > > **Generate as one skill `<slug>` (default), or split into > `<slug>-incidents` and `<slug>-changes`?** The default is **one skill** even when the proposal fires. Splitting fragments shared cross-cutting rules, doubles the README/glossary maintenance burden, and surprises users who installed "the X skill" and find half their work routes elsewhere. Only split when the user explicitly confirms. #### What changes when the user accepts a split - Each cluster becomes its own folder under `<skills-root>/`, with its own SKILL.md, README.mdx, references/, and scripts/. - Each SKILL.md's description mentions the sibling skill ("loads alongside `<sibling-slug>` for cross-process work like X") so the matcher knows the pair composes. - Cross-cluster JTBDs go in **whichever cluster owns the action's primary verb**, not duplicated. If "resolve a problem with a change" lives in `<slug>-problems` (because the verb is "resolve"), `<slug>-changes` only needs a one-line note that problem-resolution writes to changes; the recipe lives in the problems skill. - The `semantic_model:` provenance key on every generated SKILL.md still points to the same source slug (e.g. `itsm`); the model file is shared, the skills are split. #### Confirmation checkpoint Present three lists to the user (four when Step 3.5 fired a split proposal; five when `platform_enforceable_gaps` is non-empty): 1. **Sections**, the JTBDs that earned a place (one bullet each, with the merit signals that justified them). 2. **Common queries**, the cube queries that go in the appendix. 3. **Skipped**, Pass-1 candidates that failed the merit test, with the reason. The user may disagree and ask to add some back. 4. **Split proposal** (only when Step 3.5's conditions all held), the cluster breakdown and the one-skill-vs-split question. Default to one skill; only split when the user explicitly confirms. 5. **⚠️ Platform-enforceable gaps detected** (only when `platform_enforceable_gaps` is non-empty), one bullet per gap listing the entity, the field, the kind (`computed_field` or `validation_rule`), and a short quote of the §3 prose evidence. Frame as a question, not a command: > The model documents these rules in §3 prose, but the entity's > `computed_fields` / `validation_rules` blocks do not encode them. > A recipe-level stopgap will be baked into the generated skill, > but the platform will not enforce the rule on writes that bypass > the skill (direct CLI calls, other skills, future migrations). > > - **`features.rice_score`** (computed_field): §3 says > *"(reach × impact × confidence) / effort"*. No > `computed_fields` entry derives `rice_score`. > - **`features.release_id`** (validation_rule): §3 says > *"null until scheduled, …commitment is derived (status ∈ > {planned, in_progress, shipped} ⇒ committed)"*. No > `validation_rules` entry gates `release_id` against status. > > **Recommended:** pause this skill-maker run, route to the > `semantic-model-analyst` skill (Audit / Extend mode) to add the > matching `computed_fields` / `validation_rules` blocks, redeploy > via `semantic-model-deployer`, then re-run skill-maker. The > regenerated skill will surface the platform-derived fields and > error codes instead of baking client-side recipes for them. > > **Or:** proceed and accept the stopgap recipes. Pick a route. Default is to surface the gap and let the user decide; do not silently proceed past the checkpoint when this list is non-empty. If the user picks "proceed", the run continues to Step 4 with the JTBDs intact; if they pick "pause", stop the run and tell them which skill to invoke next. Wait for confirmation before writing files. This is the only human checkpoint. ### Step 4, Audit existing artifacts If `<skills-root>/<modelslug>/` already exists from a prior generation, read every file under it and check for **drift** against (1) the current source model, (2) the current generation's plan, and (3) the current platform conventions. The audit is **read-only**; nothing is rewritten in this step. Findings go into the Step 10 summary, and the user decides whether to regenerate flagged files in Step 5–7. Skip this step entirely on a fresh generation (target folder does not exist or contains only a stale `SKILL.md` with no `references/` or `scripts/`). On a fresh run, there is nothing to audit; everything gets written in Steps 5–8. #### Model drift is the first thing to check The generated skill is a frozen snapshot of the source model at generation time. The model can move between generations, an analyst can rename a `singular_label`, swap an enum value, add a `computed_field`, simplify the §1 narrative, redraw the mermaid diagram, or close out a §7.2 future-consideration. Any of those changes leaves baked content stale. Detect drift **before** running the artifact-shape checks below; a stale glossary or recipe is worse than a non-canonical script. The audit re-parses the source model file at `MODEL_PATH` (same parse Step 2 does) and diffs the resulting facts against what is baked into the generated files: - **README `## Semantic model` mermaid block**: byte-diff against the model's §2 mermaid block. Any difference is a defect. - **README body §1 paragraph(s)**: byte-diff against the model's §1 narrative. The README copies §1 verbatim; a mismatch means the analyst rewrote §1 (or the generator paraphrased instead of copying). Defect. - **SKILL.md domain glossary**: every entity in §2 / §3 should appear in the glossary table with its current `singular_label`, and no extra entities should appear. Add / remove / rename = defect. - **SKILL.md "Key enums"**: every enum the model declares (§5 plus per-entity `enum` fields) and every value within each enum should appear; no extras. Defect on any add / remove / rename / reordering of values that recipes branch on. - **SKILL.md "Platform-derived fields" preamble block**: must match the union of `computed_fields[].name` across every entity, with the model's `description` text intact. Defect on any add / remove / rename. - **SKILL.md "Platform-enforced invariants" preamble block**: must match the union of `validation_rules[].code` across every entity, with the model's `message` and `description` intact. Defect on any add / remove / rename. - **SKILL.md "Platform-enforced permissions" preamble block** ): must match the `conditional_permissions` index built in Step 2 (i.e. every `validation_rules` rule whose JsonLogic invokes `{"require_permission": "<code>"}`). Every `(entity, rule_code, permission_code)` tuple in the index must appear in the preamble with the rule's `message` and the §8 step 1 description of the permission. Defect on any add / remove / rename. Skip the section entirely when the index is empty. - **SKILL.md "Restrict-cleanup chains" preamble block** ): must match the `restrict_inbound` index built in Step 2. Every entity that is the target of at least one `reference + restrict` inbound FK must appear with its cleanup-children listed in dependency order. Drift signals: an entity that the model now declares with a flipped `parent ↔ reference` FK (per the v1.13 permission-scope override rule) but whose preamble entry hasn't been regenerated; or a restrict-inbound row in the model that the preamble fails to list. Skip the section entirely when no entity has restrict-inbound edges. - **SKILL.md "Row-level read scope" preamble block**: must match the `row_visibility_rules` index built in Step 2. Every entity that declares a non-empty `Select rule` must appear with the scope's plain-English gist (from the rule's `description`, the entity's §3 prose, or a fallback paraphrase of the JsonLogic intent). The gist must describe the **uniform per-row predicate** that the platform applies to every caller with `view_permission`; it must NOT promise a `view_all_<plural>` permission bypass unless the model file's §7 architectural-decision entry explicitly resolves the broadening mechanism (option C separate-entity surface, option D Postgres `BYPASSRLS` role attribute) and the preamble names that mechanism. **Drift signals (defects):** (a) an entity that the model now declares with a new / removed / modified `Select rule` whose preamble entry hasn't been regenerated; (b) **a preamble entry that names a permission bypass the model file does not resolve in §7** (the canonical v2.2 defect — the prose claims a bypass the platform cannot honor); (c) a preamble entry whose gist describes a *tiered* read pattern but whose underlying `Select rule` JsonLogic encodes a uniform filter (drift between intent and rule). Skip the section entirely when `row_visibility_rules` is empty. - **SKILL.md "Conditional field UI states" preamble block** (analyst v2.2+): must match the `dynamic_input_types` index built in Step 2. Every field that declares a non-empty `input_type_rule` must appear with the rule's `description` (or the JsonLogic's plain-English gist), grouped by entity. Drift signals: an `Input type rules` entry that the model adds, removes, or whose trigger condition the model rewrites without a matching preamble change; a preamble entry whose field no longer exists in §3 (the analyst dropped the field but the preamble lingers). Skip the section entirely when `dynamic_input_types` is empty. - **Per-JTBD coverage of `conditional_required_fields`**: for every entry in the `conditional_required_fields` sub-index built in Step 2 (a field whose `input_type_rule` flips `default → required` on a transition), the transition JTBD that fires the trigger condition must include the dependent field in its PATCH body as a side-effect of the trigger. A transition recipe that sets the trigger field without the paired side-effect field is a drift defect — the rule was added to the model after the recipe was written, or the generator missed it. Severity: defect (regenerate the JTBD's reference / script). - **SKILL.md "What this skill does NOT do" inlined §7.2 list**: must match the model's current §7.2 bullets. Defect on any add / remove / rename. (Bullets the user has paraphrased for readability are non-canonical, not defect; flag separately.) - **JTBD recipe field references**: every column a recipe writes (in inline bodies, references' Recipe blocks, or scripts) must exist on the entity in the current §3. A recipe writing a removed or renamed column is a defect. - **Audit-log mentions**: every entity SKILL.md / a reference claims is `audit_log: yes` (or `: no`) must agree with the current §3 entity declaration. Defect on mismatch. - **§6 cross-model hints**: every cross-model hint named in generated content (Guardrails, "What this skill does NOT do") should still be present in the model's §6. Defect on stale references. The drift check has its own severity row in "What to report" below. It runs **regardless** of whether the user invoked the skill-maker for a regeneration or a review, the model is the contract, and a review that does not re-resolve to the contract is incomplete. (The "review skill" call is exactly Step 4.) #### Artifact-shape checks (post-drift) After the drift check, walk every file in the skill folder (`SKILL.md`, `README.mdx`, `references/*.md`, `scripts/*.sh`) and apply the same checks the self-review (Step 9, Principle 0) applies to freshly written files. The point is symmetry: if Principle 0 would reject a file the generator just wrote, it should also flag the same file sitting on disk from a prior run. Concretely: - **Read patterns.** Every `semantius call ... GET ...` is either `--single` (one row required) or array-default (zero or many rows acceptable). The flag must be present iff the lookup is by `id`, unique column, or composite-unique key. A unique-key read missing `--single` is non-canonical (still works, but uses the legacy two-guard pattern). - **Guard patterns** (scripts only). `--single` reads need only the exit-code guard; array reads need exit-code AND body inspection. A `--single` read with a redundant `grep -q '"id"'` follow-up is non-canonical. An array read with no body inspection is a defect. - **Response parsing** (scripts only). `--single` responses are bare objects (`grep -oE '"id":"..."'`, no `head -n1`, no `[0]`); array responses need `head -n1` or `[0]` indexing. A mismatch silently produces empty strings; flag it. - **`# expect:` annotations** (references only). Every GET, POST, PATCH, DELETE in the recipe carries an `# expect:` line naming the pattern (`--single` or array) and the action on failure. Missing annotations are defects. - **Cross-reference integrity.** Every `references/<slug>.md` linked from SKILL.md must exist on disk; every `scripts/<slug>.sh` mentioned in a SKILL.md `Recipe:` line must exist. Files on disk that aren't linked from SKILL.md are orphans (left over from a JTBD that no longer exists or was reclassified). - **Pass 3 alignment.** For each JTBD in the current generation's plan, the file on disk should match the new classification. A JTBD now classified `script` whose existing artifact is `references/<slug>.md` (or vice versa) needs migration; the audit flags the pair, the user picks the direction. - **Hardcoded literals.** Search every file for ISO timestamps, ISO dates, baked-in ids, and the generation year. These rot and should be placeholders. Same scan the self-review's Principle 1 runs on a fresh write. #### What to report (handed to Step 10) For each file with findings, produce one bullet: - `README.mdx: drift, body §1 paragraph mismatches the model's current §1 narrative. The analyst rewrote §1 to drop backticked identifiers; the README still has the old verbatim copy.` - `SKILL.md: drift, "Platform-derived fields" preamble lists 1 field; model's computed_fields union now has 2 (added features.days_open). Recipes will not warn against writing the new field.` - `SKILL.md: drift, "Key enums" lists feature_status values including 'parked'; model's §5 no longer declares 'parked'. Triage's Inputs table accepts a value that no longer exists.` - `cast-vote.sh: 4 reads use legacy two-guard pattern; --single would collapse each to one guard. Working but non-canonical.` - `triage-feature.md: 2 GETs missing # expect: annotations.` - `score-rice.md: classified `script` in current plan but exists as reference; needs migration.` - `tag-feature.md: orphan; no JTBD with this slug in current plan.` - `ship-release.sh: contains hardcoded date "2026-05-04"; should be a placeholder.` Group findings by file and by severity: - **"drift"** = the file no longer matches the source model; baked content is stale. Always recommend regenerating. - **"defect"** = the file is broken on its own terms (missing link target, structural shape failure, recipe writes a removed column). Recommend regenerating. - **"non-canonical"** = the file works but uses an outdated pattern; user decides whether to take the upgrade. - **"orphan"** = the file is no longer referenced from SKILL.md (its JTBD was reclassified or removed). User decides whether to delete or restore. The Step 10 summary surfaces these and asks the user how to proceed; **do not auto-rewrite in Step 4**. #### What the user can choose in Step 10 Three options the summary should offer: 1. *Regenerate flagged files* (Steps 5–7 rewrite them). Default for defects. 2. *Leave as-is*. Default for non-canonical findings on a file the user may have hand-edited. 3. *Per-file decision*. The user accepts some, rejects others. If the user opts to regenerate, the affected files are rewritten in Steps 6 (references) and 7 (scripts). Files not flagged for regeneration stay untouched even if their JTBD is in the current plan; the audit is what gates the rewrite, not the plan alone. #### Hand-edits The audit is conservative about hand-edited prose. References in particular get hand-edited (failure-mode wording, user-prompt phrasing). The audit flags non-canonical patterns but does NOT mark the file for forced rewrite; the user keeps custody. The defect categories that DO warrant a forced rewrite recommendation (prefixed "defect" in the summary) are: - A reference linked from SKILL.md that doesn't exist on disk - A script file that fails the structural shape check (empty, wrong shebang, missing `set -euo pipefail`) - Cross-FK invariants that contradict the current model (e.g. a reference recipe writes a column that no longer exists) Everything else is "non-canonical" and the user decides. ### Step 5, Write the consolidated SKILL.md The folder gets two files written in sequence: the agent-facing `SKILL.md` (this step) and the human-facing `README.mdx` (Step 8). Both are required output. Write the SKILL.md first because the README pulls its trigger phrases and JTBD titles from it. Use the template below. Resolve every reference at generation time (enum values, FK target tables, required-on-create field sets), the calling agent must not need to consult the semantic-model file to fill in fields. #### SKILL.md template ````markdown --- name: <modelslug> description: >- <One paragraph. Lead with the domain ("Use this skill for anything involving <system_name>, <one-line domain summary>"). List 4–6 realistic trigger phrases users might say, mixing entity names and task verbs (e.g. "create a lead", "convert opportunity to account", "report pipeline by stage"). Be slightly pushy, skills under-trigger by default.> semantic_model: <system_slug, e.g. product_roadmap (no path, no .md extension)> --- # <system_name> The H1 here is **`system_name` verbatim**. No "Skill" suffix, no "domain" prefix, no rewording. The file is named `SKILL.md`, so the agent loading it already knows it is a skill, repeating "Skill" in the heading is noise. Examples: `# Applicant Tracking System`, `# Workforce Planning`, `# Customer Relations`. (The README.mdx H1 follows a different rule, the Title grammar in Step 8, because the catalog needs the "Skill" suffix to disambiguate cards. Do not confuse the two.) This skill carries the domain map and the jobs-to-be-done for <system_name>. Platform mechanics, CLI install, env vars, PostgREST URL-encoding, `sqlToRest`, cube `discover`/`validate`/`load`, and schema-management tools, live in `use-semantius`. Assume it loads alongside; do not re-explain CLI basics here. If a task is purely about defining schema, managing permissions, or running ad-hoc queries against tables you already know, call `use-semantius` directly, going through this skill adds nothing. **Module type**: <`domain` or `master`, copied from frontmatter `module_type` (default `domain` when absent)>. A `master` module is a neutral host for shared / master data (e.g. vendors, currencies, departments) consumed by multiple domain modules via cross-module `permission_hierarchy` rows tagged `origin = "model_master"`. Writes to entities in a master module have cross-domain visibility: every consuming domain module sees the write through the bridge. The recipes in this skill treat master entities the same as domain entities at the CLI level; the only practical difference is the "shared across domains" guardrail surfaced on each write recipe touching one. Skip this line entirely when the model is a plain domain module. **Shared master entities** (entities authored under this domain module that the analyst flagged as classic master concepts via the `**Shared master cluster:** <cluster>` annotation; writes to these entities are likely candidates for promotion to a master module on re-deploy, and the live module may already have routed them through a master via the deployer's Stage 2d Branch B path. Recipes that touch them include a one-line note that the data is shared across the named cluster): <list each entity in the `master_cluster_by_entity` index from Step 2. Skip the section entirely when no entity in the model carries the annotation AND the module itself is not `module_type: master`.> - `<table>` is part of the `<cluster>` shared master cluster. **Auto-managed fields** (set by Semantius on every table; never include in POST/PATCH bodies): `id`, `created_at`, `updated_at`. The `label_column` field is **required on insert and caller-populated** on every entity unless the model explicitly says it is auto-derived , this includes junction tables like `<junction>` and sub-entities like `<sub-entity>`, where the recipe must compose the value (see each JTBD for the composition rule). Do not omit `*_label` from POST bodies. **Platform-derived fields** (set by the platform's per-entity `computed_fields` triggers on every INSERT/UPDATE; **never include in POST/PATCH bodies, the platform overwrites caller payloads**: <list each `computed_fields[].name` from the model, grouped by table and one-line description copied from `computed_fields[].description`. Skip the section entirely when no entity in the model declares `computed_fields`.> - `<table>.<field>`: <description from the model's `computed_fields[].description`> **Platform-enforced invariants** (entity-level `validation_rules` triggered on every INSERT/UPDATE; the platform rejects writes that violate them with `{ "errors": [{ "code", "message" }, ...] }`. The recipes here do NOT pre-validate these; they surface the platform's error to the user verbatim if the write fails): <list each `validation_rules[].code` from the model, grouped by table, with the `message` and (if present) `description`. Skip the section entirely when no entity in the model declares `validation_rules`.> - `<table>` rule `<code>`: <message>. Why: <description, when present>. **Platform-enforced permissions** (rules whose JsonLogic invokes `{"require_permission": "<code>"}`; the platform throws when the caller lacks the named permission, surfacing the rule's `code` and `message` as a validation failure. The recipes that hit these gates name the permission up-front so the calling agent can either (a) confirm the caller holds it before attempting the write, or (b) propose handing off to a user who holds it instead of hitting the throw blind): <list each `(entity, rule_code, permission_code, role-hint)` tuple from the `conditional_permissions` index built in Step 2. Pull the `role-hint` from §8 step 1's description of the permission. Skip the section entirely when `conditional_permissions` is empty.> - `<table>` rule `<code>` requires `<permission_code>` (`<role-hint from §8>`): <message>. Why: <description, when present>. **Restrict-cleanup chains**; inbound `reference + restrict` FKs that block deletion of the target entity until children are explicitly cleaned up first. The calling agent attempting to delete a listed entity must walk the named children first, in the order given, or the platform will reject the DELETE with a foreign-key constraint error. Every listed chain corresponds to a Pattern J "delete / archive" JTBD in this skill): <list each entity that has at least one inbound `reference + restrict` edge per the `restrict_inbound` index from Step 2. For each entity, list the restrict-children in dependency order (children of children first if any chain deeper). Skip the section entirely when no entity in the model has restrict-inbound FKs.> - Deleting `<table>` requires cleaning up first: `<child_table>` (via `<fk_field>`), `<child_table>` (via `<fk_field>`), … See the `delete-<table>` JTBD for the recipe. **Row-level read scope**; per-row visibility filters set on the entity via `select_rule`. The platform applies an RLS policy on every read. **Critical: the rule applies uniformly to every caller with `view_permission`** — the platform evaluates the JsonLogic body per row with `$today` / `$now` / `$user_id` as reserved variables; there is no documented mechanism by which holding a specific permission causes the rule to be skipped for that caller. Recipes against a scoped entity must surface the per-row predicate as a **uniform** limit, not a tiered one. If the model file's §7 carries an explicit architectural-decision entry naming a documented broadening mechanism (a separate cube view / entity surface admins read, or a Postgres role with `BYPASSRLS` provisioned outside Semantius), name that mechanism here so the recipe can route to it; otherwise the broader-access path is human escalation, not a magic permission grant.): <list each entity in the `row_visibility_rules` index from Step 2. For each entity, give the scope in plain English (from the rule's `description`, the entity's §3 prose, or a paraphrase). Name the documented broadening mechanism ONLY when the model file's §7 explicitly resolves it; otherwise omit the broadening line. Skip the section entirely when `row_visibility_rules` is empty.> - `<table>`: every caller with `view_permission` sees only rows where <plain-English uniform predicate>. <Optional: "Broader read access for `<role>` is provisioned via `<mechanism named in model §7>`" — include only when the model's §7 names the mechanism.> > **Never write a line like "callers holding `<slug>:view_all_X` bypass the > filter".** That mechanism is not documented in the current Semantius > platform spec. A preamble that promises it generates recipes that look > right but silently leak access OR silently deny access (depending on > how the calling agent reasons). The audit catches this as the canonical > v2.2 defect. **Conditional field UI states**; per-field UI mode overrides set via `input_type_rule`. The platform evaluates the rule client-side at form-render time and overrides the field's static `input_type` for the current record. The rule does NOT gate writes — recipes that POST/PATCH the entity bypass the form entirely and can set any field at any time — but two patterns matter for recipe shape: (a) when a rule flips a field's effective mode to `required` on a sibling-field transition, the transition's recipe must set that field in the same PATCH (else the form would have rendered it `required` but the API call leaves it null); (b) when a rule flips a field's effective mode to `readonly` after a terminal state, recipes that update the entity after that state should not write the field. Cross-reference with `validation_rules` — when the server-side rule enforces the same invariant, the platform rejects the bad write with a structured `code` / `message`; surface that in the JTBD's Failure modes block): <list each field in the `dynamic_input_types` index from Step 2, grouped by entity. For each, name the field, the trigger gist (from the rule's `description` or the JsonLogic's plain-English summary), and the resulting effective `input_type`. Skip the section entirely when `dynamic_input_types` is empty.> - `<table>.<field>`: <trigger gist, e.g. "hidden until status=approved, then readonly"> (paired server-side rule: `<validation_rules.code>` — or *"no paired server-side rule; UI-only behavior"*). --- ## Domain glossary <One short table. Pull `singular_label`s, table names, and a one-line "what it represents" for each entity. Group related entities together (e.g. "Pipeline: leads, opportunities, accounts"). Skip junction tables unless a job touches them directly. Do not duplicate FK targets here , each JTBD's reference file owns its own FK assumptions.> | Concept | Table | Notes | |---|---|---| | Lead | `leads` | Inbound or sourced contact, not yet qualified | | Opportunity | `opportunities` | Qualified deal in the pipeline | | Account | `accounts` | Closed-won opportunity or imported customer | ## Key enums <Only enums that gate JTBDs. Skip purely informational ones. Format: table.column → values, with the typical lifecycle path marked.> - `leads.lead_status`: `new` → `contacted` → `qualified` | `disqualified` - `opportunities.stage`: `prospecting` → `proposal` → `negotiation` → `closed_won` | `closed_lost` ## Cross-cutting data rules <Only facts that span 2+ JTBDs in load-bearing ways belong here. Per-FK shape, per-junction uniqueness, and audit-logging notes go in the JTBD's reference file, not here. This section is often empty or just 1–2 lines; that is correct, not a sign of incompleteness. Examples of facts that *do* belong here: - A naming convention several recipes rely on (e.g. "all `*_at` fields are server-set on insert; never include them in POST bodies"). - A platform-wide constraint that constrains every recipe's write pattern (e.g. "rows soft-deleted via `is_active=false` are still visible to `read_*`; recipes filter on `is_active=eq.true` unless the JTBD explicitly wants the full history"). If you have nothing to put here, omit the section.> ## When the runtime disagrees with the recipe The FK shape and audit-logging facts in each JTBD's reference file are baked in at skill-generation time. The live schema can drift, admins can add a unique index, drop an FK, or toggle audit-logging on a table without regenerating this skill. The recipes are not self-correcting on their own, but the agent has an escape hatch. When a recipe gets a `409 Conflict`, `422 Unprocessable Entity`, or any other write failure the JTBD's reference file did not predict, the recovery move is **read the live schema, then decide**: ```bash # What FKs does this entity actually have right now? semantius call crud read_field '{"filters": "entity=eq.<entity_id>"}' # Or, more targeted, what does field <name> reference today? semantius call crud read_field '{"filters": "entity=eq.<entity_id>,name=eq.<field_name>"}' ``` If the live shape contradicts the recipe's assumption (e.g. a unique constraint exists where the recipe expected a free-form junction), abort with a clear stderr message naming the drift, do not silently "fix it up" with extra writes. Then surface to the user that the skill is out of date and recommend regenerating via `semantius-skill-maker`. Drift recovery is the user's call, not the agent's. ## Lookup convention <This block lives at the SKILL.md top level, not per-JTBD, so the agent reads it once per trigger and applies it everywhere. The recipe files under `references/` may name the column they resolve, but they do not re-explain `wfts` vs `eq`.> Semantius adds a `search_vector` column to searchable entities for full-text search across all text fields. Use it whenever the user passes a name, title, email, or description, not a UUID: ```bash semantius call crud postgrestRequest '{"method":"GET","path":"/<table>?search_vector=wfts(simple).<term>&select=id,<label_column>"}' ``` Use `wfts(simple).<term>` for fuzzy text searches; never `ilike` and never `fts`, they bypass the search index and mismatch the platform convention. Field-equality (`<column>=eq.<value>`) is the right tool for a *different* job: filtering on a known-exact value. Use it for UUIDs, FK ids, status enums, and unique columns whose values the caller already knows verbatim (e.g. `tag_name`, `user_email`, `release_name`, `cost_center_code`). The two patterns are not in competition: `wfts(simple)` resolves a fuzzy human input to a row; `eq` selects rows whose column exactly equals a known value. If a lookup returns more than one row, present the candidates and ask. If zero, ask the user to clarify rather than guessing. ## Timestamps in recipe bodies <Top-level rule, named once here, never restated per JTBD.> Every `*_at` field, `*_date` field, or other moment-of-action value in a recipe body is a placeholder the calling agent fills at call time, not a literal copied from the example. The Recipe templates use `<current ISO timestamp>` and `<today's date, YYYY-MM-DD>`; do not copy those strings into a real call. This applies in SKILL.md, in every reference file, in the Common queries appendix, and in any script the calling agent invokes. --- ## Jobs to be done <One H2 per JTBD. Each section follows the structure below. Order sections by typical lifecycle (create → progress → close → report), not alphabetically.> ### <Job title, verb phrase> **Triggers:** `<phrase 1>`, `<phrase 2>`, `<phrase 3>` **Inputs:** | Name | Required | Notes | |---|---|---| | `<input>` | yes/no | <where it comes from; resolved by `<column>=eq.<value>` if exact, `search_vector=wfts(simple).<term>` if fuzzy> | The Inputs table must be **internally consistent with the routing rules below**: do not list a status value as an accepted input here and then say "for that value, route to JTBD Y". If a value belongs elsewhere, drop it from this table. **Recipe:** see [`references/<jtbd-slug>.md`](references/<jtbd-slug>.md). *(Reference shape, used when the JTBD was classified `reference` in Step 3 Pass 3. The full recipe body, lookup-then-compose-then-write, including any branching, label composition, and computed-value recompute, lives in the linked file. Do not paste it here.)* *(Script shape, used when the JTBD was classified `script`:)* **Recipe:** run `scripts/<op-slug>.sh <arg1> <arg2>`. The agent invokes; do not paste the script body here. Exit `0` on success, non-zero with the failed step on error. *(Inline shape, only when classified `inline` in Pass 3, ≤5 lines of recipe, no branching:)* **Recipe:** ```bash semantius call crud postgrestRequest '{"method":"POST","path":"/<table>","body":{...}}' ``` **Validation:** <2–3 short post-conditions, only the ones that have actually been broken in practice. The reference file may carry deeper validation; this list is what an agent skimming the SKILL.md needs to sanity-check the call.> **Failure modes:** <1–2 most-likely failures, each paired with a *recovery action*. Long lists belong in the reference file's extended failure-modes section; here, surface only what an agent needs to bail out cleanly. Examples: - `409 on <table>.<column>` (uniqueness) → row already exists; PATCH the existing row instead. - FK violation on `<column>` → the parent was deleted; ask the user whether to recreate or abort.> --- ### <next job…> … --- ## Common queries <Optional appendix from Pattern I, pre-shaped cube queries for reporting tasks. These are *not* JTBDs; they're examples the calling agent can adapt. Open with one note, then 3–5 query blocks.> Always run `cube discover '{}'` first to refresh the schema. Match the dimension and measure names below against what `discover` returns , field names drift when the model is regenerated, and `discover` is the source of truth at query time. ```bash # Pipeline by stage (count + total amount) semantius call cube load '{"query":{ "measures":["opportunities.count","opportunities.sum_amount"], "dimensions":["opportunities.stage"], "order":{"opportunities.sum_amount":"desc"} }}' ``` <…2–4 more representative queries, each with a one-line title comment.> --- ## Guardrails <Domain-specific rules the calling model should never violate. Each rule should appear here *or* in the relevant JTBD's failure-modes, not both. Pull from §7.1 of the model (resolved blockers / explicit constraints) and from the merit signals that triggered each JTBD. Examples: - Never PATCH `opportunities.stage` directly to `closed_won` without setting `closed_date` and `won_amount` in the same call. - `accounts` rows are only created via the close-won flow, never insert directly. - `*_status` flips in this domain are not DB-guarded; always read current status before writing. - Junction labels are caller-populated, see each junction JTBD for the composition convention.> ## What this skill does NOT do - Schema changes, use `use-semantius` directly. - RBAC / permissions, use `use-semantius` directly. - One-off seed data, write a script, don't bake it into a JTBD. - <Inline the bullet list of unbuilt features here. Pull each item from §7.2 "Future considerations" of the model at generation time and write it as a plain bullet, do *not* cite "§7.2" in the SKILL.md, the calling agent has no way to look it up. If §7.2 is empty or missing, drop this bullet entirely.> ```` #### What goes into each recipe, concretely When you bake a recipe, **resolve every reference**: - **Enum values**, copy verbatim from §5. Write `"stage":"closed_won"`, not `"stage":"<terminal value>"`. - **FK fields**, list by name with target table; if the agent passes a human-friendly value (an email, a code), the first recipe step is the lookup that resolves it to an id, using the `wfts(simple)` pattern above for searchable entities. - **Timestamps and dates**, never hardcode a date or timestamp literal in a recipe. The model file is read once at generation time but the recipes run weeks or years later; a baked-in `"2026-05-01T10:30:00Z"` silently corrupts every future call. For fields like `voted_at`, `posted_at`, `submitted_at`, `actual_release_date`, `closed_date`, always render the value as a placeholder the calling agent fills at call time, `"<current ISO timestamp>"` or `"<today's date, YYYY-MM-DD>"` , and add a one-line note in the recipe: *"`posted_at`: set to the current timestamp at call time; do not copy the example value."* This applies to every example body in the SKILL.md, including the Common queries appendix. - **Caller-populated label fields**, when a `label_column` is required but not auto-derived (the model marks the field as required with no default; common on junction tables and sub-entities like `comments`), call this out *both* in the glossary's "auto-managed fields" note *and* in each affected JTBD. The default Semantius behavior is that `id`, `created_at`, `updated_at` are auto-managed, but `label_column` is **not** auto-managed when the entity declares it as a required caller-populated field, the recipe must compose and POST a value. Word the auto-managed-fields note carefully so an agent skimming the glossary doesn't conclude it can omit `*_label` from POST bodies. - **Required-on-create field sets**, the model's `Required` column is intent, not platform-enforced. Spell out the business-required fields per JTBD; they often differ from create vs update. - **Audit-logged entities**, Semantius handles audit rows automatically on writes; recipes don't manage them. The non-obvious case is *reading* the audit trail. If the merit test surfaced an audit-read JTBD, the recipe is a single GET against the audit endpoint with the entity id , see `use-semantius` `references/crud-tools.md` for the path shape. - **Platform-derived fields (`computed_fields`)**, the platform writes these on every INSERT/UPDATE and overwrites whatever the caller sent. Recipes must **never include them in POST/PATCH bodies**, and must not re-derive them client-side. After a write that touches the inputs (`reach_score`, `impact_score`, `confidence_score`, `effort_score` for a RICE-derived `rice_score`), the recipe's "Validation" block should **read back** the row and assert the derived field has the expected value, that's the only place the formula is restated, and only to spot-check that the trigger fired. - **Platform-enforced invariants (`validation_rules`)**, the platform rejects bad writes with a structured `{ "errors": [...] }` body and a 4xx status. Recipes must **not pre-validate** these, duplicating the rule client-side is brittle (the rule can change in the platform without a recipe regen) and surfaces the same error twice on bad input. Instead, the JTBD's `Failure modes` block names each platform `code` the user is likely to hit and the recovery action: *"`code: release_only_when_committed`, the user tried to attach a release before the feature is committed; tell them to triage the feature to `planned` first, then retry."* The `code` is the i18n binding key, never paraphrase it. - **Platform-enforced permissions (`require_permission` rules)**, the platform throws when the caller lacks the named permission, and the throw lands as a regular `validation_rules` failure (same `code` / `message` shape, same 4xx response). Recipes here differ from the generic "don't pre-validate" rule above: it is **cheap and high-value** for the recipe to **pre-flight the permission check** by reading the caller's role-permissions before attempting the write. The point is not to duplicate the platform's enforcement (the platform is the source of truth, and the recipe still surfaces the throw verbatim if the pre-flight is wrong) but to give the calling agent a chance to *avoid the failure entirely* by handing off to a user who holds the permission, or by escalating to confirm. The recipe shape is: (1) read the conditional-permission row from `Platform-enforced permissions` preamble, naming the gate, the permission code, and the role-hint; (2) if the caller is the current user and they lack the permission, **stop and ask** ("this transition requires the `<permission_code>` permission, typically held by <role-hint>; do you want to hand off, or proceed as the user who is signed in?"); (3) if the caller is acting on behalf of a specific user, surface who that user is and confirm they hold the permission before proceeding; (4) the JTBD's `Failure modes` block names the platform `code` and the recovery action just like a regular invariant. Family-13 owner / manager edit gates use the same shape: pre-flight by reading the record's owner field against the caller's `$user_id`, fall back to `require_permission` of the override role only when ownership doesn't match. - **1:1 / unique constraints**, flag in **Failure modes** with the exact 409 condition *and* the recovery action (PATCH the existing row, pick a different parent, etc.). - **Row-scoped reads (`select_rule`)**, the platform filters rows from every read of a scoped entity via an RLS policy. **The rule applies uniformly to every caller with `view_permission`.** Three recipe shapes apply: - *Read recipes against a scoped entity* lead with a one-sentence visibility callout pulled from the **Row-level read scope** preamble ("every caller with `view_permission` sees only rows where `<plain- English predicate>`; rows outside the predicate are filtered out at the RLS layer regardless of the caller's role"). Recipes that *enumerate* the entity to make a decision ("are there any open tickets?") need this callout most loudly — a missing row is indistinguishable from no-such-row, and a recipe that concludes "no open tickets exist" from an empty result is wrong when the caller is scoped. - *Broader-access path (when the model's §7 resolves a mechanism).* If the **Row-level read scope** preamble named a documented broadening mechanism (separate cube view / entity surface, or a Postgres `BYPASSRLS` role attribute), the recipe's "you might want more" block names that mechanism and how the caller routes to it. The recipe does not auto-elevate; it proposes the route and lets the caller decide. **If the preamble did NOT name a mechanism, the recipe says so plainly: "broader read access for this entity is not provisioned in this catalog; escalate to a user who holds the role with broader access" — and never invents a "grant yourself `<slug>:view_all_X`" hand-off.** - *No client-side re-encoding of the rule.* Recipes must not duplicate the `select_rule` JsonLogic in their own filter (e.g. wiring `submitter_user_id=eq.$user_id` into the GET path "to be safe"). The platform applies the rule; client-side duplication is redundant and breaks if the model's rule changes between regenerations. The correct posture is: read with the natural query; the platform filters; surface the visibility limit to the user via the preamble callout. - **Conditional UI states (`input_type_rule`)**, the platform overrides a field's effective `input_type` at form render per-record. Recipes that POST/PATCH bypass the form and are not gated by the rule, but two patterns matter: - *Conditional-required side-effect.* For every entry in the `conditional_required_fields` sub-index (a rule that flips `default → required` on a transition), the JTBD that performs the triggering transition must set the dependent field in the same PATCH. The `dynamic_input_types` index gives the trigger and the dependent; the JTBD's Recipe block makes the PATCH explicit ("set `status=approved` AND `approved_at=$now` in one call"). When a paired `validation_rules` family-5 entry exists, name its `code` in the Failure modes block as the platform's enforcement-side counterpart. - *Post-terminal lock.* For every rule that flips a field to `readonly` after a terminal state, recipes that *update* the entity after that state should drop the locked field from their PATCH body. The platform doesn't enforce this server-side via `input_type_rule`, so the recipe is what keeps it consistent with the UI; if a paired server-side rule exists (a Stage 8 family-10 state-transition rule typically), surface its `code` in Failure modes. - *No re-derivation of the rule's effective value.* Recipes must not attempt to compute the field's UI mode client-side and branch on it — the rule is for the form, not for the recipe. A recipe that reads `status` and decides whether to include `approved_at` in the body should do so based on the **JTBD's own transition semantics** (which it owns), not by interpreting the `input_type_rule` JsonLogic. - **Cube queries in the appendix**, always lead with `cube discover '{}'` and tell the calling agent to *map* the appendix's measure/dimension names against discover's output. Cube schema names drift on regeneration; the appendix is a starting point, not a contract. #### Trigger phrasing The trigger language lives on **two distinct surfaces** that serve different audiences and take different shapes. They are NOT copies of each other; they overlap only in what they describe (the domain), not in their wording. **Surface 1: SKILL.md frontmatter `description`.** Matcher fuel, read by Claude Code's skill router to decide whether to load this skill for a given user prompt. The matcher works on semantic similarity between the description and the user's prompt, so the description should describe the **intent classes** the skill handles, not list literal user phrasings. Concrete user-voice sentences over-fit to specific wordings; abstract intent enumeration generalizes across the thousands of phrasings real users actually produce. This pattern matches how Anthropic's own skills are authored (`pdf`, `docx`, `xlsx`, `pptx`): their descriptions are intent enumerations, not lists of quoted user sentences. Follow that convention. **Surface 2: README.mdx `## Sample prompts`.** Catalog display, read by humans browsing a skill list. Its job is to show the **breadth** of what users can ask of this domain in literal phrasings the reader recognizes ("yes, I'd say something like that"). Concrete user-voice sentences belong here, in volume. ##### How to author the SKILL.md description Two parts, in this order: 1. **Domain noun + scope** (1 sentence). Lead with the domain ("CRM", "ITAM", "workforce planning") and the entities or capabilities it covers in plain words. Example: "Use this skill for anything involving ITAM (IT Asset Management), the in-house domain that tracks hardware assets, software products and licenses, installations, asset assignments, contracts, and purchase orders, plus the cost-center and chargeback rollup that links them." 2. **Action intent enumeration** (one sentence, verb-phrase list). List the JTBDs as abstract verb-phrase intents, comma-separated inside a single sentence introduced by "Trigger when the user wants to ...". Each intent corresponds to one JTBD section in the body; the matcher generalizes from these phrasings to varied user wording. Example: "Trigger when the user wants to deploy a hardware asset to a user, return or unassign an asset, retire or decommission equipment, install software on an asset with optional license seat tracking, uninstall software, mark a purchase order received, or renew a contract." - Aim for 6–10 intent phrases (one per JTBD; bundle close siblings if needed). Each phrase 4–10 words. - Lead each with an active verb. Cover the primary verb plus one common informal synonym where natural ("retire or decommission"), so the matcher hears both vocabularies. - **Do not** quote literal user sentences ("Bob is leaving, return his laptop"). The matcher generalizes better from intent phrases. - **Do not** include discovery intents (lookups, reports). Those are handled by `use-semantius` alone in most cases; loading the full domain skill for "who has asset X" wastes context. Discovery triggers belong in the README only. **Do not** add a "Loads alongside `use-semantius`..." compose hint to the description. The description is matcher fuel, and a sentence about which sibling skill owns CLI install / PostgREST encoding / cube mechanics does not help the router map a user prompt to this skill (users do not type "I need PostgREST encoding"). Compose-metadata is the harness's concern, not the matcher's. The compose-hint already lives in the SKILL.md body's opening paragraph ("Platform mechanics ... live in `use-semantius`. Assume it loads alongside"), where the calling agent reads it after the skill has loaded; that is the right place for it. ##### How to author the README sample prompts A bulleted list of **concrete user-voice sentences**, the kind of thing a real person types into chat. Volume matters here; the reader is browsing. - 12–17 prompts total. - **8–11 action prompts**: concrete sentences for the JTBDs. Multiple synonymous phrasings for high-traffic JTBDs are welcome and useful, "Bob is leaving, return his laptop" and "I need to take back Sarah's MacBook" both map to Return and both belong in the catalog because real users say both. - **4–6 discovery prompts**: concrete lookup or report questions. "Who has asset SN-12345 right now", "which contracts expire next quarter", "show license utilization for Microsoft 365". These are NOT in the description (per surface-1 rules) but ARE in the README, because the catalog reader benefits from seeing them. ##### The relationship between the two surfaces The description and the sample-prompts list overlap only in what they describe (the same domain, the same JTBDs). They do **not** share wording: the description has abstract verb-phrase intents, the README has concrete user-voice sentences. Each README sample prompt should map cleanly to either an intent in the description (action prompts) or a Common-queries example or lookup-convention pattern (discovery prompts). Principle 6 (Step 9) gates that mapping. ### Step 6, Write the reference files (one per JTBD classified `reference`) For every JTBD that Pass 3 classified as `reference`, write a sibling file at `<skills-root>/<modelslug>/references/<jtbd-slug>.md`. The slug matches the SKILL.md `<jtbd-slug>` link target byte-for-byte, the agent will fail to load the file if the link drifts. Use a short verb-phrase slug (`schedule-feature.md`, `cast-vote.md`, `ship-release.md`), not a full sentence. The reference file is loaded by the calling agent **only** when it enters that specific JTBD. SKILL.md has already been read by then, so the agent knows the glossary, enums, lookup convention, timestamp rule, and guardrails. Do not restate any of those. The reference file owns the recipe body, the FK / shape assumptions the recipe relies on, and any rules that only matter inside this JTBD. #### Reference file template ```markdown # <Job title (matches SKILL.md ### heading verbatim)> <One opening sentence: what this recipe does and the most load-bearing invariant. No marketing, no value-prop, the agent has already chosen this recipe. Example: "Cast or update a vote on a feature. The `(feature_id, user_id)` junction has no DB-level uniqueness, so the recipe must read first."> ## FK & shape assumptions <List only the FK / uniqueness / audit-logging facts THIS recipe relies on. One line per fact, in the form `<child>.<col> -> <parent>.id` plus a short note on uniqueness or junction shape. Skip anything the recipe doesn't actually depend on, this is an assumption ledger, not a schema dump. If any of these turn out to be wrong at runtime (a 409 / 422 the recipe didn't predict), the agent follows the SKILL.md "When the runtime disagrees with the recipe" escape hatch: query `read_field`, surface the drift, abort cleanly. Do not silently adapt. Audit-logging notes belong here only if the recipe's correctness depends on whether audit rows are written; otherwise omit, audit rows are Semantius's concern, not the recipe's.> - `feature_votes.feature_id -> features.id` - `feature_votes.user_id -> users.id` - `(feature_id, user_id)` junction has **no DB-level unique constraint**, recipe MUST read-first before insert to avoid duplicate vote rows. ## Composition rules <Required only when this JTBD composes a caller-populated label or recomputes a stored field. Spell out the algorithm so two callers given the same inputs produce byte-identical output. "If possible", "approximately", and "around N characters" are banned, replace with deterministic rules: where to cut, what separator, whether to append an ellipsis, how to round.> - `<feature_vote_label>`: composed as `"{user.user_full_name} -> {feature.feature_title}"`. ASCII arrow ` -> ` (space-hyphen-greater-space). The values come from the read-first calls in step 1; do not invent. - `<rice_score>`: computed as `(reach * impact * confidence) / effort`. Round to <N> decimals to match the `numeric(<precision>, <scale>)` column scale, no truncation, no implicit float drift. If `effort` is null or zero after the patch, write `rice_score: null` rather than a placeholder. ## Recipe ```bash # Step 1: parallel-fetch (no dependency between these reads) semantius call crud postgrestRequest '{"method":"GET","path":"/<table>?<filter>&select=<cols>"}' semantius call crud postgrestRequest '{"method":"GET","path":"/<other>?<filter>&select=<cols>"}' # Step 2: <branch / compute / refuse logic with explicit conditions, # e.g. "if release_status in (released, cancelled), refuse"> # Step 3: <write> (paired fields go in one call, never split) semantius call crud postgrestRequest '{ "method":"<POST|PATCH>", "path":"/<table>[?<filter>]", "body":{<resolved body>} }' # Step 4: <verify the post-condition the validation block claims> ``` Annotate each recipe step's leading comment with **what the step depends on**: independent reads carry the leading comment "parallel-fetch (no dependency)" so the agent runs them in one round trip; dependent steps name what they consume from earlier steps. Without the explicit hint, the agent treats numbered lists as sequential. ## Validation <Three or four post-conditions, including any deeper invariants the SKILL.md outline only summarised. Each one must be checkable from a single GET; if you cannot, fix the recipe so it can.> ## Failure modes (extended) <Long-form discussion of every failure that matters: triggering condition, why it happens, the exact recovery procedure (often a follow-up call), how to detect after-the-fact that this failure happened, and whether the recovery is safe to run blindly or needs a user confirmation. Pair every failure with a recovery, not just a description.> ``` #### Where FK detail lives, and why The split exists so SKILL.md stays small *and* tolerates live-schema drift. Apply the test for each piece of content: - *Every JTBD touches it* (lookup convention, timestamp rule, glossary, enums, guardrails) → SKILL.md only. - *Only this JTBD touches it* (recipe body, JTBD-specific composition rules, FK / uniqueness assumptions, audit-logging facts the recipe depends on, extended failure modes, computed-field rounding) → reference file's "FK & shape assumptions" section. - *Genuinely cross-cutting fact 2+ JTBDs depend on in load-bearing ways* (rare, often empty in practice) → SKILL.md "Cross-cutting data rules" section. Default is "doesn't qualify"; promote reluctantly. Per-FK shape used to live in a SKILL.md cheatsheet. It moved to the reference files because (1) most FKs are touched by only the one JTBD that mutates them, so the SKILL.md slot was paid by every trigger but consumed by one, and (2) live schema can drift between generation and call (admins toggling unique indexes, audit-logging, FKs); colocating the assumption with the recipe that depends on it makes regeneration and drift-recovery localised. The runtime escape hatch in SKILL.md ("When the runtime disagrees with the recipe") covers the drift case. A reference file aimed at fewer than ~40 lines means the JTBD probably belongs inline in SKILL.md after all, the file split has overhead (an extra read). A reference file growing past ~120 lines means either the JTBD is doing two jobs (split it) or the reference is restating SKILL.md material (delete the duplicates). ### Step 7, Write the script files (one per JTBD classified `script`) For every JTBD that Pass 3 classified as `script`, write a sibling file at `<skills-root>/<modelslug>/scripts/<op-slug>.sh`. Mark it executable in the comment header; the calling agent invokes the script through the shell rather than reading it into context. The script's contract is its **inputs**, **exit codes**, and **stdout on success**. The agent never reads the body, so the body must be self-defending: validate args, refuse on bad preconditions, never silently leave half-state. #### Script file template ```bash #!/usr/bin/env bash # <op-slug>.sh: <one-line purpose, e.g. "Ship a release: PATCH the # release row, sweep its planned/in_progress features to shipped, # verify the sweep is complete."> # # Usage: <op-slug>.sh <arg1> <arg2> [optional] # # <Optional per-mode / per-subcommand detail block goes HERE, AFTER # Usage, never before. For a single-mode script omit this block # entirely. Example for a two-mode script: # Add: read-first dedupe; if row exists active, no-op; ... # Remove: soft-deactivate (is_active=false) so history survives.> # # Exit: 0 on success # 1 on usage/validation failure (bad args, precondition not met) # 2 on platform error (semantius call failed) # # Idempotent: re-running with the same inputs is safe. Partial-state # recovery: on failure, print the failed step and exit non-zero; the # next run resumes from where it left off. set -euo pipefail if [ "$#" -lt <N> ]; then echo "Usage: $(basename "$0") <arg1> <arg2> [optional]" >&2 exit 1 fi arg1="$1" arg2="$2" # Step 1: read; refuse if precondition fails. result=$(semantius call crud postgrestRequest "{\"method\":\"GET\",\"path\":\"/<table>?<filter>&select=<cols>\"}") \ || { echo "step 1 (read <table>) failed" >&2; exit 2; } # parse result, check precondition; bail with a clear message if not met. # Step 2..N: write, then verify. semantius call crud postgrestRequest "{...}" \ || { echo "step 2 (write <table>) failed" >&2; exit 2; } semantius call crud postgrestRequest "{...}" \ || { echo "step 3 (sweep <child>) failed; release row already updated, retry will be a no-op for already-shipped rows" >&2; exit 2; } echo "<op-slug>: ok" ``` #### Conventions every script follows - **First-line shebang `#!/usr/bin/env bash`**, `set -euo pipefail` immediately after, no exceptions. Silent failures in shell are how cascade scripts leave half-state. - **Header section order is fixed**: purpose one-liner, Usage, optional per-mode detail, Exit, Idempotent. Usage comes immediately after the purpose line so a human auditor sees "how do I call this" before any prose. Per-mode behavior detail (e.g. `Add:` / `Remove:`) goes *after* Usage, never between purpose and Usage; the synopsis introduces the modes, then the detail explains them. - **Validate args before any platform call.** Print usage to stderr, exit 1. The agent reads stderr to recover. - **Exit codes are part of the contract.** The recipe script's own exit codes are: 0 = ok, 1 = bad inputs or unresolved/ambiguous lookup, 2 = platform error. The agent only branches on these three; do not invent more for the script layer. The underlying `semantius` CLI carries finer-grained signal — `1` (bad args / `--single` zero rows), `2` (`--single` ≥2 rows), `3` (network / transport, transient and retryable), `4` (tool execution failed: RLS, dup key, schema, validation rule), `5` (auth failure, permanent) — but the script collapses platform failures into its own `2` and lets stderr carry the specifics. The diagnostic string must name *which step* failed (e.g. `step 3 (sweep <child>) failed`) and surface any platform `validation_rules` error verbatim so the agent can recover. - **Failure messages name the failed step.** `step 3 (sweep <child>) failed` is recoverable; `error` is not. - **Surface platform `validation_rules` errors verbatim, never duplicate them.** When a `semantius call ... POST/PATCH` fails because the platform rejected the write, the response body carries `{ "errors": [{ "code", "message" }, ...] }`. Pass the `code` and `message` through to stderr unchanged so the agent can surface a clean recovery hint to the user. The script may *name* known codes in its diagnostic prose (e.g. "step 3 failed; if code is `release_only_when_committed`, the user should triage the feature to `planned` first"), but it must NOT pre-check the JsonLogic client-side; that duplicates a rule the platform owns and rots the moment the rule changes. - **Idempotent.** A repeat run on partially-applied state must either complete or be a deterministic no-op. For cascade scripts, filter writes to "rows still in the source state", not "all rows in the parent set"; running twice then becomes safe. - **No interactive prompts.** The agent invokes non-interactively. If the operation needs a user confirmation, the JTBD is a `reference`, not a `script`. - **URL-encode every caller-provided value interpolated into a GET path, PATCH filter, or DELETE filter.** Raw bash interpolation of `$var` into `/<table>?search_vector=wfts(simple).$var` or `?<col>=eq.$var` breaks the moment the value contains a space, an ampersand, a parenthesis, a `+`, a `%`, a `#`, a `?`, a quote, or any other character outside the URL unreserved set. Real catalog data is full of these (`Customer Management`, `Investment Banking`, `Sales & Marketing`, `Account (Salesforce)`). The canonical encode-then-interpolate pattern is one line via `jq`: ```bash enc_term=$(printf '%s' "$user_input" | jq -sRr @uri) semantius call crud postgrestRequest \ "{\"method\":\"GET\",\"path\":\"/${table}?search_vector=wfts(simple).${enc_term}&select=id\"}" ``` This applies to **every** caller value: search terms going into `wfts(simple).<term>`, exact-match values going into `<col>=eq.<value>` or `<col>=in.(<values>)`, label-equality dedupe filters, and any other position where a caller string ends up in the URL. UUIDs already resolved from a `--single` read are URL-safe and do not need encoding. Recipe lines that interpolate raw `$var` into a path are a defect; Principle 7 in Step 9 catches them on self-review. - **Build JSON bodies with `jq -nc --arg`, never string concatenation.** A naïve `body="{\"notes\":\"$caller_notes\"}"` breaks the moment `$caller_notes` contains a `"`, a `\`, a literal newline, or a control character. Research-agent prose contains all four. The failure mode is opaque, the platform sees mangled JSON and returns a parse error rather than a clean validation message. The canonical build-then-pass pattern is: ```bash body=$(jq -nc \ --arg status "$new_status" \ --arg notes "$caller_notes" \ '{record_status: $status, notes: $notes}') semantius call crud postgrestRequest \ "{\"method\":\"PATCH\",\"path\":\"/${table}?id=eq.${row_id}\",\"body\":${body}}" ``` Use `--arg` for strings, `--argjson` for booleans / numbers / nested objects, and `--rawfile` for multiline content read from a file. Conditional fields (only include `industry_id` when `alias_type=industry_term`) compose by building the base object then layering with `+ {field: $val}` inside the same `jq` call, never by concatenating fragments. Recipe lines that build JSON via string concatenation are a defect; Principle 7 catches them. - **Refuse writes to columns the entity does not declare.** The model parse in Step 2 already produces a per-entity field list. For any optional column a script writes conditionally (`notes`, `description`, `condition_notes`, `is_preferred`), the script must either (a) bake in the list of entities that carry the column and refuse the arg with a clear stderr message when the caller targets one that does not, or (b) be specialized to a single entity that has the column. A polymorphic script that accepts an `entity` arg and unconditionally writes `notes` will 4xx on every entity that lacks a `notes` column, and the platform's response (`column "notes" does not exist`) is opaque to the agent, surface a precise error early instead. The canonical pattern: ```bash case "$entity" in data_object_aliases|data_object_relationships|solutions|vendors|industry_business_functions|business_function_domains|business_function_capabilities|domain_data_objects|capability_domains|solution_domains|solution_data_objects|solution_capabilities|domain_regulations) supports_notes=1 ;; *) supports_notes=0 ;; esac if [ "$supports_notes" = "0" ] && [ -n "${caller_notes:-}" ]; then echo "step 0: entity '$entity' has no notes column; supported entities are: ..." >&2 exit 1 fi ``` The list is computed from the model at generation time, not at script-run time. The same rule applies to every optional column the recipe ever writes. ### Step 8, Write the README.mdx (human-facing catalog entry) After the SKILL.md is written, generate a sibling `README.mdx` in the same folder. This file is **not** loaded by any agent harness; it exists so a person browsing a skill catalog can understand at a glance what the skill is for and whether they want it. Optimize for human skim, not agent triggering. This step is **not optional**. A run that produces only `SKILL.md` is incomplete; the catalog system depends on the README being there. If you find yourself about to print the Step 10 summary without having written `README.mdx`, stop and write it now. #### Audience and tone The reader is a human evaluating skills, not an LLM deciding whether to invoke one. Two consequences shape every rule that follows: - Drop the pushy trigger language and the "delegates platform mechanics to `use-semantius`" plumbing. Those belong in the SKILL.md, where the matcher reads them. A human browsing the catalog does not need to know about the `use-semantius` composition to decide whether the domain matches their problem. - Drop the agent-harness jargon (Agent Skills, frontmatter matching, trigger phrases as keyword strings). The catalog is read by people picking which skills to install, not by the harness picking which skill to load. Lead with the domain narrative the model file already authored. The catalog reader needs to understand the SYSTEM here. The unique "why install this specific skill" angle lives only in the front-matter `description`. #### Hard banned characters and phrases These are non-negotiable. The README is read by humans browsing a skill catalog, and prior generations have repeatedly violated them. - **Never** emit the em-dash character (Unicode U+2014, the long dash often used as a parenthetical break) anywhere in the README. Use commas, colons, parentheses, or split sentences. Hyphens (`-`) and en-dashes (`–`, used only in number ranges) are fine. - **Never** use the substring "this skill" anywhere in the README. The catalog renders many skill cards side by side and "This skill helps with…" openings make the list unreadable. - **Never** include `generated_from`, `semantic_model`, or any other provenance key in the README front matter. The catalog only reads `title` and `description`. Provenance lives in the SKILL.md. If you find yourself reaching for an em-dash because the sentence "feels right" with one, rewrite the sentence. The user has flagged this multiple times. #### Front-matter `description` rules The `description` is the **single line a non-technical person reads on the catalog card** before deciding whether to open the skill. It must follow the same audience and verb logic as the body's skill-explanation paragraph (Step 8 §3), compressed to one sentence. **Required shape (one sentence, ≤140 characters):** > `<Extracted verb><s>` `<the domain object in user words>` `<list of lifecycle stages, operations, or capabilities in plain words>`. The description names what the skill actually does, by listing the real nouns of the domain (workflow stages, operations, artefacts). It does **not** include a "so [benefit]" clause. The benefit / value-prop lives in the body paragraph's failure-modes sentence, not on the catalog card. A reader of the catalog card wants to know what the skill *does*, not why it exists. - **Extracted verb** comes from the same three-tier verb-extraction rule used in the body paragraph (Step 8 § "Verb-extraction rule"). The description must use the **same verb** as paragraph 2, resolved in this order: - **Tier 1, suffix match.** `Tracking|Tracker → tracks`, `Planning|Planner → plans`, `Management|Manager → manages`, `Budgeting → budgets`, `Scheduling|Scheduler → schedules`, `Forecasting → forecasts`, `Reporting → reports`, `Monitoring → monitors`, `Routing → routes`, `Booking → books`, `Provisioning → provisions`. - **Tier 2, implied-domain-verb lookup.** If Tier 1 misses, check the noun table: `Roadmap → plans`, `Inventory → tracks`, `Ledger → records`, `Directory → lists`, `Registry → registers`, `Pipeline → moves`, `Catalog → lists`, `Calendar → schedules`, `Knowledge Base|KB → answers`, `Dashboard → surfaces`, `CRM → tracks`, `Helpdesk|Service Desk → resolves`. Example: `Product Roadmap` → "Plans how every idea moves from intake to a shipped feature...". - **Tier 3, fallback palette.** Only when neither tier fires: `Captures`, `Holds`, `Describes`, `Maps`, `Organises`, or `Helps an agent <verb-from-domain> ...`. Should be rare. - **Domain object** uses the model's user-facing labels, never table names or schema-cased identifiers. "candidates", not `candidates`; "headcount plans", not `headcount_plans`. - **Capability list** names the actual lifecycle stages, operations, or artefacts the skill works with, in plain domain words from the model. Examples: "from requisition through application, interview, offer, and hire"; "subscriptions, license assignments, renewals, and planned spend by cost center"; "with decision packages, funding levels, ranking, and approval workflow"; "from intake through RICE scoring, objective alignment, and release scheduling". Pull these nouns from the model's entities, enums, and lifecycle fields, they should be recognisable to an operator of the system. **Hard bans (zero tolerance):** - **"Bakes in", "baked in", "bakes the rules", "bakes the invariants".** These read as internal implementation talk; the catalog reader does not know or care that anything is being baked. Use the extracted verb instead. - "Multi-step rules", "paired status fields", "paired writes", "cascade", "invariants", "knock-on changes baked in", "the multi-table cascade that fires when". All mechanics jargon. - Any snake_case or identifier-shaped token (regex `\b[a-z][a-z0-9]*(_[a-z0-9]+)+\b`). - "This skill", "A skill for", "Domain skill for", "Skill that", any self-referential opener. - Em-dashes (U+2014). - Engineer-coded LLM language ("non-deterministic", "stochastic", "deterministic output"). - Restating the system name itself ("The Applicant Tracking System..."). The title already says it. **Coherence check:** the description's verb must match the body paragraph's verb (same verb-extraction tier). The description itself names *capabilities*, not benefits, the body paragraph's sentence 3 (failure modes) is where the value-prop lives. Do not paraphrase the body's "so X" clause into the description; that shape belongs in the body, not on the catalog card. **Examples (illustrative, regenerate from the actual model):** | `system_name` | Verb | GOOD description | |---|---|---| | Applicant Tracking System | tracks | `Tracks candidates through requisitions, applications, interviews, offers, and hires.` | | Workforce Planning | plans | `Plans headcount across scenarios, commits approved scenarios into positions, and opens requisitions for new seats.` | | Equipment Lease Management | manages | `Manages equipment leases through schedules, payments, renewals, and end-of-term disposition.` | | Zero-Based Budgeting | budgets | `Runs ZBB cycles with decision packages, funding levels, ranking, and approval workflow.` | | SaaS Expense Tracker & Budget | tracks | `Tracks SaaS subscriptions, license assignments, renewals, and planned spend by cost center.` | | Product Roadmap | plans (Tier 2: `Roadmap` → plans) | `Plans features through intake, RICE scoring, objective alignment, release scheduling, and ship.` | | Inventory Tracker | tracks (Tier 1) | `Tracks items, locations, movements, counts, and reorder points across warehouses.` | | General Ledger | records (Tier 2: `Ledger` → records) | `Records transactions across accounts, journals, and periods, and runs balanced period closes.` | | Service Desk | resolves (Tier 2: `Service Desk` → resolves) | `Resolves tickets through intake, triage, assignment, work, and follow-up.` | **BAD examples (do not produce):** - `Bakes in the multi-step rules for moving a candidate from application to hire, including paired status fields and offer-acceptance ripples.` (Bakes in, paired status fields, ripples, all jargon.) - `Tracks candidates from application to hire so the right pieces always get filled in in the right order.` (The "so [outcome]" clause is trigger-fodder; the description should name capabilities, not justify them.) - `Plans headcount across scenarios so an approved scenario walks into real seats with the right paperwork at every step.` (Same anti-pattern, "so [outcome]" clause replaces the capability list.) - `This skill helps with the Applicant Tracking System.` (Self-referential opener, restates the title.) #### Body structure (in this exact order) The body has exactly **five** sections after the heading. Do not add, rename, or rearrange. 1. **Heading.** See "Title grammar" below. 2. **Model description (verbatim from the model's §1 narrative).** Immediately after the heading, copy the model file's §1 narrative paragraph(s) verbatim. Do not paraphrase. Do not insert your own summary. This paragraph explains what the SYSTEM is. - **Ignore the `domain` frontmatter field entirely** when building the README body. In every model file we have seen, `domain` is a short category tag (`ATS`, `CDP`, `ERP`, `Workforce Planning`, `Product Management`), not a description. Pasting it as a body paragraph leaves an orphan acronym floating under the heading and looks broken. The §1 narrative is always the source of truth for the body description. - If the model file has no §1 narrative, stop and ask the user to add one. Do not fabricate a description. 3. **Skill explanation paragraph (one paragraph, ~3 sentences, built on a fixed three-noun definition).** After a blank line, write **one** paragraph aimed at a non-technical human browsing the catalog. The paragraph names three things in order: the **model**, the **skill**, and the **failure modes**. #### The three-noun definition - **The model** describes the static structure: what entities exist, what fields they have, what values are allowed. It tells the agent *what can be recorded*. - **The agent** is good at understanding instructions and chaining steps, but two runs of the same prompt can take subtly different paths and produce subtly different records. - **The skill** is the missing piece between them: it teaches the agent *how to use this specific model to do its specific jobs reliably, the same way every time*. That third bullet is the value-prop, every paragraph must carry it somehow. The skill is not a metaphor about habits or shorthand, it is the model's instruction manual for the agent. #### Sentence-by-sentence shape **Sentence 1, the model.** Name the model and what it lays out or tracks. Use the verb-extraction rule below. Bridge from the previous paragraph by referring to the same kind of thing it ended on (records, plans, ideas, contracts). **Sentence 2, the skill.** Name the skill (by its title, not the pronoun "this skill") and what it teaches the agent: how to use the model to do its specific jobs reliably and the same way every time. Reuse the domain verb from sentence 1 if it reads naturally. **Sentence 3, what going wrong looks like.** Two or three concrete failure modes in plain domain words, semicolon- separated. These are evidence for the value-prop, not complaints about the platform. Optional sentence 4, what life looks like with it loaded. Only if it earns its keep, do not pad. #### Verb-extraction rule (critical, prevents all paragraphs reading the same) Most `system_name` values either have an action verb hiding in a suffix or **imply** one through a domain noun. Resolve in **three tiers**, in order. Stop at the first tier that fires. **Tier 1: Suffix match.** If `system_name` ends in an `-ing` gerund or an `-er`/`-or` agent noun from the table below, use the bare verb form. | Suffix | Verb | Example | |---|---|---| | `Tracking`, `Tracker` | tracks | "The Applicant Tracking model **tracks** ..." | | `Planning`, `Planner` | plans | "The Workforce Planning model **plans** ..." | | `Management`, `Manager` | manages | "The Equipment Lease Management model **manages** ..." | | `Budgeting` | budgets | "The Zero-Based Budgeting model **budgets** ..." | | `Scheduling`, `Scheduler` | schedules | | | `Forecasting` | forecasts | | | `Reporting` | reports | | | `Monitoring` | monitors | | | `Routing` | routes | | | `Booking` | books | | | `Provisioning` | provisions | | **Tier 2: Implied-domain-verb lookup.** If Tier 1 does not fire, check whether `system_name` contains one of these domain nouns, each of which implies a verb a user would actually say. Treat this list as authoritative; extend it as new patterns appear. | Noun in `system_name` | Verb | Reasoning | |---|---|---| | `Roadmap` | plans | A roadmap is a planning artefact | | `Inventory` | tracks | What you do with an inventory is track stock | | `Ledger` | records | A ledger records transactions | | `Directory` | lists | A directory lists entities | | `Registry` | registers | A registry registers entries | | `Pipeline` | moves | A pipeline moves work through stages | | `Catalog` | lists | A catalogue lists items | | `Calendar` | schedules | A calendar schedules events | | `Knowledge Base`, `KB` | answers | A KB answers questions | | `Dashboard` | surfaces | A dashboard surfaces metrics | | `CRM` | tracks | Customer relationship tracking | | `Helpdesk`, `Service Desk` | resolves | A helpdesk resolves tickets | Example: `system_name = "Product Roadmap"` matches `Roadmap` in Tier 2 → "The Product Roadmap model **plans** how every idea moves from intake through scoring and release commitment to a shipped feature ..." **Tier 3: Fallback palette.** Only when neither Tier 1 nor Tier 2 fires, pick from `captures`, `holds`, `describes`, `lays out`, `organises`, `maps`. The fallback should be **rare**. If you find yourself reaching for it, pause and ask: "what does an operator actually *do* with this thing?" If a single verb captures it (even informally), prefer that verb and add it to the Tier 2 table for future runs. If neither tier fires and no domain verb feels obvious, surface a one-line confirmation to the user before writing files: `"No clear domain verb in '<system_name>'; using '<fallback>'. Override with a different verb, or proceed?"` The Tier 3 fallback palette has six options so even genuinely verbless system names do not all read the same. #### Worked examples (use as shape templates, not for verbatim copy) **Applicant Tracking** (verb extracted: track) > The Applicant Tracking model tracks every step of a hire, from > first application to recorded acceptance. The Applicant > Tracking Skill teaches an agent how to use that model to track > candidates through the funnel reliably and the same way every > time, so the right pieces always get filled in in the right > order. Without it, an offer can go out with no recorded > approver; a rejection can land with no reason on file and > quietly blank the funnel report; a candidate can accept while > the requisition stays open and get pulled into another pipeline > by mistake. **Workforce Planning** (verb extracted: plan) > The Workforce Planning model plans how the team grows across > scenarios and the positions a committed scenario will create. > The Workforce Planning Skill teaches an agent how to use that > model to plan headcount across scenarios and walk an approved > scenario into real seats reliably, with the right paired > updates and the right handoff to the recruiting team. Without > it, a plan can be marked approved with no record of who signed > off; two people can end up assigned to the same seat; an > approved scenario can sit dormant while the real positions > never get created. **Zero-Based Budgeting** (verb extracted: budget) > The Zero-Based Budgeting model budgets every line item from > scratch each cycle, with the assumptions behind each number. > The Zero-Based Budgeting Skill teaches an agent how to use > that model to budget a fresh cycle reliably, with assumptions > captured alongside the numbers and the prior cycle's reasoning > still readable when someone asks. Without it, a budget line > can land with no recorded assumption; a justification from > last cycle can quietly carry over without being re-examined; a > cut can ship without naming who approved it. **Product Roadmap** (Tier 2: `Roadmap` → plans) > The Product Roadmap model plans how every idea moves from > intake through scoring and release commitment to a shipped > feature, with the rationale weighing each one and the release > it lands in. The Product Roadmap Skill teaches an agent how > to use that model to plan a feature from intake through to a shipped > release reliably, without the handoffs between PM, design, and > engineering quietly going missing. Without it, an idea can get > scheduled with no recorded owner; a release can ship with > features still marked "in design"; a deferred feature can lose > the rationale that explains why it slipped. #### Hard bans (literal scans before declaring done) - Any snake_case or identifier-shaped token (`approved_at`, `originated_from_action_id`, `*_id`, `*_at`, `*_by_*`). Implementation, not value. - Mechanics jargon: `writes`, `rows`, `calls`, `PATCH`, `POST`, `API`, `schema`, `column`, `FK`, `foreign key`, `constraint`, `uniqueness`, `join`, `table`, `query`, `back-pointer`, `cascade` (the noun). - LLM-engineer language: `non-deterministic`, `stochastic`, `improvises`, `drift between runs`, `reproducible output`. Catalog readers do not think of agents that way. - Band-aid framings: "the platform does not enforce", "the database does not catch", "multi-step writes that aren't enforced". These frame the skill as patching a defect. - The phrase "this skill" anywhere; the literal front-matter `description` copied verbatim; `use-semantius`; CLI commands; file paths; code fragments. - Schema-cased entity names: "Position" not `positions`, "Interview Feedback" not `interview_feedback`. Use the model's `singular_label` values. - Verb-list rephrasing of the trigger bullets ("approving plans, opening requisitions, filling positions, onboarding new hires"). The bullets render right below; do not echo them. - The literal phrase "lays out what the system can record". That was the example, not a template; paraphrase based on the model's actual flavor. #### Required ingredients - The three-noun definition: the model paragraph names the model and its verb, the skill paragraph names the skill by title and the value-prop ("teaches an agent how to use that model to do its jobs reliably and the same way every time"), the failure paragraph names two or three concrete bad days. - Domain verb extracted from `system_name` per the rule above (or fallback palette if no verb is hiding). - Bridge to the previous paragraph by reusing a noun from its last clause (records, plans, ideas, contracts, the funnel, etc.). Do not start cold. #### The acceptance tests 1. **Pattern test.** Replace the model name with "X" everywhere in the paragraph. If the result reads as something that could apply to any of the other skills in the catalog, the paragraph is too generic; the verb-extracted noun and the failure modes should make it unmistakably about this one model. 2. **No-duplication test.** Place the paragraph above the rendered trigger bullet list. If any sentence reads like a paraphrase of the bullets, replace it. 3. **Coffee test.** Read aloud as if to the operator the model describes (recruiter, planning lead, controller, support engineer). If they would squint at any sentence, rewrite. 4. **Sample prompts.** A bulleted list of **every** trigger phrase from the SKILL.md frontmatter `description`, verbatim and quoted, one per bullet, in the same order they appear in the description. Do not pick a subset. Do not paraphrase. If the description has ten quoted phrases, the bullet list has ten bullets. Sample prompts come **before** the capability list because catalog readers recognize and resonate with user-voice phrasing faster than verb-phrase capability bullets; the prompts pull the reader in, and the capability list gives them the scope check they want next. 5. **What it covers.** A short bulleted list (5–7 bullets, each a verb phrase under ~12 words) summarizing the capability scope of the skill. Pulled from the JTBD section titles plus the Common-queries appendix, grouped and condensed. Each bullet names a capability in plain domain words, no script names, no file paths, no jargon. The list functions as the catalog reader's scope check after the sample prompts hook them: "the prompts feel right, but does it actually do what I'd want?" See "What it covers, content rules" below for shaping guidance. 6. **Semantic model.** A Mermaid diagram copied verbatim from the model (see Mermaid section below). #### README.mdx template ````mdx --- title: <Heading text, see "Title grammar" below> description: <One sentence, ≤140 chars. Shape: "<Extracted-verb>s <domain object> <list of lifecycle stages, operations, or artefacts in plain words>." Verb-led, names the actual nouns of the domain. No "so [benefit]" clause. No "Bakes in", no mechanics jargon, no snake_case, no "this skill", no em-dashes.> --- # <Heading text, same as front-matter title, must contain "Skill"> <Verbatim copy of the model's §1 narrative paragraph(s). Ignore the `domain` frontmatter field entirely (it is a short category tag like ATS, CDP, ERP, never a description). No paraphrase, no code, no CLI, no enum names.> <Skill explanation paragraph: 2 to 4 sentences expanding the front-matter `description` into prose for a human. Same value-prop, not the same words. Mentions concrete domain nouns. Does not say "this skill". Does not mention `use-semantius`, CLI, or harness plumbing. Explains what loading this skill enables on top of the system the previous paragraph described.> ## Sample prompts - "<phrase 1 from SKILL.md description, verbatim>" - "<phrase 2 from SKILL.md description, verbatim>" - "<phrase 3 from SKILL.md description, verbatim>" - ... (one bullet per quoted phrase in the SKILL.md description, no subset) ## What it covers - <verb-phrase capability 1, e.g. "Move candidates through requisitions, applications, interviews, offers, and hires"> - <verb-phrase capability 2> - <verb-phrase capability 3> - ... (5–7 bullets total, see "What it covers, content rules" below) ## Semantic model ```mermaid <Mermaid diagram, see "Mermaid diagram" below> ``` ```` That is the entire README. Six elements only: front-matter, heading, model description (verbatim from §1), skill explanation paragraph (prose expansion of the front-matter description), sample prompts, what it covers, mermaid diagram. **Do not add** any other section, including "When to use it", "What's inside", "Generated from", or "About". #### What it covers, content rules The `## What it covers` section is the catalog reader's scope check. It comes **after** the sample prompts (which hook recognition) and **before** the diagram (which is the visual model). Five rules shape it: 1. **5–7 bullets.** Fewer reads as too thin; more reads as a feature dump and starts to compete with the prompts for attention. If the source has 10+ JTBDs, group them. 2. **Each bullet is a verb phrase under ~12 words.** Lead with a verb in the same Tier 1 / 2 / 3 family as the front-matter description's verb (no need to repeat the exact verb on every bullet, but stay in the family of action verbs the domain uses). Examples: "Deploy, return, and retire hardware assets"; "Install and uninstall software with license seat tracking"; "Receive purchase orders"; "Renew contracts". 3. **Group related JTBDs into single bullets when natural.** Deploy + return + retire collapse to one bullet ("Deploy, return, and retire hardware assets"); install + uninstall collapse to one ("Install and uninstall software with license seat tracking"). Do not split for the sake of bullet count. 4. **Common queries get one rolled-up bullet at the end.** Format: "Common reports: <list 3–5 query themes in plain words>". Example: "Common reports: asset count by status, contracts expiring, license utilization, spend by cost center". Do not list each query separately; that bloats the list and competes with the JTBDs for attention. 5. **No script names, no file paths, no jargon.** "Renew contracts" is good; "renew-contract.sh" is bad; "materialize the renewal handoff" is bad. The reader is non-technical; they care about what the skill *does*, not how the generator classified it. The list is sourced from the JTBD section titles plus the Common-queries appendix. Walk the JTBDs in the order they appear in the SKILL.md, group adjacent related ones, render each group as a verb-phrase bullet, then append the rolled-up "Common reports" bullet last. Keep the order from the SKILL.md so the catalog list and the SKILL.md sections agree on narrative flow. #### Title grammar This rule governs **two places** in the README.mdx that must carry the same text: the front-matter `title` and the H1 heading. Both **must** contain the word "Skill" with a capital S, written as a standalone word (never "domain skill", never "Skill that…", never lowercased). The SKILL.md H1 is a **different** heading, governed by its own rule (see the SKILL.md template above): it is `system_name` verbatim, no "Skill" suffix, because the file is named `SKILL.md` and repeating "Skill" in the heading is redundant. Title grammar does **not** apply to the SKILL.md H1. Algorithm: 1. Start with `system_name`. 2. If it ends in the word "System" (case-insensitive), drop that trailing word. Reason: appending "Skill" to a name that already ends in "System" produces "...System Skill", which reads as two nouns colliding. Resolve the collision in favor of "Skill", because "Skill" is the catalog's anchor word and every entry carries it; "System" is the one that drops. So "Applicant Tracking System" becomes "Applicant Tracking". 3. Append " Skill". Examples: | `system_name` | Title | |---------------------------|-----------------------------| | Applicant Tracking System | Applicant Tracking Skill | | Workforce Planning | Workforce Planning Skill | | Product Roadmap | Product Roadmap Skill | | Customer Relations | Customer Relations Skill | | CRM | CRM Skill | If the resulting title reads awkwardly to a fluent English ear (rare, flag it to the user), prefer rewording the system_name itself in the model file rather than dropping "Skill" from the title. "Skill" is the catalog's anchor word; humans scanning the list expect every entry to have it. #### Mermaid diagram **Copy the mermaid block from the source model file verbatim.** The semantic model already authors a domain-map mermaid diagram (it is produced by `semantic-model-analyst` and is the single source of truth for the entity layout). Locate the existing ```` ```mermaid ```` fenced block in the model file and paste it under `## Semantic model` unchanged. Do **not** generate a new diagram from the model's entity list and FK section. Do **not** apply your own layout, labels, or grouping. Any deviation from the model's diagram causes the README to drift from the model the next time someone updates the model file. If the model file has no mermaid block at all (rare; flag this to the user as a model defect), omit the `## Semantic model` section entirely and note in the Step 10 summary: `Model file has no mermaid block; omitted Semantic model section. Ask <semantic-model-analyst> to add one.` ### Step 9, Self-review pass Before printing the summary, re-read the SKILL.md you just wrote with fresh eyes, as if a colleague were going to use it tomorrow against a different model. The point is not a checklist; it is that small drafting errors here scale, because every future invocation of the generated skill pays the cost. Fix issues in place; surface anything you can't fix without a design change in the Step 10 summary as a known limitation. Run the pass against the principles below. Principle 0 is a structural-compliance check that runs **first** because it catches the single most common defect from prior generations: skipping Pass 3 entirely and emitting a monolithic SKILL.md. The remaining principles are *examples* of what to look for, drawn from defects observed in prior generations, they are not exhaustive, and the principle is what should drive the review on a new model where the specific defects may be different. **0. Pass 3 was actually applied (structural compliance).** Run this check **before** anything else. It is mechanical and detects the "agent skimmed past the classification step" failure mode that has caused more re-runs than every other defect combined. Walk every `### <JTBD>` heading in the SKILL.md body. For each one, locate its `**Recipe:**` block and apply this rule: - *Pointer form is one line.* The acceptable shapes are exactly: `**Recipe:** see [`references/<slug>.md`](references/<slug>.md).` or `**Recipe:** run \`scripts/<slug>.sh <args>\`.` plus optional one-sentence elaboration about exit codes. - *Inline form is ≤5 lines of bash inside a single fenced code block, no `# Step N:` comments, no branching prose between steps.* If the recipe block has step comments, multiple `semantius call` invocations in sequence, or paragraphs of "if X, refuse" between bash lines, it is **not** inline. It belongs in `references/<slug>.md` and the SKILL.md body must shrink to the pointer form. Count the JTBDs that violate one of those shapes (call this `V`) and the JTBDs Pass 3 classified as `inline` (call this `I_classified`). If `V > 0` **or** `V != I_classified`, Pass 3 was bypassed. Stop the self-review. Go back, re-classify the violating JTBDs as `reference` or `script`, write the corresponding files in `references/` or `scripts/`, and replace the inline body in SKILL.md with the pointer form. Then re-run this check from the top. Do not advance to Principle 1 until `V == I_classified`. Two separate count-based enforcements, applied after the per-JTBD shape check: - *Zero `references/` files with 5+ JTBDs:* unusual but not automatically wrong. Verify by walking each JTBD's body and confirming none of them carries a "ask the user before X" branch. Most domains have at least one such branch (charging to an inactive cost center, rewriting committed history, deleting with cascade). If you find one, it is a reference; promote it. - *Zero `scripts/` files with 5+ JTBDs:* almost certainly a misclassification. Walk each reference and apply the "user-prompt branch" test from Pass 3: does this recipe actually need the *agent* to ask the *user* something, or does it just read, compute, validate, and write? If the latter, demote it to a script. Composition rules and computed-value recompute do not count as user-prompt branches; they are mechanical and belong in scripts. Cascade flows almost always belong in scripts. **1. Self-contained at runtime.** The calling agent should never need to consult the **source model file** or a deployment-specific config to execute a recipe, the whole point of generating this skill is to condense the model's domain facts (enums, FK shapes, label rules, required fields) into the SKILL.md so the model file doesn't have to load alongside. `use-semantius` is the deliberate exception. It loads alongside this skill by design and owns the platform mechanics, CLI install, env vars, PostgREST URL-encoding, schema-management tools, cube query DSL. Pointing to a `use-semantius` reference for *platform* concerns (e.g. "see `references/cube-queries.md` for date filtering syntax") is correct and not a punt. Pointing to it for *domain* facts the generator should have resolved (an enum value, a FK target, a required-on-create field set) is a punt, fix those. Three things to scan for: - *Hardcoded literals that will rot.* Dates, timestamps, ids, the generation year, anything that was correct only at write time. Every such literal in a recipe body must become a placeholder (`<current ISO timestamp>`, `<today's date, YYYY-MM-DD>`, `<feature_id>`) with a one-line note telling the agent to fill it at call time. Hardcoded timestamps are the most common offender , search for them explicitly even if you don't think you wrote any. - *Verbatim-copied content matches the source.* The README's body §1 paragraph(s) and the `## Semantic model` mermaid block are byte-copied from the model. Re-open the model file and diff these two regions against the README; any difference means the generator paraphrased instead of copying (defect, fix in place). This is the same check Step 4's drift pass runs on already-generated skills; on a fresh write it catches the generator paraphrasing through habit even though Step 2 had the source loaded. - *Recipes that punt.* If a JTBD ends with "see `use-semantius` for the path" or "look up X in references/Y.md", the bake-in failed. Either resolve the value now (re-read the model and the use-semantius references) or, if it truly isn't knowable at generation time, keep the punt explicit and reconsider whether the JTBD passes the Step-2 merit test. A JTBD that just redirects fails the test, drop it and say why in the Step 10 summary. **2. Each fact lives in one place.** Restating the same rule in two sections doesn't reinforce it; it creates drift. Re-read the SKILL.md asking: *if this rule changed, how many places would I need to edit?* The answer should be one. - Cross-cutting rules belong in **Guardrails**; JTBD-specific recovery belongs in that JTBD's **Failure modes**. If the same sentence appears in both, delete one. - Composition rules for caller-populated labels (`{user} → {feature}`) belong in *one* JTBD plus a one-line glossary pointer, not verbatim in three places. - "What this skill does NOT do" is about scope (unbuilt features, out-of-domain tasks), not correct usage. If a bullet there overlaps with a guardrail, trim whichever side restates the other. **3. No surprises in the cheap-to-read parts.** The glossary, enums, and Cross-cutting data rules are skimmed first; the per-JTBD reference files (with their FK & shape assumptions and extended failure modes) are read on demand. Anything that will *surprise* the calling agent at write time should surface in whichever layer the agent reads before the surprise can bite, cross-cutting surprises in SKILL.md, JTBD-local surprises at the top of the reference file's recipe. - Unique constraints on natural keys (e.g. `tag_name` unique). - Delete behaviors that block writes (e.g. `restrict` on `author_id` means deleting a user with comments fails). - Required caller-populated labels on junction or sub-entities. - Built-in Semantius tables that overlap with declared entities (the model's §8 flags this, commonly `users`). The calling agent must not POST to a duplicate table. - Internal contradictions: re-read the "auto-managed fields" paragraph against every POST recipe. If any recipe POSTs a `*_label` value, the auto-managed paragraph must carve those fields out explicitly; otherwise an agent skimming the glossary will conclude it can omit them. **4. Recipes match the platform conventions.** The use-semantius references encode how the platform actually works; the generated skill should follow the same patterns so it composes cleanly. - Fuzzy text search uses `search_vector=wfts(simple).<term>`, never `ilike` or `fts` (those bypass the search index). - Field-equality (`<column>=eq.<value>`) is for known-exact values (ids, enums, unique keys), not banned, just a different tool than fuzzy search. - Read-before-write on junctions without DB-level uniqueness. - Audit-logged tables don't need explicit audit writes; recipes don't manage them. - **No recipe re-derives a `computed_fields[].name`.** Walk every POST/PATCH body in every reference and inline recipe; if any of them writes a column listed under "Platform-derived fields" in the SKILL.md preamble, the recipe is wrong (the platform overwrites it). Drop the field from the body. The post-write read-back is fine and encouraged. - **No recipe pre-validates a `validation_rules[].code`.** Walk every reference's branching prose; if it duplicates a check the platform already enforces (e.g. "refuse to attach a release_id when status isn't planned/in_progress/shipped" when `release_only_when_committed` is in the model), drop the client-side check and rewrite the JTBD's Failure modes block to name the platform `code` and the recovery action instead. Duplicated checks are brittle and confuse the agent about who owns the rule. - **No recipe duplicates a `select_rule` in its own filter** (analyst v2.2+). Walk every GET path against an entity that appears in the `row_visibility_rules` index. If the path adds a filter that re-encodes the rule (e.g. `submitter_user_id=eq.$user_id` against an entity whose `select_rule` already filters on the same column), drop the duplicate filter. The platform applies the rule via RLS; the client-side duplication is dead code that breaks the moment the analyst updates the rule. Recipes against a scoped entity should read with the natural query and let the platform filter; the user-facing scope reminder lives in the JTBD preamble (sourced from the SKILL.md "Row-level read scope" block). - **Every read recipe against a row-scoped entity carries a visibility callout**. For every JTBD whose Recipe reads an entity that appears in the `row_visibility_rules` index, the JTBD's preamble or Inputs block must contain a one-sentence scope reminder ("every caller with `view_permission` sees only rows where `<plain- English uniform predicate>`"). A read recipe on a scoped entity without that reminder is the silent-empty-result defect: a missing row is indistinguishable from no-such-row, and the agent (or the user) draws the wrong conclusion. Pull the scope sentence from the SKILL.md "Row-level read scope" preamble. - **No recipe promises a `view_all_<plural>`-style permission bypass** ) critical rule). Walk every preamble line, every JTBD visibility callout, every Failure-modes block. If any prose names a permission code as a way to "see every row" / "bypass the filter" / "broader read access" / "elevated tier" / similar, the corresponding `Select rule` JsonLogic must literally reference that permission code via `{"require_permission": "<code>"}` or an equivalent platform operator AND the model's §7 must resolve the architectural decision. A prose claim about permission bypass with no JsonLogic reference and no §7 entry is the **canonical v2.2 defect** the audit exists to catch — the prose promises something the platform does not honor, and the calling agent ships with broken RBAC. Fix by either deleting the bypass prose (rule applies uniformly; broader access goes through human escalation), pointing at a real documented mechanism from §7, or routing the user back to `semantic-model-analyst` to resolve Stage 12 / Stage 12.5 properly. - **Every transition JTBD that fires a `conditional_required_fields` trigger writes the dependent field in the same PATCH** (analyst v2.2+). Walk the `conditional_required_fields` sub-index from Step 2. For every `(entity, trigger_field, trigger_value, dependent_field)` tuple, find the JTBD whose Recipe PATCHes the trigger field to the trigger value. The Recipe body must include the dependent field in the same PATCH body. A transition that sets the trigger without the dependent is the silent-empty-housekeeping-field defect — the UI would have rendered `dependent_field` as `required` at form time, but the API recipe has no form. Fix: add the dependent to the PATCH body with the correct value (typically `$now` for `*_at` fields, `$user_id` for `*_by` fields). - **No recipe interprets the JsonLogic of an `input_type_rule`** (analyst v2.2+). The rule is for the form-rendering layer, not for the recipe. Recipes drive their transition semantics from the JTBD's own intent (the analyst's prose, the `validation_rules`, the trigger condition captured in `conditional_required_fields`), not by re-evaluating the `input_type_rule` body. A recipe with a branch like *"check whether `input_type_rule` would have rendered this field as `hidden` for the current record"* is wrong — drop the branch, let the recipe's own preconditions decide. If a new platform convention shows up in the use-semantius references that this list doesn't mention, treat the principle ("match the platform") as the authority and add the new convention to the recipes , the bullets above will lag. **5. Recipes are reproducible.** Two callers given the same inputs must produce byte-identical output. Most "weird drift" bugs in generated skills trace to phrases that *seem* deterministic but are not. - *Composition rules are exact.* For every caller-populated label field (`*_label` on a junction or sub-entity), the rule names a precise algorithm: separator characters (with whitespace), cut points (column counts on which side of which boundary), fallback when the input is shorter than the cut, casing. Phrases like "first ~80 characters", "trim at a word boundary if possible", "approximately N", "around" are bans, replace with rules a script could implement: "first 80 chars of `comment_body`; if char 80 falls mid-word, cut at the last space at or before position 80; if the body was longer than the cut, append the literal `…` (U+2026), no trailing space." - *Symbols are consistent across the file tree.* If the composition uses ` -> ` (ASCII), every example, every guardrail, every validation note uses ` -> `; do not mix ASCII and Unicode arrows (`→`), do not switch separators between examples (` / `, ` | `, ` -> `). Pick one set per skill and apply. - *Computed values specify rounding.* A formula like `(reach * impact * confidence) / effort` over a `numeric(p, s)` column with `s = 2` requires the recipe to round to 2 decimals before the PATCH; otherwise the float-to-stored cast truncates the value and the `Validation` post-condition ("`rice_score` equals the formula") fails on a tiny rounding diff. Name the scale and the rounding behavior in the recipe. - *Side-effect timestamps are placeholders.* Every `*_at`, `*_date`, `submitted_at`, `voted_at`, `posted_at`, `actual_release_date` field in a recipe body is a placeholder, the rule lives once at the SKILL.md top level, the per-JTBD reminder has been deleted. Re-search the file tree for hardcoded ISO dates and ISO timestamps; any hit is a defect. **6. Cross-section coherence.** Each fact stated in one place must not be silently contradicted in another. - *Inputs tables match routing rules.* If a JTBD's prose says "for status X, route to JTBD Y instead", then X must not appear in this JTBD's `Inputs` table as a valid value. The contradiction forces the agent to guess. Drop X from the table and say outright which targets this JTBD owns. - *Cube queries reference columns the glossary names.* If `Common queries` uses `<Entity>.sum_<column>` or `<Entity>.<dimension>`, the underlying column must appear in the glossary, in some reference file's FK & shape assumptions, or in the "what the entity carries" line. A query mentioning `Features.sum_estimated_cost` with no `estimated_cost` named anywhere else in SKILL.md leaves the agent unable to verify the field exists; it will guess and write a query that 500s. - *SKILL.md outlines and reference files agree on the recipe shape.* Open the reference file and read its `## Recipe`. The steps, the writes, and the validation must match what SKILL.md's `Validation` and `Failure modes` summary claim. If the SKILL.md failure-modes mentions a `409 on <column>` and the reference recipe never POSTs to that column, one of them drifted; fix. - *Reference-file slugs match SKILL.md links.* For every `references/<jtbd-slug>.md` link in SKILL.md, the file exists at that exact path. For every reference file written, the SKILL.md links to it. List both sets and diff. - *Script names match SKILL.md invocations.* For every `scripts/<op-slug>.sh` mentioned in a SKILL.md `Recipe:` line, the script exists, and its `Usage:` comment matches the args the SKILL.md tells the agent to pass. - *Every trigger phrase in the description is answerable from what the skill already provides.* For every quoted phrase in the SKILL.md frontmatter `description`, the agent must be able to fulfill it from one of: (1) a JTBD section in `## Jobs to be done` (the trigger maps to a recipe), (2) a literal example in the `## Common queries` appendix (the trigger is essentially that query), (3) the established pattern in the Common-queries appendix the agent can adapt (e.g. swap a measure or filter; appendix examples are intentionally pattern-establishing, not exhaustive), (4) the `## Lookup convention` block (e.g. "who has asset X" → `serial_number=eq.X&select=current_user_id`; this works as long as the convention block names the column). Each backing type is legitimate; the goal is not 1:1 recipe coverage, it is that an agent with the skill loaded does not have to guess column names, FK shapes, or query shapes from outside the skill. Triggers backed by (2)–(4) are not a fallback; they are an **encouraged** pattern. See Step 5 "Trigger phrasing" for the action-vs-discovery split: a healthy description carries both, because discovery triggers (lookups and reports) are how the catalog reader sees the breadth of the model, and they are how the skill makes those queries deterministic for users who install it. A trigger fails this check only when none of (1)–(4) applies: the agent would have to invent a recipe, infer a relationship the skill never names, or look up enum values not in the glossary. In that case the fix is one of two things: (a) drop the trigger from the description and the README's sample prompts; (b) add the missing backing (usually one new Common-queries example, occasionally a new JTBD if the merit test passes, or a one-line addition to the lookup convention). Run this check **before** the README cross-check so the catalog list inherits a clean trigger set. **7. Scripts handle real-world inputs.** Pre-existing structural checks pass on scripts that would still 4xx in production the moment a real catalog name with a space hits them. Walk every file in `scripts/` AND every inline bash recipe in SKILL.md and run these literal-text scans. Each is mechanical and detects a class of bug the earlier principles miss because the offending lines look fine in isolation. - *Raw `$var` interpolation into a URL path.* Regex-scan every `semantius call crud postgrestRequest "{...}"` invocation for `$<varname>` or `${<varname>}` appearing inside a `path` value in a position that is **not** preceded by an `=eq.` against a known-UUID variable (`id`, `<entity>_id`). Every other interpolated value (search terms going into `wfts(simple).<term>`, exact-match filters whose value is a caller string like `alias_name=eq.<value>` or `relationship_verb=eq.<value>`, value lists in `in.(...)` filters) must come from a pre-encoded variable produced by `printf '%s' "$raw" | jq -sRr @uri`. A line that interpolates raw `$user_input` into the URL is a defect. Most catalog names contain spaces (`Customer Management`, `Investment Banking`, `Service Desk`); raw interpolation silently mangles them. Fix in place: introduce `enc_<name>=$(printf '%s' "$raw_<name>" | jq -sRr @uri)` and reference `${enc_<name>}` in the path. - *String-concatenated JSON bodies.* Scan every script for the shapes `body="{` or `body="$body,` or any line that builds a JSON body by appending interpolated `"$var"` fragments. Every body must be built with `jq -nc --arg <key> "$<var>" ... '{...}'`. The naïve concatenation pattern fails the moment a caller value contains a `"`, a `\`, a newline, or a control character; research-agent prose is full of these. The platform surfaces a generic JSON parse error rather than the validation error the recipe was trying to test. Fix in place: rewrite the body using `jq`, using `--argjson` for booleans / numbers / nested objects and `--arg` for strings. - *Optional columns written without a per-entity guard.* For every script that accepts an optional arg corresponding to a column (`notes`, `description`, `condition_notes`, `is_preferred`, any arg whose name matches a column on *some* but not *all* targeted entities), walk back to the model's per-entity field list (from Step 2's parse) and confirm the script enforces the entity- carries-this-column check before composing the body. A polymorphic script that unconditionally writes `notes` against an `entity` arg will 4xx on every entity that lacks a `notes` column; the platform's `column "notes" does not exist` response is opaque to the agent. Fix in place: bake the supports-column entity list into the script (computed at generation time from the model's §3) and refuse the caller's arg with a precise stderr message when the target entity does not carry the column. The Step 7 template shows the canonical case-statement form. - *`--single` vs array misuse on caller-driven lookups.* For every fuzzy `wfts(simple).<term>` read, the recipe's intent is one of two things, "the term must resolve to exactly one row or the recipe cannot proceed" (use `--single` with a one-line guard) or "zero matches is a normal branch, ambiguous needs the candidate list" (use array-default with a two-step body inspection). Mixing these silently mis-reports: a `--single` read on an ambiguous match exits 2 (which the script may handle as "platform error" rather than "user must disambiguate"); an array read whose code path assumes `--single`'s bare-object shape mis-parses every row. Fix in place per the use-semantius `Pattern A` / `Pattern B` convention. The fix for each defect is in-place rewriting of the offending script lines, not "flag in summary and ship". Step 9 is a gate, not a status report. Re-run this principle until every script passes all four scans. **Final pass: read it cold.** After applying principles 1–7, set the files aside for a moment, then read SKILL.md top-to-bottom as if encountering it for the first time, and skim each reference file once. Where you backtrack, re-read, or pause to figure out what a sentence means, the writing is doing more work than it should. The specific defects that show up here are usually patterns the earlier principles missed because they were too local: a glossary that introduces a term still used unexplained in a JTBD three sections later, a guardrail that contradicts a JTBD's failure-mode recovery, a "see X" pointer where X never quite delivers what the pointer promises. Tighten in place. --- **README cross-check.** The README is for humans browsing a catalog, so different failure modes apply. Run these as literal-text scans, not vibes. If any check fails, fix and re-scan before declaring done. 1. **File exists.** Both `SKILL.md` and `README.mdx` are present in the target folder. 2. **Em-dash scan.** Literal-search the README for Unicode codepoint U+2014 (the em-dash, the long horizontal dash, distinct from the shorter hyphen `-` and en-dash `–`). Must be zero hits. Replace each with commas, colons, parentheses, or split sentences. The user has flagged em-dash use repeatedly. 3. **"this skill" scan.** Literal-search the README (case-insensitive) for the substring "this skill". Must be zero hits. Rewrite any sentence that uses it. The catalog renders many cards side by side and "This skill helps with..." openings make the list unreadable. 4. **Headings: one rule per file, do NOT make them match.** - **SKILL.md H1**: must equal `system_name` verbatim. No "Skill" suffix (the file is `SKILL.md`, the word would be redundant), no "domain" prefix, no rewording. For `system_name = "Applicant Tracking System"` the only valid SKILL.md H1 is `# Applicant Tracking System`. - **README.mdx H1 and front-matter `title`**: must be identical to each other and must follow Title grammar: contain "Skill" with capital S as a standalone word, no "domain" anywhere, no lowercased "skill", trailing "System" dropped from `system_name` before " Skill" is appended. For the same `system_name` the only valid README H1 is `# Applicant Tracking Skill`. Reject for the README: `# Applicant Tracking System Skill`, `# Applicant Tracking System domain skill`, `# Applicant Tracking System`, `# Applicant Tracking domain skill`, and any other variant. Reject for the SKILL.md: anything that adds "Skill", "domain", or rewords the system name. 5. **Model description paragraph is verbatim from §1.** The first body paragraph(s) under the heading are a verbatim copy of the model file's §1 narrative. Diff against the source model. No paraphrase, no summary. - **No orphan `domain` line.** The `domain` frontmatter is ignored when building the README body (it is always a short category tag like `ATS`, `CDP`, `ERP`). If the README starts with such a short word or acronym on its own line under the heading, the `domain` tag was wrongly pasted as a body paragraph. Delete it. The §1 narrative is the only source for this section. 6. **Skill explanation paragraph passes the non-technical reader test AND does not duplicate the trigger list.** Verify there is a second paragraph between the model description and `## Sample prompts`. Run these literal scans on that paragraph; any failure means rewrite, not patch: - **Not a copy of the front-matter `description`.** Diff against the front-matter `description`. They must share the value-prop but not the words. - **Three-noun definition is present.** Sentence 1 names the model and what it tracks/plans/manages/captures (model). The skill is named by its title (not "this skill") and explained as "teaches an agent how to use that model to <verb> <its jobs> reliably and the same way every time". The paragraph ends with two or three concrete failure modes. - **Domain verb extracted from `system_name` (three-tier).** Run the three-tier resolution and verify the verb actually used in sentence 1 matches. - **Tier 1 fail:** if `system_name` ends in `Tracking|Tracker|Planning|Planner|Management|Manager|Budgeting|Scheduling|Scheduler|Forecasting|Reporting|Monitoring|Routing|Booking|Provisioning`, the bare verb (track, plan, manage, budget, schedule, forecast, report, monitor, route, book, provision) must appear in sentence 1. - **Tier 2 fail:** if `system_name` contains `Roadmap|Inventory|Ledger|Directory|Registry|Pipeline|Catalog|Calendar|Knowledge Base|KB|Dashboard|CRM|Helpdesk|Service Desk`, the corresponding implied verb (plans, tracks, records, lists, registers, moves, lists, schedules, answers, surfaces, tracks, resolves) must appear in sentence 1. - **Tier 3 misuse:** using a fallback verb (`captures`, `holds`, `describes`, `lays out`, `organizes`, `maps`) when Tier 1 or Tier 2 would have fired is a fail. Rewrite using the matched verb. The verb in the front-matter `description` must be the same. - **Pattern test (catalog uniqueness).** Mentally substitute "X" for the model name everywhere in the paragraph. The result must NOT read as something that could apply to any other skill in the catalog. The verb-extracted noun and the failure stories should make the paragraph unmistakably about this one model. Generic openers like "The system has a handful of multi-step moves", "Loading the domain knowledge means", "Multi-step writes are not enforced" are a fail. - **No duplication of the trigger bullet list.** Read the paragraph and the rendered `## Sample prompts` list together. Comma-strung verb lists that mirror the bullets are a fail. - **No band-aid framing.** Phrases like "the platform does not enforce", "the database does not catch", "multi-step writes not enforced" frame the skill as patching a defect. Replace with the positive three-noun definition. - **No LLM-engineer language.** Scan for "non-deterministic", "deterministic", "stochastic", "improvises", "drift between runs", "reproducible output". Catalog readers do not think of agents that way. Use "the same way every time". - **No identifier-shaped tokens.** Regex `\b[a-z][a-z0-9]*(_[a-z0-9]+)+\b` matches snake_case (`approved_at`, `originated_from_action_id`, `headcount_actions`). Zero hits. - **No mechanics jargon.** Case-insensitive scan for `writes`, `rows`, `calls`, `PATCH`, `POST`, `API`, `schema`, `column`, `FK`, `foreign key`, `constraint`, `uniqueness`, `join`, `table`, `query`, `back-pointer`, `cascade` (noun). Zero hits. - **No `use-semantius`**, no CLI commands, no file paths, no code fences. - **No "this skill"** substring, does not start with "This skill". - **Carries two or three concrete failure modes** in plain domain words, semicolon-separated. Phrased the way a domain expert would describe a bad day: "an offer can go out with no recorded approver", "two people can end up on the same seat". - **Domain nouns use user labels, not table names.** Cross-check against the model's `singular_label` values. - **Skill self-reference is by title.** Look for `# <Title>` H1, then verify the paragraph refers to the skill as "the <Title>" (e.g. "the Applicant Tracking Skill"), not as "this skill". - **Banned literal phrase: "lays out what the system can record".** That was an example, not a template. Paraphrase based on the model's actual flavor and the extracted verb. 7. **`description` follows the verb-led capability shape.** One sentence, ≤140 characters, written for a non-technical reader. The description names *what the skill does* by listing the actual capabilities/lifecycle stages of the domain, not by justifying the skill with a "so [outcome]" benefit clause. Run these literal scans: - **Shape:** `<Verb><s> <domain object> <list of lifecycle stages, operations, or artefacts>`. The verb is the same one extracted for paragraph 2 (`tracks`, `plans`, `manages`, `budgets`, `schedules`, `forecasts`, `reports`, `monitors`, `routes`, `books`, `provisions`) or the fallback (`Captures`, `Holds`, `Maps`, `Organises`, `Records`, `Resolves`). - **Banned shape: "so [outcome]" clause.** If the description contains ` so ` followed by a benefit/outcome clause (e.g. "so the right pieces always get filled in in the right order", "so renewals never fall off the calendar", "so two people never end up on the same seat"), it is using the body paragraph's value-prop shape instead of the catalog's capability shape. Rewrite to list the actual capabilities (workflow stages, operations, artefacts) instead. Also banned: ` while `, ` with ` followed by an outcome clause. - **Banned starters and substrings:** `Bakes in`, `bakes in`, `baked in`, `Bakes the`. Catalog readers do not know or care that anything is baked. Replace with the extracted verb. - **No mechanics jargon** in the description: `multi-step rules`, `paired status fields`, `paired writes`, `cascade`, `invariants`, `knock-on changes`, `multi-table cascade`, `seat-cascade`. Same ban list as paragraph 2. - **No identifier-shaped tokens** (snake_case regex from item 6). - **No "This skill", "A skill for", "Domain skill for", "Skill that".** Lead with the verb. - **No restatement of the system name.** "The Applicant Tracking System ..." is bad; the title already says it. - **Verb coherence with paragraph 2.** The description's verb must match the verb extracted for paragraph 2 (same Tier 1/2/3 resolution). The description names the *capabilities* (catalog card view); paragraph 2 carries the *value-prop* (failure modes). They share the verb but not the shape. 8. **No provenance keys in front matter.** Exactly two keys: `title` and `description`. No `generated_from`, no `semantic_model`, no other key. 9. **Mermaid is the model's mermaid, byte-for-byte.** Diff the ```` ```mermaid ```` block in the README against the one in the source model file. They are identical. Any difference means the diagram was regenerated instead of copied. 10. **Sample prompts: concrete user-voice sentences, mapped to backings.** The README's `## Sample prompts` list and the SKILL.md frontmatter `description` are **independently authored** with different shapes: the description carries abstract verb-phrase intents, the README carries concrete user-voice sentences. They do not share wording. Run these checks on the README's sample-prompts list: - **Volume.** 12–17 bullets. Below 12 the catalog list looks thin; above 17 it dominates the page. - **Concrete user-voice phrasing.** Each bullet is a sentence a real person would type, in casual or natural register. Reject bullets that read as abstract intent phrases (e.g. `"return a hardware asset"` is wrong; `"Bob is leaving, return his laptop"` is right). The description is where intent phrases belong, not the README. - **Action vs discovery split.** 8–11 action prompts (concrete phrasings of JTBD intents, multiple synonyms welcome) plus 4–6 discovery prompts (concrete lookup or report questions). - **Backing per Principle 6.** Each action prompt maps to a JTBD section; each discovery prompt maps to a Common-queries example, its adaptable pattern, or the lookup convention. Unbacked prompts are leaks: drop or back. - **No literal user-voice quotes appear in the SKILL.md description.** Run a separate scan on the description: if it contains quoted full-sentence user phrasings (e.g. `"Bob is leaving, return his laptop"`), that is matcher signal pollution. The description should enumerate intent classes ("return or unassign a hardware asset"), not list literal phrasings. Strip the quoted sentences from the description; the equivalent concrete phrasings stay in the README sample prompts. 11. **`## What it covers` is present, ordered, and well-shaped.** The section sits between `## Sample prompts` and `## Semantic model` (this order is load-bearing: prompts hook the reader, capabilities anchor the scope check, the diagram closes with the visual). Run these literal scans: - Section heading is exactly `## What it covers`. - Bullet count is in `[5, 7]`. Fewer reads as thin; more reads as a feature dump. - Each JTBD bullet leads with a verb and is under ~12 words. The trailing `Common reports: ...` bullet is the one structural exception, it leads with the noun phrase "Common reports:" and may run longer (it lists 3–5 themes separated by commas); apply only the no-jargon and no-identifier scans to it. - No script names (regex `\.sh\b`), no file paths (regex `/` followed by lowercase), no snake_case identifiers (regex `\b[a-z][a-z0-9]*(_[a-z0-9]+)+\b`), no jargon from the banned mechanics list (Principle 6's body-paragraph bans apply here too: writes, rows, calls, PATCH, POST, FK, cascade, etc.). This applies to every bullet, including the Common reports bullet. - The bullets cover, in order, the same JTBDs the SKILL.md's `## Jobs to be done` lists, with adjacent related JTBDs grouped into single bullets where natural (e.g. deploy + return + retire collapse to one bullet about hardware lifecycle). The Common-queries appendix is summarized in a single trailing "Common reports: ..." bullet, not split. - No bullet duplicates a sample prompt. The prompt list is user-voice phrasing; the capability list is action scope. Overlap means the capability list isn't earning its place. 12. **No `use-semantius` mentions** and no agent-harness jargon anywhere in the README. **Output of the self-review.** Report **per-principle**, not "no issues found" as a single line. For each of Principles 0–7 plus the README cross-check, write either: - the fix you made, in one phrase (e.g. "Principle 1: replaced 3 hardcoded timestamps with placeholders"); or - the evidence that the principle was *actually scanned* against the generated files (e.g. "Principle 7 URL-encoding scan: 14 interpolation sites checked, all routed through `jq -sRr @uri`"; "Principle 7 JSON-body scan: 9 bodies checked, all built via `jq -nc`"; "Principle 7 column-existence scan: 2 polymorphic scripts have entity-supports-column guards on `notes` arg"). "Self-review pass, no issues found" is **not an acceptable form** without the per-principle evidence, because the most common defect in prior generations was the generator declaring no issues while having skipped a principle entirely. Behavioral correctness (does the script actually run on real catalog names?) is checked by Principle 7, not by Principle 0; a Principle 0 pass plus a missing Principle 7 line is the recurring failure mode this report shape is designed to catch. If a principle has nothing to check on a given generation (e.g. no scripts written, so Principle 7's script scans are vacuous), say so explicitly: "Principle 7: no scripts written, vacuous." --- ### Step 10, Summarize Print to the user: - The folder created: `<skills-root>/<modelslug>/` (state which root was used, project or user) and the files inside it. The two top-level files (`SKILL.md`, `README.mdx`) are required, missing either means the run is incomplete. List `references/` and `scripts/` contents if any were written. - The **sections written** (one bullet each), with the merit signal that earned the spot **and** the Pass-3 classification, e.g. - "Vote on a feature, junction without uniqueness + caller-populated label, **reference** (`references/cast-vote.md`)" - "Ship a release, cascade flow, **script** (`scripts/ship-release.sh`)" - "Capture a feature, simple POST with no branching, **inline**" - The **Common queries** baked into the appendix (titles only). - The **dropped candidates** with reasons (e.g. "manage-tag, pure CRUD on `tags`, no merit signal, calling agent uses use-semantius directly"). The user may ask to add some back. - The **platform-enforceable gaps** from Pass 2's tracking, when any. One bullet per gap (entity, field, kind, §3-prose evidence), and whether the user chose to proceed with the stopgap recipe or paused to fix the model. This survives in the user's audit trail so a later regeneration can confirm the gap was either closed (model now carries the rule, no gap reported) or knowingly accepted again. - The **self-review result** from Step 9, **one line per principle (0 through 7 plus the README cross-check)**, in the per-principle evidence shape required by Step 9's "Output of the self-review". Either the fix made or the explicit scan-evidence; a collapsed "no issues found" line is rejected by Step 9 and must not appear here. The Principle 7 lines in particular must name a count of interpolation sites / JSON bodies / polymorphic-column guards inspected, not just "passed", because that was the principle prior generations skipped most often. Example shape: - "Principle 0: 7 JTBDs, 0 inline / 0 reference / 7 script; Pass 3 alignment confirmed." - "Principle 1: replaced 2 hardcoded timestamps with placeholders; §1 paragraph and mermaid byte-match the model." - "Principle 4: dropped a client-side discriminator pre-check in `add-alias.sh`; failure-modes now name the platform `code`." - "Principle 7 URL-encoding: 12 interpolation sites scanned, all routed through `jq -sRr @uri`." - "Principle 7 JSON bodies: 9 bodies scanned, all built via `jq -nc --arg`." - "Principle 7 column-existence: `promote-record.sh` now refuses `notes` arg on entities without a `notes` column (7 entities listed)." - "Principle 7 `--single` vs array: 14 reads scanned, classified per use-semantius Pattern A / Pattern B." - "README cross-check: 12 checks, all pass." - The **file-tree size profile**, one line: `SKILL.md <N> lines, references/ <M> files (<lo>-<hi> lines each), scripts/ <K> files`. Surfacing this gives the user a feel for whether the split landed in a reasonable place; a 700-line SKILL.md with empty `references/` is a signal the classifier was too conservative. - The **audit findings** from Step 4. On a fresh generation Step 4 is skipped (there are no pre-existing artifacts to audit), but the bullet still appears, with the wording **"Fresh generation; Step 4 audit skipped. Behavioral correctness of the freshly- written files is covered by the Step 9 self-review above (Principle 0 structural + Principle 7 script-robustness)."** Do not collapse to "nothing to audit", that wording invites the generator (and the user) to read it as "behavioral correctness was also skipped", which is exactly the failure mode the per-principle self-review report is designed to prevent. On a regeneration, replace the fresh-generation sentence with the real findings, grouped by file and severity: - **Defects** (file is broken; rewrite recommended): e.g. "`references/score-rice.md`: linked from SKILL.md but missing on disk." - **Non-canonical** (works but uses an outdated pattern; user decides): e.g. "`cast-vote.sh`: 4 reads use legacy two-guard pattern, `--single` would simplify." - **Orphans** (no JTBD with this slug in current plan): e.g. "`tag-feature.md`: orphan; consider removing or restoring the JTBD." After listing, ask: *"Regenerate flagged files? (all-defects / all-flagged / per-file / none)"*, default `all-defects`. The user picks; Steps 5–7 rerun for the chosen subset, files outside the subset stay untouched. --- ## What this skill does **not** do - It does not run `semantius` itself, recipes are written, not executed. - It does not deploy the model, that's `semantic-model-deployer`. - It does not generate evals, add via `skill-creator` later. ## Re-running on an updated model Regenerate into the same target folder. The flow is: 1. **Step 4 audits the existing artifacts** (read-only) and produces a findings list grouped by defect / non-canonical / orphan. See Step 4 for the checks it runs. 2. **Step 10 surfaces the findings to the user** and asks which flagged files to regenerate (default: defects only). 3. **Steps 5–7 write the chosen subset.** `SKILL.md` and `README.mdx` are always rewritten because they always need to reflect the current generation's plan; references and scripts are rewritten only for files the user opted to regenerate. Files outside that subset stay untouched, including hand-edited ones. Orphans (files for JTBDs that no longer exist in the current plan) are surfaced in the audit but not auto-deleted. The user may have referenced them externally or be mid-edit. The Step 10 summary names each orphan and asks; default is to keep. Hand-edits stay safe by default. The `README.mdx` and reference files attract domain-expert hand-edits (narrative copy, failure-mode wording, user-prompt phrasing); the audit treats those edits as authoritative unless the file has a real defect (broken link, missing required field, contradicts the model). For non-canonical patterns alone, the user decides whether to take the upgrade. ## Rebuild from scratch (Mode D) A holistic regeneration of the entire generated skill folder, distinct from the conservative "Re-running on an updated model" flow above. The conservative re-run preserves hand-edits and rewrites only defective files; Mode D throws out the prior generation entirely and re-derives every artifact from the current model, treating the prior folder as **archived knowledge** for lessons learned but never as a structural constraint. ### When to choose Mode D Trigger phrases the user is likely to use: - "Rebuild / reanalyze / re-author the `<slug>` skill from scratch." - "The model has drifted across many iterations, regenerate everything." - "Throw out the existing skill folder and start over." - "We accumulated cruft in the generated skill, I want a fresh pass." ### When *not* to use Mode D - The model has minor changes and you only want to update affected files, use the conservative **Re-running on an updated model** flow (the default re-run behavior). - The user wants to preserve hand-edits to README.mdx narrative or reference-file copy, use the conservative flow. Mode D rewrites everything. - The user wants audit-only (no writes), run Step 4 alone and stop without proceeding to Step 10's regeneration prompt. - The model file's major differs from `EXPECTED_MAJOR`, refuse and route the user to the analyst's Mode D Rebuild on the model file first; this skill cannot rebuild a generated skill from a stale-major model. ### How a rebuild runs 1. **Run Steps 1–3 as if generating from scratch.** Re-parse the current model file and re-derive jobs to be done from first principles. Do **not** consult the prior `SKILL.md` or its reference files for the JTBD list, the model is the only input. Reading the prior generation here would import its biases and defeat the point of a rebuild. 2. **At Step 4, the audit's role flips.** Instead of producing a "regenerate this defective file" list, it produces a "lessons from the prior generation" list, surfaced for the user at Step 10. Look for: - Hand-edited narrative copy in README.mdx or reference files that captures domain nuance not in the model (rare; surface so the user can paste relevant bits manually after the rebuild lands). - JTBDs present in the prior plan that no longer have a model basis (likely intentional drops; surface as "removed"). - Guardrails or domain-glossary entries that look user-customized (preserve verbatim only if the user explicitly opts in at Step 10). - Orphan files (JTBDs that no longer exist in the rebuilt plan); surfaced but never auto-deleted. 3. **Steps 5–9 write a complete fresh folder.** Default target: a sibling folder `<skills-root>/<slug>.rebuild/` so the prior survives for diffing. Overwriting `<skills-root>/<slug>/` directly is allowed **only after explicit user confirmation** at the Step 10 summary gate. 4. **Step 10 shows the diff before overwriting.** The summary names: JTBDs added / removed / renamed, references regenerated, scripts regenerated, and any hand-edits the audit flagged for manual carry-over. Ask: *"Does this rebuild look right, or anything to keep from the prior folder?"* Loop until confirmed. No overwrite of `<slug>/` until the user says yes. ### What carries over - **Nothing structural by default.** The semantic-model file is the single source of truth; prior artifacts are not. The rebuilt SKILL.md, README.mdx, references, and scripts are derived fresh from the model. - **Hand-edited content** (README narrative, reference-file failure-mode wording, guardrail prose) is surfaced in the Step 10 diff for opt-in manual carry-over. The skill does not auto-merge; the user pastes the bits they want to keep into the rebuilt folder. - **The target folder name** (`<slug>/`) stays the same unless the user explicitly renames the system, in which case follow the slug change loudly per the front-matter rules in Step 5 (a slug change breaks any external references to the prior folder). ### What this is not - **Not the conservative re-run.** That preserves hand-edits and rewrites only defective files. Mode D rewrites everything. - **Not a fix-up of broken artifacts.** Use Step 4 audit + Step 10 subset selection for that, the conservative flow handles it correctly. - **Not an upgrade path for major-version mismatches.** Major mismatch is rejected at Step 2; the user must re-author the model via `semantic-model-analyst` Mode D Rebuild first, then re-run skill-maker (any flow) against the fresh file. --- ## Failure modes - **Model file's `version` major differs from `EXPECTED_MAJOR`** (or `version` is missing), refuse. The model is from a different schema era and recipes would bake in stale patterns. Tell the user to run `semantic-model-analyst` to re-author the model at current major (archived-knowledge mode handles older files), then re-run skill-maker against the new file. - **Model file missing required frontmatter**, stop and ask. Don't guess `system_slug`. - **Model file has open §7.1 blockers**, refuse. Tell the user to resolve blockers in `semantic-model-analyst` first. - **Conflicting target folder**, if `<skills-root>/<modelslug>/` already exists and the SKILL.md was not generated by this skill (no link back to the model file in its header), stop and ask before overwriting. - **JTBD count > ~12 after filtering**, Step 3.5 (Cluster check) runs and may surface a clean two-skill split. If it does, the Confirmation checkpoint already presents the split as a fourth list; no separate warning needed. If Step 3.5 finds no clean cut (the model really is one tightly-coupled big domain), warn the user that the resulting one-skill description will under-trigger and ask whether to drop lower-merit candidates or split the model file itself. Proceed with one oversized skill only if the user confirms.