--- name: usdl-composition-skatchbook description: Element-targeted Skill that opens a Skatchbook scratch entry alongside one Composition component whose intent or structure is unclear, walks candidate code abstractions (port, strategy registry, pipeline, state machine, factory, adapter, etc.) through small examples, and once the Spec author picks one, hands the parent skill the chosen abstraction's architectural shape (component `` prose and a `` Element with ``/`` children) for writing to composition.xml via Bin. Trigger this Skill when the active task mentions "component", "structure", "abstraction", "Skatchbook", "scratchbook", "sketchbook", "experiment with shapes", "candidate pattern", "I'm not sure which shape", "try this abstraction", "port vs strategy", or any phrase about experimenting with a code shape before committing it to the Spec. Not user-invocable directly; surfaced as a See-Also Reference from usdl:composition (per `beh.rule.peer-skill-cross-reference`) and preloaded by `top.agent.composition-author` and `top.agent.interfaces-author`. The bundled `scripts/scratch-runner/` opens scratch entries and translates the chosen abstraction into a USDL Composition fragment; the parent skill then calls `usdl content`/`usdl validate` through `usdl:bin` to write the fragment into composition.xml. Strips filenames and function signatures before any fragment leaves the Skatchbook. Carries no executable code. --- # usdl-composition-skatchbook ## What this Skill is This is the element-targeted Skill that runs a **Skatchbook session** (`term.skatchbook`) alongside **one Composition component** whose intent or structure is unclear. It exists so the Spec author can experiment with one or more candidate code abstractions in a scratch space before any architectural commitment is written to `composition.xml`. It is **not user-invocable directly**. It is surfaced as a **See-Also Reference** from `usdl:composition` (per `beh.rule.peer-skill-cross-reference`) and preloaded by `top.agent.composition-author` (and by `top.agent.interfaces-author` when a contract derivation also needs a structural sketch). The agent host loads it when `usdl:composition` recognises that a component's intent is too vague to draft a useful `` block or to pick the right `` references. The use case it implements is `beh.experiment-in-skatchbook`. ## How it fits with peer Skills - **Parent (See-Also source):** `usdl:composition` — the section-spanning Skill. When the composition interview reaches a component whose intent or shape is unclear, `usdl:composition` names this Skill in its response so the host may load it. - **Spec mutation authority:** `usdl:bin` — wraps the `usdl` CLI. Every change to `composition.xml` is made by the parent Skill calling `usdl` subcommands; **this Skill and its bundled scripts never write Section files** (`con.skatchbook-no-direct-spec-writes`). - **Template authority:** `usdl:templates` — owns `templates/composition/component.xml` and `templates/composition/constraint.xml`. The fragment this Skill emits must conform to those Templates before the parent Skill writes it. - **Sibling Skatchbook user:** `usdl:interfaces:contracts` — uses the same Skatchbook store (`top.skatchbook-store`) for schema derivation. Both peers obey the same no-direct-spec-writes rule. They do not call each other; the host routes. - **Peer Element Skills (informational only):** `usdl:behaviour:usecase`, `usdl:behaviour:nfr`, `usdl:topology:services`, `usdl:topology:communication` — siblings; none are called from here. This Skill does not invoke peers. It surfaces information so the host can route, per `beh.rule.peer-skill-cross-reference`. ## Authoritative inputs Before opening a scratch entry, the Skill loads: 1. The target component's draft `` from the parent Skill (the prose the author has so far — possibly only a sentence; possibly empty). 2. The matching `` from `topology.xml` (the unit the component lives inside) so the architectural conversation stays inside the right boundary. 3. The full `behavior.xml` use-case the component is expected to handle, when one exists, so the candidate shape is judged against the actual handling story. 4. `templates/composition/component.xml` and `templates/composition/constraint.xml` (via `usdl:templates`) — the structural shape the eventual fragment must conform to. 5. The Skatchbook store root (`top.skatchbook-store`) — a filesystem directory provided by the parent Skill or by the host. The Skill reads and writes only inside this directory. The Skill never asks for filenames, paths, or function signatures. Those would violate `beh.rule.no-code-in-spec` if they leaked into the eventual Spec fragment. ## The Skatchbook flow The Skill runs the loop below in order. Required steps are unconditional; optional steps surface only when the author indicates interest, per the minimum-interview discipline. ### 1. Open a scratch entry (unconditional) The Skill calls `scripts/scratch-runner/open_scratch.py` with the target component id and the Skatchbook store path. The script creates a new, timestamped scratch directory tagged with the component id and writes a `metadata.json` (component id, creation timestamp, status). Two invocations against the same component id produce two distinct entries — earlier sketches are never overwritten. The entry path is the only thing the script returns; everything else inside the entry is the author's working space. ### 2. Draft candidate abstractions (unconditional) The Skill helps the author write one or more **candidate abstractions** into the entry as plain code files (PHP class, Python class, pseudo-code; whichever language the author thinks in). Typical candidates the Skill suggests, given an intent that mentions "policy" or "branching": - **Strategy + registry** — one class per variant, a registry that returns the matching one. - **Port + adapter** — one interface owned by the inner ring, one or more adapters in an outer ring. - **Pipeline / chain of responsibility** — a sequence of small stages each transforming the carrier. - **State machine** — explicit states, explicit transitions, one transition function. - **Factory** — construction concentrated behind one entry point. The Skill walks each candidate through one or two **small examples** that the author already has in mind — what does the call site look like? what happens on the unhappy path? — until the author can compare candidates side by side. ### 3. Pick one (unconditional) The author picks the candidate that best captures the intent. The Skill marks the chosen file in `metadata.json` (the script writes the field; the Skill does not edit Spec files). ### 4. Translate to a Spec fragment (unconditional) The Skill calls `scripts/scratch-runner/translate_to_spec.py` with the entry path and a path under the Skatchbook store where the script should write a USDL fragment. The script reads the chosen abstraction and emits a fragment containing: - A **``** block of architectural prose: the main classes and their roles, named by **role** (e.g. "registry", "concrete policy class", "state-machine driver"), **never by filename and never with parameter lists**. The dictionary's `` row is explicit: "No filenames. No function signatures." The script strips both before emitting. - A **``** Element with `` clauses naming what must exist (e.g. "One concrete policy class per Supplier-policy variant.") and `` clauses naming the bypass constructs that would prove the pattern was abandoned (e.g. `conditional-on-policy-identifier`, `instance-of-policy-chain`). The `construct=` slugs are short, kebab-case, machine-readable. The fragment lives in the Skatchbook store. It is **not** written into `composition.xml` by this Skill — that is the parent's job. ### 5. Hand the fragment to the parent Skill (unconditional) The Skill returns the path of the emitted fragment to the parent Skill (`usdl:composition` or the composition-authoring Agent). The parent Skill then: - Validates the fragment against `templates/composition/component.xml` and `templates/composition/constraint.xml` via `usdl:templates`. - Calls `usdl validate` and `usdl content` (or the equivalent edit operation, depending on the parent's strategy) via `usdl:bin` to merge the fragment into `composition.xml`. - Shows the diff to the Spec author and waits for confirmation. If the parent Skill cannot apply the fragment cleanly (validation failure, id collision), the parent Skill — not this Skill — handles repair. This Skill never retries the write. ## The no-code-in-spec rule `beh.rule.no-code-in-spec` is binding on every fragment that leaves this Skill. The Spec captures architecture, not implementation; the Skatchbook captures implementation sketches, not architecture. The translation step is the boundary. The translator strips, before emitting: - **Filenames and file paths.** Any reference like `refund_policy.py`, `src/policies/standard.php`, `./adapter.ts` is removed from the prose. The architectural role (e.g. "concrete refund-policy class") is preserved. - **Function signatures, parameter lists, parameter types, return types.** Any line shaped like `def calculate(refund: Refund) -> Decimal:` or `public function calculate(Refund $r): Money` is removed. The behaviour the function captures is preserved as role description. - **Library and framework names** (per the dictionary's `` row: "Library prescriptions belong in ADRs, not here."). - **Class names that only make sense as filenames.** Role names (`Registry`, `Adapter`, `StateDriver`) are kept; literal class identifiers from the sketch (`AcmePolicyFactoryV2Impl`) are normalised to their role. ### Example — before and after A sketch entry contains a Python file with this content: ``` # refund_policy/standard.py class StandardRefundPolicy: def calculate(self, refund: Refund) -> Decimal: ... class RefundPolicyRegistry: def for_supplier(self, supplier_id: str) -> RefundPolicy: ... ``` The translator's emitted `` prose, after stripping, reads: - One concrete refund-policy class per Supplier-policy variant, each carrying the calculation for that variant. - A registry that, given a Supplier-policy identifier, returns the matching policy instance. The emitted `` carries: - `` "One concrete refund-policy class per Supplier-policy variant, each in its own file." - `` "A registry that, given a Supplier-policy identifier, returns the matching policy instance." - `` - `` No filenames. No function signatures. No `Decimal`, no `Refund`, no `def`. The architectural shape survives; the implementation does not. ## The no-direct-spec-writes rule `con.skatchbook-no-direct-spec-writes` is binding on every bundled script under `scripts/scratch-runner/`: - The scripts read and write only inside the Skatchbook store path the caller supplies. - The scripts **never open `composition.xml`** (or any other Section file) for writing. - The scripts **never delete a Spec Element.** - Mutations to `composition.xml` go through the **parent Skill**, which uses `usdl:bin` to call the `usdl` CLI. This separation is the single reason the Skatchbook can experiment freely without poisoning the Spec store. A reviewer who grep'd this Skill's scripts for `composition.xml` should find zero matches; that is the property the scripts guarantee. ## Bundled scripts The `scripts/scratch-runner/` directory carries two small scripts, each runnable with `--help`: - **`open_scratch.py`** — creates one fresh, timestamped scratch entry under the supplied Skatchbook store, tags it with the target component id and a `metadata.json`, and returns the entry path. Two calls with the same component id produce two distinct entries. - **`translate_to_spec.py`** — reads the chosen abstraction file inside one scratch entry and writes a USDL Composition fragment (a `` prose block plus a `` Element with ``/`` children) to the supplied output path inside the Skatchbook store. Strips filenames and function signatures before emitting. Both scripts use the Python standard library only and write only inside the Skatchbook store. ## What this Skill does not do - It does not invoke `usdl:bin`. The parent Skill does. - It does not write `composition.xml`. The parent Skill does, via `usdl:bin`. - It does not write to `behavior.xml`, `topology.xml`, or `interfaces.xml`. Only `usdl:behaviour`, `usdl:topology`, and `usdl:interfaces` (through their respective Agents and `usdl:bin`) write those. - It does not invent abstractions the author did not consider. It surfaces typed shapes the author can accept or reject. - It does not retain candidates the author rejected as part of the eventual Spec fragment. Rejected candidates remain in the Skatchbook entry for the author's future reference. - It does not paste any sketch code into the Spec. Filenames and function signatures are stripped at the translation boundary. ## Cross-references in the Spec - Use case: `beh.experiment-in-skatchbook`. - Rule: `beh.rule.no-code-in-spec`. - Constraint: `con.skatchbook-no-direct-spec-writes`. - Component (SKILL.md): `cmp.composition-skatchbook.skill-md`. - Component (bundled scripts): `cmp.composition-skatchbook.scratch-runner`. - Topology unit: `top.skill.composition-skatchbook`. - Storage unit (read/write): `top.skatchbook-store`. - Storage unit (never written here): `top.spec-store`. - Glossary term: `term.skatchbook`.

usdl-composition-skatchbook

Install this skill

Comments