rote-cli 0.1.0__py3-none-any.whl

rote/skills/rote-graduate/references/crystallization-heuristics.md

@@ -0,0 +1,260 @@
+# Crystallization Heuristics
+
+Phase 3 of the graduator is where the highest leverage lives: finding
+every place the source skill's prose is hiding a deterministic procedure
+that *should be code*. This file is the pattern library.
+
+The guiding rule is simple: **if the skill's author already wrote down
+the exact procedure, don't make the LLM re-derive it at runtime.** Every
+token spent re-deriving a known-fixed procedure is waste, and every
+MANDATORY check enforced only by prose is a bug waiting to happen.
+
+## Why crystallization is the biggest win
+
+Skills that graduate well typically see:
+- **50–70% token reduction per run** from moving formatting, batching,
+  and rule enforcement into code
+- **Reliability wins** from making MANDATORY checks impossible to skip
+- **Testability wins** from having the deterministic parts in regression
+  suites instead of trusting the agent to follow instructions
+
+Crystallization is mostly a pattern-matching exercise. This file lists
+the patterns you should actively hunt for.
+
+## The patterns
+
+### Pattern 1 — Literal Python or pseudocode in the prompt
+
+**What it looks like:** the skill's markdown includes fenced code blocks
+(```python` or ``` `text` ) that describe exactly how to do something.
+The LLM is being asked to *read* this code and *re-execute it in its
+head*.
+
+**BDR example:**
+`references/conference-enrichment.md` includes a full Python function
+definition for `is_pharma(company_name)` — a keyword classifier with
+hardcoded include/exclude lists. The LLM reads this file, mentally
+"runs" the function on each contact, and returns a list. Absurd.
+
+**What to do:**
+- Extract the code verbatim into an `extracted/*.py` module.
+- Create a `pure_function` node that calls it.
+- Note the extraction in the graduation report so the human reviewer
+  can verify the extraction matches the original.
+
+**How to detect:** grep for ` ```python`, ` ```py`, and `def `. Also
+look for `for contact in`-style pseudocode in plain prose — it's the
+same pattern without the code fence.
+
+---
+
+### Pattern 2 — Fixed constants embedded in prose
+
+**What it looks like:** the skill says "batch of 10", "wait 30 days",
+"accuracy below 85", "up to 250 per call". These numbers never change
+run-over-run; they're API limits or policy thresholds.
+
+**BDR examples:**
+- `enrich_contact_batch`: `batch_size: 10` (ZoomInfo API limit)
+- `hubspot_upsert`: `batch_size: 100` (HubSpot API limit)
+- `hubspot_create_list` → `add_contacts_to_list`: `batch_size: 250`
+- `exclusion_check_recent`: `days_back: 30`
+- `vet_contact`: `min_accuracy_score: 85`
+
+**What to do:**
+- Lift the constant into the node's `constants:` field in the IR.
+- In the extracted Python module, define it as a module-level constant
+  (so it shows up once and is trivially overridable if policy changes).
+- Enforce it in code — the extracted function should *reject* inputs
+  that violate the constraint, not just document it.
+
+**Why this matters:** constants that live only in prose drift when
+prompts get edited. Once a limit lives in code, it stops drifting. The
+BDR skill's exclusion checks say "30 days" in the prose — in the
+graduated pipeline, `RECENT_EMAIL_DAYS = 30` cannot be silently
+changed to 7 without a commit that shows up in review.
+
+**How to detect:** grep for numeric literals in the prose. Most of them
+are constants begging to be lifted. Questions to ask: "does this number
+ever change across runs?" — if no, it's a constant.
+
+---
+
+### Pattern 3 — MANDATORY checks enforced only by prose
+
+**What it looks like:** the skill uses the word "MANDATORY", "required",
+"always", "must", or "do not skip" to describe a check that happens
+before some irreversible action.
+
+**BDR example:** Phase 5 exclusion checks. The skill's
+`hubspot-operations.md` literally says "MANDATORY" in ALL CAPS for the
+three exclusion checks (do-not-contact, recently emailed, active
+sequence). In the agent loop, nothing actually prevents the LLM from
+skipping these if prompt drift is bad.
+
+**What to do:**
+- Classify the check as a `pure_function` or `external_call` node.
+- Set `mandatory: true` on the node in the IR. The IR schema enforces
+  that mandatory nodes cannot be made conditional.
+- The adapter will emit the mandatory node as an unconditional activity
+  the workflow always calls in order. The prose enforcement disappears
+  because the code-level enforcement replaces it.
+
+**Why this matters:** this is the single highest-leverage pattern in
+graduation. A MANDATORY prose check is a *reliability bug waiting to
+happen* — every prompt edit, every model upgrade, every long agent
+trajectory is a chance for the check to get forgotten. Moving it to
+code makes skipping impossible.
+
+**How to detect:** grep (case-insensitive) for "mandatory", "required",
+"always", "must", "never skip", "do not skip", "be sure to". Audit
+every hit.
+
+---
+
+### Pattern 4 — Fixed string templates for reports and outputs
+
+**What it looks like:** the skill shows an exact expected output
+format — usually in a fenced code block or a bulleted template —
+and the agent's job is to fill in the blanks.
+
+**BDR example:** `hubspot-operations.md` shows the exact
+pre-enrollment report format, counts-by-reason and all. The LLM was
+generating this markdown by hand every run. Wasteful.
+
+**What to do:**
+- Create a `pure_function` node that takes typed inputs (the counts,
+  the contact lists) and produces the markdown string.
+- The function is pure string formatting — no LLM.
+
+**How to detect:** look for ````text` or ````markdown` blocks with
+placeholder syntax (`[name]`, `{field}`, `...`). Also look for any
+output spec with a fixed structure.
+
+---
+
+### Pattern 5 — Batching and rate-limiting loops with fixed semantics
+
+**What it looks like:** the skill says "process in batches of N",
+"chunk by Y per call", "wait between requests". The loop structure and
+batch size are fixed.
+
+**BDR examples:**
+- Enrich contacts in batches of 10
+- Upsert contacts in batches of 100
+- Add to list in batches of 250
+
+**What to do:**
+- Extract the batch size as a constant (see Pattern 2).
+- The batching loop lives inside the extracted function, not the
+  workflow — the workflow calls the function once with a list of any
+  size, and the function handles chunking internally.
+- The adapter can set appropriate activity timeouts based on the
+  expected batch count.
+
+**How to detect:** grep for "batch of", "chunk", "max ... per".
+
+---
+
+### Pattern 6 — Taxonomy / enum lookups that never change
+
+**What it looks like:** the skill does setup lookups (ID resolution,
+category mapping, static reference data) at the start of every run.
+The underlying data is stable — these IDs don't change month-over-month.
+
+**BDR example:** `taxonomy_lookup` — the ZoomInfo management level IDs
+(VP, Director), industry IDs (pharma, biotech), department ID (Medical
+& Health). These IDs have been stable for years.
+
+**What to do:**
+- Extract as a `pure_function` node with a `cache:` config for
+  aggressive caching (e.g., `persistent`, `30d`).
+- On first run, the function hits the API; subsequent runs read from
+  cache until TTL expires.
+
+**How to detect:** look for "look up", "resolve", "get the ID for",
+"find the category", especially as setup steps at the start of a
+phase.
+
+---
+
+### Pattern 7 — Numeric or enum thresholds disguised as LLM rules
+
+**What it looks like:** the skill's rubric includes a rule like
+"discard contacts with accuracy below 85" or "contacts older than 90
+days are stale". These look like they belong in the `llm_judge` rubric,
+but they're actually hard thresholds.
+
+**BDR example:** `vet_contact` — the rubric says "flag contacts below
+85 accuracy". This is a numeric comparison, not a judgment call.
+
+**What to do:**
+- Keep the step as `llm_judge` (the rest of the rubric is fuzzy).
+- But add a **pre-filter** in the signature that short-circuits on the
+  hard threshold before calling the LLM. The BDR
+  `signatures/vet_contact.py` does this — low-accuracy contacts never
+  reach the model.
+- This saves tokens on the obvious cases and guarantees consistency on
+  the hard rules.
+
+**How to detect:** look for numeric comparisons in rubrics ("below X",
+"above Y", "at least Z"). Every one is a potential pre-filter.
+
+## When NOT to crystallize
+
+The hunt for crystallization should be aggressive, but not blind. Leave
+things agentic when:
+
+1. **The procedure genuinely varies run-over-run.** Target company
+   research (BDR Phase 1.5) calls different tools for different
+   indications, draws on different sources, produces different briefs.
+   That's `agent_loop`, not `pure_function`.
+
+2. **The inputs are unbounded prose.** Summarizing someone's employment
+   history to check franchise alignment isn't code-able — the input
+   shape is unbounded and the judgment is fuzzy. That's `llm_judge`.
+
+3. **The skill explicitly says "this is a judgment call".** Trust the
+   source. If the skill author marked something as needing human or
+   LLM judgment, there's usually a reason.
+
+4. **Crystallizing would require reimplementing an existing fuzzy
+   service.** Don't try to replace a vendor's search ranking with
+   your own code. Use the service; codify the *calling convention*,
+   not the service's internal logic.
+
+## The estimation heuristic
+
+When producing the Phase 7 graduation report, estimate the
+"% codifiable" as:
+
+```
+codifiable_nodes = count(pure_function) + count(external_call)
+total_nodes = len(all nodes except hitl_gate)
+pct = codifiable_nodes / total_nodes * 100
+```
+
+A well-graduated BDR-scale skill lands around **60–70% codifiable**.
+If you're below 40%, you're probably leaving crystallization on the
+table. If you're above 80%, either you have a very structured skill
+or you're over-crystallizing — double-check that the remaining
+`llm_judge` / `agent_loop` nodes genuinely need the LLM.
+
+## Scanning order
+
+When doing Phase 3, walk through the source skill in this order:
+
+1. **Every `references/*.md` file first.** The reference files usually
+   contain the highest density of crystallizable patterns (literal code,
+   constants, rubrics with thresholds).
+2. **Then the main `SKILL.md`.** It's orchestration-level and usually
+   has fewer literal patterns, but contains the MANDATORY flags and
+   phase ordering.
+3. **For each file, grep for the detection terms listed in each pattern
+   above.** Note every hit. You'll usually find more patterns than
+   nodes — several patterns often apply to the same node.
+
+Record every extraction candidate in the graduation report with
+`file:line`, the current prose, and the proposed codified form. This
+is the primary audit trail for the graduation and the thing the human
+reviewer will check first.

rote/skills/rote-graduate/references/ir-schema.md

@@ -0,0 +1,420 @@
+# Pipeline IR Schema (`pipeline.yaml`)
+
+Phase 5 of the graduator produces a `pipeline.yaml` file that describes
+the entire graduated pipeline in a runtime-agnostic form. This file is
+the reference for that YAML schema. It matches the Pydantic models in
+`rote/ir.py`; when in doubt, that module is the authoritative source.
+
+## Top-level structure
+
+```yaml
+name: bdr-campaign              # required, kebab-case, unique
+version: "0.1.0"                # required, semver string
+source_skill: ../../skill       # optional, path to source skill bundle
+description: |                  # optional, multi-line prose
+  End-to-end BDR outreach campaign workflow...
+
+config:                         # optional, defaults apply if omitted
+  schedule: null                # cron expression or null
+  on_failure: notify_owner      # free-form adapter hook
+  observability:
+    traces: true
+    eval_set_dir: ./evals/
+  hitl:
+    default_timeout: 7d
+
+input:                          # required, pipeline input contract
+  type: CampaignBrief
+  required:
+    - drug_brand
+    - drug_generic
+  optional:
+    - job_focus
+  input_schema:                 # strongly preferred: full JSON Schema
+    type: object                # for the input payload (see below)
+    title: CampaignBrief
+    properties: { ... }
+    required: [drug_brand, drug_generic, ...]
+
+nodes: [ ... ]                  # required, list of Node objects
+edges: [ ... ]                  # required, list of Edge objects
+entry_nodes: [target_research, taxonomy_lookup]
+exit_nodes: [manual_enrollment_handoff]
+```
+
+### `input.input_schema` — promote the entry payload schema
+
+When you design the entry nodes' `signature_spec.input_schema`, you
+already produce a full JSON Schema for the pipeline's input type (the
+BDR example has `CampaignBrief` with its `$defs` for `CampaignType`
+and `JobFocus`). **Promote that same schema to `input.input_schema`**
+so adapters can validate the pipeline input before the workflow
+starts:
+
+- Take the input type's object schema (with any enums/nested types it
+  needs inlined under its own `$defs`) — the same dictionaries
+  Pydantic emits via `model_json_schema()`.
+- The schema's `required` list must match `input.required`, and its
+  `properties` must cover every name in `input.required` +
+  `input.optional`.
+- `input_schema` is optional in the validator (old pipelines stay
+  valid), but always emit it for new graduations — it is the typed
+  contract everything downstream keys off.
+
+## Node object
+
+Every node has a `kind` field, and the required fields depend on the
+kind. The validator enforces kind-specific requirements.
+
+### Common fields (all kinds)
+
+```yaml
+- id: taxonomy_lookup            # required, unique, snake_case
+  kind: pure_function            # required, one of 5 kinds
+  phase: "2"                     # optional, source skill phase (string)
+  description: |                 # required, short prose
+    Resolve ZoomInfo IDs for management levels...
+  input:                         # optional, field→type mapping
+    brief: CampaignBrief
+  inputs:                        # data-flow bindings: param → source ref
+    brief: pipeline.input        # (see "Data-flow bindings" below)
+  output: TaxonomyIds            # optional, type name or field mapping
+  timeout: 5m                    # optional, duration string
+  retry:                         # optional
+    max: 3
+    backoff: exponential         # linear | exponential | constant
+    retry_on: [rate_limit, network]   # optional, note: NOT 'on' — YAML parses 'on' as boolean
+  mandatory: false               # optional, default false
+  constants:                     # optional, arbitrary key/value dict
+    batch_size: 10
+  cache:                         # optional
+    strategy: persistent
+    ttl: 30d
+  fan_out: false                 # optional, if true node invoked per input element
+```
+
+### Data-flow bindings (`inputs:`)
+
+`input:` documents *types*; `inputs:` binds *where the values come
+from at runtime*. Adapters render `inputs:` into real payloads — a
+node without `inputs:` receives an empty payload, so **emit `inputs:`
+for every top-level node whose upstream sources you can name.**
+
+The grammar is exactly four forms. There is no expression language —
+no arithmetic, no aggregation, no deep paths:
+
+| Reference form               | Meaning                                     |
+|------------------------------|---------------------------------------------|
+| `pipeline.input`             | the whole pipeline input payload            |
+| `pipeline.input.<field>`     | one top-level field of the pipeline input   |
+| `<node_id>.output`           | the whole output of an upstream node        |
+| `<node_id>.output.<field>`   | one top-level field of an upstream node's output |
+
+BDR examples:
+
+```yaml
+- id: lead_generation_loop
+  inputs:
+    brief: pipeline.input                    # whole input payload
+    intel: target_research.output           # whole upstream output
+    taxonomy: taxonomy_lookup.output
+    target_quota: pipeline.input.target_quota  # one input field
+
+- id: hubspot_upsert
+  inputs:
+    # HITL gate outputs work too — this is the reviewer's signal payload:
+    contacts: contact_review_gate.output.approved_contacts
+
+- id: exclusion_check_recent
+  inputs:
+    contacts: exclusion_check_dnc.output.passed   # chain node → node
+```
+
+Rules and edge cases:
+
+1. **Reference only upstream nodes.** A reference to a node that runs
+   in a later wave — or to a loop-body sub-node, which has no
+   top-level result — fails at emission time.
+2. **Pipeline input fields must be declared.** `pipeline.input.<field>`
+   is validated against `input.required` + `input.optional` +
+   `input_schema.properties`.
+3. **Leave a parameter unbound when the grammar can't express it** and
+   say why in a comment. BDR has two deliberate examples:
+   `dnc_list_id` (deployment configuration, not pipeline data) and
+   `vetted_count` (an aggregate — `len()` of a list — which belongs in
+   the extracted function, not the reference syntax).
+4. **Loop-body sub-nodes:** their `inputs:` describe what the parent
+   loop passes per iteration. Adapters don't resolve them at the top
+   level, so treat them as documentation for the loop harness.
+5. **`fan_out` nodes:** bind the element parameter to the upstream
+   *list* (e.g. `contact: exclusion_check_sequence.output.passed`).
+   The runtime is responsible for per-element dispatch; v0 adapters
+   pass the whole list in a single invocation.
+6. **HITL gates need no `inputs:`** — a gate's "output" is the signal
+   payload the human sends, and downstream nodes reference it as
+   `<gate_id>.output[...]`.
+
+### `pure_function` and `external_call`
+
+**Required:** `impl` — path to the extracted Python function in
+`"extracted/foo.py:bar_func"` format.
+
+```yaml
+- id: pre_enrollment_report
+  kind: pure_function
+  description: Render the pre-enrollment report as Markdown.
+  impl: extracted/report.py:generate_pre_enrollment_report
+  input:
+    campaign_name: str
+    vetted_count: int
+    passed_contacts: list[HubSpotContact]
+    exclusions: list[ExclusionRecord]
+    template_ids: list[str]
+  output: report_markdown str
+
+- id: hubspot_upsert
+  kind: external_call
+  description: Batch upsert contacts to HubSpot (100 per call).
+  impl: extracted/hubspot.py:batch_upsert_contacts
+  input:
+    contacts: list[VettedContact]
+  output:
+    upserted: list[HubSpotContact]
+  constants:
+    batch_size: 100
+  retry:
+    max: 5
+    backoff: exponential
+  timeout: 60s
+```
+
+### `llm_judge`
+
+**Required:** at least one of `signature` (legacy) or `signature_spec`
+(structured). **Strongly preferred: emit both.** The Temporal adapter
+prefers `signature_spec` when present and falls back to the legacy
+path; the Cloudflare adapter and any future non-Python target *require*
+`signature_spec` because there's no shared Python module to import.
+
+- **`signature`** — path to a typed Python signature class in
+  `"signatures/foo.py:FooClass"` format. Used by the Temporal adapter
+  and by humans iterating on the signature with DSPy / BAML. Always
+  emit this for runtimes that share Python with the extracted modules.
+
+- **`signature_spec`** — runtime-agnostic structured form: JSON Schema
+  for input + output (the same schemas Pydantic emits via
+  `model_json_schema()`), the prompt template, and the LLM client
+  config. This is the cross-language source of truth — adapters
+  derive Pydantic / Zod / Go types from the schemas as needed. See
+  [`llm-judge-extraction.md`](llm-judge-extraction.md) for the full
+  derivation procedure.
+
+```yaml
+- id: vet_contact
+  kind: llm_judge
+  description: Apply the BDR red-flags rubric to a single contact.
+  signature: signatures/vet_contact.py:VetContact     # legacy path (Temporal)
+  signature_spec:                                      # structured form (all runtimes)
+    input_schema:
+      type: object
+      required: [contact, brief, intel]
+      properties:
+        contact: {$ref: "#/$defs/EnrichedContact"}
+        brief: {$ref: "#/$defs/CampaignBrief"}
+        intel: {$ref: "#/$defs/IntelBrief"}
+      $defs:
+        # ... full Pydantic model_json_schema() output
+    output_schema:
+      type: object
+      required: [decision, relevance_evidence]
+      properties:
+        decision: {enum: [keep, discard]}
+        tier:
+          anyOf: [{enum: [ideal, strong, good]}, {type: "null"}]
+        discard_reason:
+          anyOf: [{enum: [indication_mismatch, msl_role, ...]}, {type: "null"}]
+        relevance_evidence: {type: string}
+    prompt: |
+      Apply the BDR vetting rubric to this contact.
+      Contact: {{ contact }}
+      Brief: {{ brief }}
+      Intel: {{ intel }}
+      Return your decision via the structured output tool.
+    client: anthropic           # 'anthropic' | 'openai'
+    model: claude-sonnet-4-6    # optional; adapter chooses default if omitted
+    temperature: 0.0            # optional
+  input:
+    contact: EnrichedContact
+    brief: CampaignBrief
+    intel: IntelBrief
+  output:
+    decision: VetDecision
+    tier: ContactTier
+    discard_reason: DiscardReason
+    relevance_evidence: str
+  constants:
+    min_accuracy_score: 85
+  eval_set: evals/vet_contact.jsonl
+  fan_out: true                  # one invocation per contact
+```
+
+### `agent_loop`
+
+**Required:** `tools` — list of tool names the agent may call inside
+the loop.
+**Optional:** `loop_body` — list of sub-node IDs invoked each iteration.
+**Optional:** `termination` — condition + max iterations.
+
+```yaml
+- id: lead_generation_loop
+  kind: agent_loop
+  description: Iterative search-enrich-vet loop.
+  input:
+    brief: CampaignBrief
+    intel: IntelBrief
+    target_quota: int
+  output:
+    vetted_contacts: list[VettedContact]
+  tools:
+    - zoominfo_search_contacts
+    - zoominfo_search_companies
+  loop_body:
+    - enrich_contact_batch
+    - vet_contact
+  termination:
+    condition: vetted_count >= target_quota
+    max_iterations: 10
+  timeout: 15m
+```
+
+**Note on `loop_body`:** sub-nodes listed here must also exist as
+top-level nodes in the `nodes:` list. They're referenced from the
+loop_body but also emitted as standalone activities (so they can be
+tested in isolation and reused elsewhere). The adapter excludes them
+from top-level execution waves to prevent double-dispatch.
+
+### `hitl_gate`
+
+**Required:** `signal` — name of the signal the workflow waits for.
+**Optional:** `notify` — how to alert the human reviewer.
+
+```yaml
+- id: contact_review_gate
+  kind: hitl_gate
+  description: Present the vetted contact table to the user for approval.
+  input:
+    vetted_contacts: list[VettedContact]
+  output:
+    approved_contacts: list[VettedContact]
+  signal: contact_review_approved
+  timeout: 7d
+  notify:
+    channel: slack
+    target: "#bdr-reviews"
+    message_template: |
+      BDR campaign awaiting review: {drug_brand} for {condition_acronym}
+```
+
+**Constraint:** `mandatory: true` is not allowed on `agent_loop` nodes
+(meaningless) but is allowed on every other kind. For HITL gates,
+`mandatory` is implicit — you can't skip a gate the workflow is
+waiting on.
+
+## Edge object
+
+```yaml
+edges:
+  - { from: target_research,         to: lead_generation_loop }
+  - { from: lead_generation_loop,    to: contact_review_gate }
+  - { from: contact_review_gate,     to: hubspot_upsert, on_signal: approved }
+  - { from: exclusion_check_sequence, to: personalize_email, fan_out: true }
+```
+
+- **`from` / `to`:** node IDs (must exist in the `nodes:` list).
+- **`on_signal`:** optional. If set, the edge only activates when the
+  named signal fires. Used for edges exiting a `hitl_gate`.
+- **`fan_out`:** optional. If true, the destination is invoked once per
+  element of the source's output.
+
+**Note:** `from` is a reserved word in Python, so the IR's Pydantic
+model uses the alias `from_`. In YAML, always write `from:`.
+
+## Validation rules the graduator must respect
+
+The IR validator will reject any of these, so produce the YAML with
+these constraints in mind:
+
+1. **Node IDs are unique** within a pipeline.
+2. **All `from`/`to` in `edges` reference real node IDs.**
+3. **All `loop_body` entries reference real node IDs.**
+4. **All `entry_nodes` and `exit_nodes` reference real node IDs.**
+5. **Kind-specific required fields are present:**
+   - `pure_function` / `external_call` → `impl`
+   - `llm_judge` → `signature` (legacy path) or `signature_spec`
+     (structured) — at least one. Strongly preferred: emit both.
+   - `agent_loop` → `tools`
+   - `hitl_gate` → `signal`. Cloudflare additionally requires the
+     signal name to match `[A-Za-z0-9_-]+` (no dots, spaces, etc.) —
+     this is enforced at adapter emission time.
+6. **`mandatory: true` is not allowed on `agent_loop` nodes.**
+7. **No YAML key named `on:`** — YAML 1.1 parses it as boolean
+   `True`. The IR uses `retry_on:` instead.
+8. **All `inputs:` references parse and resolve.** Each value must
+   match one of the four reference forms (see "Data-flow bindings"),
+   node references must name real nodes (and never the node itself),
+   and `pipeline.input.<field>` must name a declared input field.
+
+## Duration strings
+
+Used in `timeout:`, `default_timeout:`, `cache.ttl:`, etc.
+
+| Suffix | Meaning |
+|---|---|
+| `ms` | milliseconds |
+| `s` | seconds |
+| `m` | minutes |
+| `h` | hours |
+| `d` | days |
+
+No suffix → seconds. Examples: `5m`, `30s`, `7d`, `250ms`.
+
+## Minimal skeleton for a new pipeline
+
+When generating a `pipeline.yaml` from scratch, start with this skeleton
+and fill it in:
+
+```yaml
+name: <skill-name>
+version: "0.1.0"
+source_skill: <relative path to skill>
+description: |
+  <one-paragraph summary of what the skill does>
+
+config:
+  on_failure: notify_owner
+
+input:
+  type: <BriefTypeName>
+  required: []
+  optional: []
+
+nodes: []
+edges: []
+entry_nodes: []
+exit_nodes: []
+```
+
+Then add nodes from the source skill's entry point outward, adding
+edges as you go. Use `entry_nodes` for nodes with no inbound edges
+(except from the pipeline input itself) and `exit_nodes` for terminal
+nodes whose completion means the workflow is done.
+
+## Cross-referencing the rubric
+
+- Every node's `kind` decision is guided by `node-kinds.md`.
+- Every `pure_function` / `external_call` node's `impl` and `constants`
+  come from applying the patterns in `crystallization-heuristics.md`.
+- Every `llm_judge` node's `signature` design is guided by
+  `llm-judge-extraction.md`.
+- Every `mandatory: true` flag comes from a Pattern 3 hit in the
+  crystallization scan.