Toil Mining

/toil-mining — Mine usage history for automation candidates

Purpose: the operator's own history is the highest-signal backlog nobody

reads. This skill mines it — past agent sessions, command analytics, shell

history — clusters the repeated prompts and command sequences, scores each

cluster by frequency x pain, and hands a ranked candidate list to

/automation-shape-routing, which decides the shape (workflow vs swarm vs

skill). Toil-mining is that router's missing feeder: routing is useless

without a measured queue of things worth routing.

Use when: the same prompt keeps getting hand-pasted across sessions; the operator asks what to automate next; or the scheduled compounding sweep fires. Non-goals: building the automation, choosing its shape, or editing history.

(user-invocable: false is interim — promotion to invocable needs catalog + dispositions rows, a separate one-line change outside this skill's directory.)

⚠️ Critical Constraints

• ⛔ NEVER dispatch via `claude -p` / `claude --print` — scheduled ticks and headless workers use `codex exec` (or the local llama lane). Why: because of LAW 0 — claude -p bills the API / burns the Max quota, is hook-blocked on this host, and a sweep that fires on a timer would burn it on a schedule.
• Measure before believing. Candidates come from counted history, never from "I feel like I do this a lot." Why: because intuition about repetition is unreliable — the measured record shows the inversion that intuition misses (see worked example: rituals at 94x while skills sat at ≤9x).
• This skill emits candidates; it never builds the automation or picks its shape. Why: because shape (workflow vs swarm vs skill) is /automation-shape-routing's single job — a miner that also builds grades its own homework and duplicates the router.
• Filter machine echoes before clustering. Tool results, file-update confirmations, and error strings repeat far more than any human ritual and are not toil. Why: because the top raw counts are almost always harness noise; ranking them wastes the whole run (in the fixture, the top 4 raw entries are all machine echoes).
• Hand-pasted prompts are the loudest toil signal. A long, structured prompt pasted N times is a skill or tick that does not exist yet. Why: because each paste costs operator attention and drifts a little — variant copies of the same ritual diverge until no canonical version exists.
• Read sources read-only. Session archives, analytics DBs, and shell history are evidence; never rewrite or prune them. Why: because the mine must stay replayable — next month's sweep diffs against the same record.

Sources

Execution Steps

Step 1: Collect

Pull from every available source above; skip missing ones gracefully and note which were consulted. Capture per item: text, count, first/last seen, source.

Checkpoint: at least one source produced counted data. If none did, stop and report "no measurable history" — do not fall back to guessing.

Step 2: Cluster

Group near-duplicates (the same ritual pasted with small edits, the same command chain with different arguments) into clusters. Then split each cluster: human-initiated toil vs machine echo (tool results, success confirmations, error strings). Discard the echoes from ranking; keep their counts as context.

Checkpoint: every surviving cluster traces to something a human typed, pasted, or deliberately re-ran.

Step 3: Score — frequency x pain

score = frequency x pain, where pain weighs: length/structure of the pasted text, whether it runs unattended (overnight > interactive), consequence of getting it wrong (safety gates, money, external sends), and drift risk (how many variants the cluster contains). Rank descending. A high-frequency one-word nudge ("ok") can still rank low: frequency alone is not the verdict.

Checkpoint: the ranking would survive the operator reading it — each score has a one-line justification naming both factors.

Step 4: Emit and hand off

Write the ranked candidate list (see Output Specification), each with a suggested next step. Hand the list to /automation-shape-routing for the shape decision; durable candidates worth tracking become bead candidates via /beads-workflow. The miner stops there.

Modes

Compounding is the point: a one-off mine pays once; a scheduled sweep keeps catching new rituals as they form, before they fossilize into 90-paste habits.

Worked Example

Input: fixtures/rituals-excerpt.json — a 20-entry excerpt derived from a real ritual scan (71,191 prompts scanned). Step 2 discards the top raw counts (1545x "Bash completed with no output", 498x, 337x, 319x — all machine echoes). Step 3 ranks the surviving human toil:

# Toil-mining candidates — 2026-06-12

| Rank | Cluster | Freq | Pain | Why it ranks here | Suggested next step |
|---|---|---|---|---|---|
| 1 | overnight factory supervisor ritual ("[/loop overnight factory supervisor — Bo is asleep...]") | 94 | very high | ~150-word safety-critical prompt, hand-pasted, runs unattended overnight, gates external actions | route to automation-shape-routing; likely a scheduled tick + skill |
| 2 | META-ORCHESTRATOR TICK v2 | 81 | very high | multi-section orchestration pass, pasted 81x in ~20h, drift-prone across variants | same — strongest tick candidate |
| 3 | one-work-tick factory prompt | 39 | high | structured single-unit work dispatch with hard gates | fold into the same tick family as #1/#2 |
| 4 | "keep going towards goal" | 44 | medium | pure nudge; cheap to type but signals a missing supervisor loop | symptom of #1-#3; closes when they ship |
| — | "ok" (112x) | 112 | low | one-word approval; frequency high, pain near zero | not a candidate — note only |

Frequency inversion: these hand-pasted rituals ran 94/81/44/39 times while no
skill invocation exceeded 9 in the same window. The automation that exists is
not the automation that is needed.

Candidate #1 is the 94x overnight-supervisor ritual: highest combined score because it is long, safety-gated, unattended, and pasted nearly a hundred times — exactly the profile of a tick that should already exist.

Output Specification

Format: markdown report — ranked candidate table (cluster, frequency, pain, justification, suggested next step) plus a sources-consulted line and the discarded-echo note; the same data may be mirrored as JSON when a caller asks for machine output. Filename: written to .agents/toil-mining/YYYY-MM-DD-candidates.md (compounding mode appends a dated section to the same directory's ledger). Next action: hand the top candidates to /automation-shape-routing; track keepers as bead candidates.

Quality Rubric

• [ ] Every candidate carries a measured count from a named source, not an estimate
• [ ] Machine echoes were filtered and noted, never ranked
• [ ] Each score names both factors (frequency AND pain) in one line
• [ ] The report ends with a handoff to automation-shape-routing, not a built automation
• [ ] No history source was modified
• [ ] Compounding runs diffed against the prior findings file instead of re-reporting old clusters

See Also

• automation-shape-routing — downstream consumer; decides the shape of each candidate
• cass — the session-archaeology source
• beads-workflow — lands accepted candidates on the tracker

Reference Documents

• references/tick-design.md — the compounding-mode scheduled-tick design (launchd / systemd user timer dispatching codex exec; findings ledger + bead candidates)

Compounding-mode scheduled tick — design

How --compounding runs unattended: a host scheduler fires a headless worker on a cadence, the worker runs one mining sweep, and the results land in durable artifacts (a findings ledger + bead candidates) instead of a chat transcript.

⛔ Dispatch constraint (LAW 0)

The tick dispatches `codex exec` — NEVER claude -p / claude --print. That path bills the Anthropic API and/or burns the Claude Max weekly quota, is mechanically blocked on this host (~/.claude/hooks/no-claude-p-guard.sh), and a scheduler would re-commit the violation on every fire. Acceptable headless lanes: codex exec (default), the local llama endpoint for cheap pre-filtering. There is no third option; do not reason past this.

Shape

scheduler (launchd | systemd user timer)
  └─> tick script (thin shell wrapper)
        └─> codex exec "<compounding-mode prompt>"
              ├─> reads sources (cass, rtk history, shell history, ritual scans)
              ├─> diffs clusters against the previous findings entry
              ├─> appends a dated section to .agents/toil-mining/findings.md
              └─> emits bead-candidate stanzas for new/grown clusters

The tick is idempotent per day: re-firing overwrites nothing, it appends one dated section keyed by date. The worker gets a fresh context every fire — all continuity lives in the findings ledger it diffs against, not in the session.

Cadence

Weekly is the default. Daily is wasteful (rituals take days to form); monthly lets a new ritual hit dozens of pastes before it is caught. Tune per host activity, not per enthusiasm.

Mac — launchd

~/Library/LaunchAgents/com.bo.toil-mining-tick.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.bo.toil-mining-tick</string>
  <key>ProgramArguments</key><array>
    <string>/bin/zsh</string><string>-lc</string>
    <string>codex exec "Run the toil-mining skill in --compounding mode over this host's usage history; append findings to .agents/toil-mining/findings.md and emit bead candidates for new clusters." &gt;&gt; "$HOME/.local/state/toil-mining/tick.log" 2&gt;&amp;1</string>
  </array>
  <key>StartCalendarInterval</key><dict>
    <key>Weekday</key><integer>1</integer>
    <key>Hour</key><integer>7</integer>
    <key>Minute</key><integer>30</integer>
  </dict>
</dict></plist>

Load with launchctl bootstrap gui/$(id -u) <plist>; verify with launchctl print gui/$(id -u)/com.bo.toil-mining-tick.

bushido (WSL) — systemd user timer

~/.config/systemd/user/toil-mining-tick.service:

[Unit]
Description=toil-mining compounding sweep (codex exec; never claude -p)

[Service]
Type=oneshot
ExecStart=/usr/bin/env zsh -lc 'codex exec "Run the toil-mining skill in --compounding mode over this host's usage history; append findings to .agents/toil-mining/findings.md and emit bead candidates for new clusters."'

~/.config/systemd/user/toil-mining-tick.timer:

[Unit]
Description=weekly toil-mining sweep

[Timer]
OnCalendar=Mon 07:30
Persistent=true

[Install]
WantedBy=timers.target

Enable with systemctl --user enable --now toil-mining-tick.timer; inspect with systemctl --user list-timers and journalctl --user -u toil-mining-tick.service.

Output routing

The tick never auto-builds an automation and never escalates a candidate past "bead created" — shape decisions stay with /automation-shape-routing, and anything external stays gated on the operator.

Failure behavior

• Worker failure: log to the tick log and exit non-zero; the next fire retries. No partial ledger writes — build the section in a temp file, append atomically.
• Missing source (no rtk, no ritual scan that week): note it in the section and continue with the rest; an empty sweep is a valid, cheap result.
• Quota/rate pressure on the codex lane: skip the fire (log "skipped: lane unavailable") rather than falling back to any Claude headless path — the fallback that "just this once" uses claude -p is the exact failure LAW 0 exists to stop.