| name | operationalize |
| description | Distill context (research, recon, learnings) into evidence-anchored rules routed to automation shapes. Use when a finished artifact should become skills, gates, or beads. |
| practices | ["wiki-knowledge-surface","design-by-contract","pragmatic-programmer"] |
| hexagonal_role | domain |
| consumes | [".agents/research/*.md"] |
| produces | [".agents/operationalize/*.md","routed-handoffs"] |
| context_rel | [{"kind":"customer-of","with":"research"},{"kind":"customer-of","with":"automation-shape-routing"},{"kind":"customer-of","with":"validate"},{"kind":"supplier-to","with":"skill-builder"},{"kind":"supplier-to","with":"workflow-builder"},{"kind":"supplier-to","with":"cc-hooks"},{"kind":"supplier-to","with":"beads-workflow"}] |
| skill_api_version | 1 |
| user-invocable | false |
| context | {"window":"fork","intent":{"mode":"task"},"sections":{"exclude":["HISTORY"]},"intel_scope":"topic"} |
| metadata | {"tier":"experimental","stability":"experimental","dependencies":["automation-shape-routing","skill-builder","workflow-builder","cc-hooks","beads-workflow","validate"]} |
| output_contract | .agents/operationalize/YYYY-MM-DD-<slug>.md rule packet + one handoff stub per routed rule |
/operationalize — Distill + Route Bridge
Loop position: move 7 (capture + ratchet) of the operating loop — routes promoted learnings to their weakest durable enforcement (skill, gate, or bead).
Rich context dies in the artifact that gathered it. A deep-research report, a
codebase-recon sweep, or a painful learning is read once, agreed with, and
never changes behavior again. This skill is the bridge: distill the artifact
into a handful of evidence-anchored rules, then route each rule to the
automation shape that will actually fire next time — skill, workflow, hook,
gate, beads, or playbook.
Use when: "I gathered rich context — operationalize it." The input is a
finished artifact; the output is rules with anchors and a handoff per rule.
⚠️ Critical Constraints
- Sources stay in place — to prevent a corpus-curation detour. Name the
source artifacts by path; never copy them into a corpus directory. The
artifact you were handed IS the evidence base.
- Every rule cites a source anchor, because an unanchored rule is an
opinion wearing a rule's clothes — it cannot be audited, challenged, or
retired when the source is superseded.
- Disagreement is marked DISPUTED, never averaged, because splitting the
difference between conflicting sources produces a rule nobody measured.
A DISPUTED entry routes to investigation (beads), not to automation.
- Shape is decided by routing, not by vibe — to prevent everything
becoming a skill. Compose /automation-shape-routing
for the shape decision; this skill only extends its target list.
- Gates start warn-only, because a fresh rule promoted straight to a
blocking gate ships its false positives as outages. Promotion to blocking
comes after the gate has run quietly on real traffic.
- No rule survives without a counter-example check, because the cheapest
time to find the case where the rule is wrong is before it is wired into
anything (see Step 5).
Execution
Step 1: Intake
Name the source artifacts in place — absolute or repo-relative paths plus a
one-line provenance note each (who produced it, when, method). Confirm each
source has citable anchors (section IDs, finding IDs, line ranges); if not, add
anchor IDs to your notes about the source, never by editing the source.
Checkpoint: every source is a named path with a provenance line. No corpus
dirs were created.
Step 2: Distill
Extract candidate rules in the canonical form — "When X, do Y because Z" —
where Z cites at least one anchor. Work source by source, then reconcile:
- Multiple sources agree → one rule citing all supporting anchors.
- Sources conflict → one DISPUTED entry naming both sides' anchors and
what evidence would settle it. Do not synthesize a compromise rule.
- A finding with no behavioral consequence → drop it (context, not a rule).
Checkpoint: every rule line carries ≥1 anchor; every conflict became a
DISPUTED entry, not a blended rule.
Step 3: Route
Hand each rule to /automation-shape-routing
and extend its decision with this target table:
| Route | Pick when the rule… | Emit target |
|---|
| skill | needs judgment at execution time | /skill-builder |
| workflow | is a deterministic multi-step sequence | /workflow-builder |
| hook | must fire mechanically on a runtime event | /cc-hooks |
| gate | should check outputs — start warn-only | a validation gate spec (warn-only first) |
| beads | is unsettled work or a DISPUTED investigation | /beads-workflow |
| playbook | guides a human/operator decision, not an agent | .agents/playbooks/ entry |
Checkpoint: every rule has exactly one route; every DISPUTED entry routed
to beads.
Step 4: Emit
Write the rule packet (Output Specification below), then create one handoff
stub per routed rule: the rule text, its anchors, the chosen route, and the
target skill invocation. The downstream builder owns the artifact; this skill
owns the rule and its evidence trail.
Step 5: Validate
For each rule, run the counter-example check: actively search the sources (and
your own experience) for one case where following the rule would be wrong. A
found counter-example narrows the rule's "When X" or demotes it to DISPUTED.
Then request a /validate verdict on the packet before
handing off — verify before any downstream builder consumes it.
Worked example (golden fixture)
Input: fixtures/research-excerpt.md — a fake
deep-research excerpt on worker-lane retry behavior, anchors RX-1…RX-5.
Distilled packet:
- When a lane receives a rate-limit response, wait the full advertised
cooldown before any same-account retry, because burst retries extend the
penalty window (RX-1) and sub-30-second retries re-failed in 84% of logged
events (RX-2). → route: hook (mechanical, event-triggered).
- When one same-account retry has already failed, rotate accounts before
the next attempt — capped at three accounts per hour, because
post-failure rotation succeeded on the next call in 91% of cases (RX-2)
while sustained cycling beyond three accounts/hour risks account review
(RX-5). → route: skill (judgment about when the cap binds).
- DISPUTED — rotate unconditionally on the first rate-limit response.
RX-4 (operator interview) asserts it; RX-5 flags rotation frequency itself
as a risk, and RX-2 only measured rotation after a failed retry. Settling
evidence: telemetry comparing first-response rotation vs post-failure
rotation. → route: beads (investigation), not automation.
Note what did NOT happen: rules 1–3 were not averaged into "rotate fairly
quickly"; RX-3 (re-dispatch to a warm lane) was held back at Step 5 because
its own source records a 9% duplicate-work counter-example.
Output Specification
Format: markdown rule packet — sources-in-place list, numbered rules in
"When X, do Y because Z" form with anchors, DISPUTED section, route table, and
the validate verdict reference.
Path: written to .agents/operationalize/YYYY-MM-DD-<slug>.md; handoff
stubs accompany it as a ## Handoffs section (one block per routed rule).
Exit signal: packet path + per-rule route summary reported to the caller.
Quality Rubric
See Also
