---
name: repetitive-work-automation
description: Mines agent session transcripts and history for recurring manual work, scores candidates by effort-vs-payoff, and proposes the cheapest proven automation (hook, skill, script, rule, or scheduled agent). Use when a user repeats themselves across sessions, when workflows feel manual, when asked what to automate, or when building an automation backlog.
---

# Repetitive Work Automation

## Purpose

Turn the work you already do into automations you never do again. Instead of guessing what to automate, this skill mines real evidence (session transcripts, tool-call histories, shell history) for repeated patterns, scores them on effort vs payoff, and hands off the right fix type with proof it works. The discipline comes from Robotic Process Mining (Dumas et al.): discover routines from interaction logs, assess automatability, then synthesize executable specifications.

## Workflow

### 1. Mine

Gather evidence from the user's actual sessions, never from vibes:

- Session transcripts (Claude Code `~/.claude/projects/*/sessions/*.jsonl`, or your own transcript logs)
- Tool-call histories and shell history (`~/.bash_history`, `~/.zsh_history`)
- Recurring scheduled jobs and cron bodies

Run the miner:

```bash
python3 scripts/mine_candidates.py --transcripts ~/.claude/projects --top 20
```

The miner normalizes messages (strips names, dates, file paths), clusters by 3-word shingles with Jaccard similarity >= 0.6, and reports clusters that appear 3+ times. Each cluster shows count, representative samples, and detected tools used. Anything below 3 occurrences is noise, not a candidate.

Manual alternative when no transcript files exist: ask the user "what have you had me do more than twice this week?" and treat their answer as the candidate list.

### 2. Score

For each candidate, fill in three numbers:

- **freq**: occurrences per week (from the miner, or the user's estimate)
- **minutes**: manual minutes per occurrence (ask the user if unknown)
- **variance**: 1-5, how different each occurrence is (1 = identical, 5 = every time is different)

Run the scorer:

```bash
python3 scripts/score_candidates.py --candidates candidates.json
```

Scoring rule: `weekly_value = freq * minutes * 4.33` (minutes saved per month). Sort by weekly_value, then discount by variance: score = weekly_value / variance^1.5. Candidates with variance >= 4 get flagged "redesign before automating" (Salesforce process-mining guidance: high variation means the process needs redesign first, not automation).

Pick the top 3. The rest go in the backlog, not the trash.

### 3. Propose

Match each top candidate to the cheapest fix that covers the recurrence, using this decision ladder (cheapest first):

| Fix type | Use when | Example |
|---|---|---|
| Standing rule / note | Judgment needed, behavior guidance, no code | "Always check Render env before deploy" in memory |
| Shell script / alias | Deterministic sequence, same command each time | `git-wip.sh`: commit, push, verify |
| Hook | Event-triggered deterministic action around a tool | PostToolUse: run formatter after every Edit |
| Skill | Repeated workflow with judgment, reusable knowledge | This skill itself; trip-planner skill |
| Subagent / scheduled agent | Specialized expertise, parallelizable, recurring cadence | Nightly reconciliation sweep |
| MCP server | External service integration, docs lookup, browser | GitHub / Slack / database access |

Guiding heuristic from Anthropic's own engineers: if you do something more than once a day, it becomes a skill or command. More than once a week, a script or hook. More than once a month, a standing rule.

Write each proposal in `templates/automation-proposal.md` and show it to the user before building. Proposals need: what recurs (with transcript evidence: dates + quotes), the chosen fix type and why the cheaper options failed the fit, estimated build time, and expected monthly savings.

### 4. Prove

Build the automation, then prove it works before handing it off:

- **Scripts and CLIs**: run a real dry run against realistic input. `py_compile` every Python file. Show the before/after.
- **Hooks**: test with a controlled edit; confirm the hook fires and exits cleanly (exit code 1 on PreToolUse blocks the action, verify blocking works).
- **Skills**: run the skill on a fresh example input; check the output contract is satisfied.
- **Scheduled agents**: run once manually; verify output and timing.

Record the proof in the proposal (command run, result, date). An automation without a passing proof run stays a proposal, never a handoff. If the fix cannot be proven in this session, say so and leave the candidate unclaimed rather than shipping a guess.

## Output Contract

Every run of this skill delivers:

1. `candidates.json`: mined clusters with freq estimates and representative samples
2. `scored.json`: candidates ranked with weekly_value, variance, fix-type recommendation
3. `proposals/`: one filled `automation-proposal.md` per top-3 candidate
4. At least one proven automation (built + dry-run passing), or a clear statement of why the top candidate was left unbuilt

## Operating Rules

- Every factual claim about what the user repeats must cite transcript evidence (file, date, or quoted request). No "you seem to do X a lot" without receipts.
- Never invent frequency or time numbers. Unverifiable = ask the user or cut the candidate.
- Quality beats cadence: a wrong automation is worse than no automation. If the top candidate's variance is >= 4, propose redesign, not automation.
- Cheapest fix wins. Do not build a subagent for what a shell alias solves.
- Automations touching money, posting, deleting, or messaging stay proposals until the user explicitly approves them.
- Privacy: transcripts may contain secrets. Redact credentials and PII from candidates.json and proposals.