Distill Traces

---
name: distill-traces
description: Use when asked to extract reusable loop patterns or YAML fragments from successful execution history.
disable-model-invocation: true
argument-hint: "<loop-name> [--min-success N]"
model: sonnet
allowed-tools:
  - Bash
  - Read
  - Glob
  - Write
arguments:
  - name: loop_name
    description: Name of the loop to distill patterns from (required)
    required: true
  - name: min_success
    description: Minimum number of successful runs required before writing fragments (default 3)
    required: false
metadata:
  short-description: Extract reusable loop YAML fragments from successful execution history.
---

# Distill Traces

Mine successful execution history for a loop and write reusable YAML state templates and transition fragments to `.loops/lib/<loop-name>/` in the project.

---

## Step 1: Discover History Runs

List all directories under `.loops/.history/` and filter for runs belonging to `<loop_name>`:

```bash
ls -d .loops/.history/*-<loop_name>/ 2>/dev/null | sort
```

Each directory name follows the flat layout `<YYYY-MM-DDTHHMMSS>-<loop-name>`. Parse each folder name with the pattern `^(\d{4}-\d{2}-\d{2}T\d{6})-(.+)$` and keep only those where the loop-name part (group 2) matches `<loop_name>` exactly.

If no directories are found, report: "No history found for loop `<loop_name>`." and stop.

---

## Step 2: Filter Qualifying Runs

For each candidate directory, read `state.json`:

```bash
cat .loops/.history/<run-folder>/state.json
```

Keep only runs where `status == "completed"`. These are runs that terminated successfully (the `status` field in `state.json` is set to `"completed"` only when the loop terminated via a terminal state).

Collect all qualifying run folder paths. Apply the `--min-success` threshold (default 3):

- If qualifying run count < threshold: print `Not enough successful runs for <loop_name>: found <N>, need <threshold> (--min-success). No fragments written.` and exit without writing artifacts (exit 0).
- Otherwise: proceed to Step 3.

---

## Step 3: Extract State Sequences and Action Patterns

For each qualifying run, read `events.jsonl`:

```bash
cat .loops/.history/<run-folder>/events.jsonl
```

Each line is a JSON object with an `"event"` field. Collect:

1. **State visits** — lines where `"event": "state_enter"`. Extract the `"state"` field from each. Build the ordered state sequence for this run.
2. **Transitions** — lines where `"event": "route"`. Extract `"from"` and `"to"` fields. These represent observed state-to-state transitions.

For each `state_enter` event, if the immediately preceding `action_complete` event (in the same run) contains an `"action"` field, record it as the action string for that state visit.

Across all qualifying runs, aggregate:
- **Per-state visit count**: how many times each state was entered across all runs
- **Per-state action strings**: most common `action` value seen for each state
- **Per-transition frequency**: count of `(from, to)` pairs across all runs

---

## Step 4: Build Fragment Data

For each state that appears in at least one qualifying run, construct a fragment entry:

- `description`: `"Extracted from <N> successful runs of <loop-name>.\nCaller must supply: on_yes, on_no (and optionally on_error, timeout)."`
- `action_type`: infer from the most common action text — `shell` if the action looks like a shell command, `prompt` if it's prose, `slash_command` if it starts with `/`. Default to `shell` when uncertain.
- `action`: the most common action string seen for this state across qualifying runs. If no action strings were recorded (state had no `action_complete` events), omit the `action` field.
- `evaluate.type`: infer from available context — use `exit_code` for shell states, `llm_structured` for prompt states, `output_contains` when action output contained a keyword pattern. Default to `exit_code` when uncertain.

For transitions, record each unique `(from, to)` pair with its frequency count.

---

## Step 5: Write state-templates.yaml

Create the output directory and write the state templates file:

```bash
mkdir -p .loops/lib/<loop-name>
```

Write `.loops/lib/<loop-name>/state-templates.yaml` using the `fragments:` map structure (the same shape as the built-in `lib/common.yaml` fragment library):

```yaml
# Generated by /ll:distill-traces <loop-name>
# Import with: import: - lib/<loop-name>/state-templates.yaml
#
# Usage in a loop state:
#   my_state:
#     fragment: <state_name>
#     on_yes: next_state
#     on_no: fallback_state

fragments:
  <state_name>:
    description: |
      Extracted from <N> successful runs of <loop-name>.
      Caller must supply: on_yes, on_no (and optionally on_error, timeout).
    action_type: shell|prompt|slash_command
    action: |
      <most common action string across qualifying runs>
    evaluate:
      type: exit_code|llm_structured|output_contains
```

Repeat the fragment entry for each state with at least one qualifying run visit. Omit the `action` key for states where no action text was recorded.

---

## Step 6: Write transitions.yaml

Write `.loops/lib/<loop-name>/transitions.yaml` with observed state transitions sorted by frequency descending:

```yaml
# Generated by /ll:distill-traces <loop-name>
# Most frequent state transitions across <N> successful runs of <loop-name>
# Reference these when wiring on_yes / on_no routing in a new loop.

transitions:
  - from: <state_a>
    to: <state_b>
    frequency: <N>
  - from: <state_c>
    to: <state_d>
    frequency: <M>
```

---

## Step 7: Write primitives.md

Write `.loops/lib/<loop-name>/primitives.md` as a human-readable index:

```markdown
# Distilled Primitives: <loop-name>

Generated from <N> successful runs (--min-success threshold: <threshold>).

## State Templates (`state-templates.yaml`)

| Fragment | Visits (total) | Action type | Evaluator |
|---|---|---|---|
| `<state_name>` | <visit_count> | <action_type> | <evaluate_type> |
...

## Common Transitions (`transitions.yaml`)

| From | To | Frequency |
|---|---|---|
| `<state_a>` | `<state_b>` | <N> |
...

## Import

To use these fragments in a new loop:

```yaml
import:
  - lib/<loop-name>/state-templates.yaml
```

Then reference a fragment:

```yaml
my_state:
  fragment: <state_name>
  on_yes: next_state
  on_no: fallback_state
```
```

---

## Final Report

After writing all files, output:

```
Distilled <loop-name> from <N> successful runs (<M> qualifying / <total> total).

Written:
  .loops/lib/<loop-name>/state-templates.yaml  (<S> fragments)
  .loops/lib/<loop-name>/transitions.yaml       (<T> transitions)
  .loops/lib/<loop-name>/primitives.md

Import with:
  import:
    - lib/<loop-name>/state-templates.yaml
```

---

## Usage Examples

```bash
# Distill from rn-remediate (requires at least 3 successful runs)
/ll:distill-traces rn-remediate

# Require at least 5 successful runs
/ll:distill-traces rn-remediate --min-success 5

# Loop with fewer runs than default threshold (exits cleanly with message)
/ll:distill-traces my-new-loop --min-success 2
```