Curate Minions

---
name: curate-minions
description: "Walk the current project's latest minions-curator report
  and triage each tmp/ script candidate: review evidence, preview a
  refactor diff, apply (backup, refactor, move, update minions/TOOLS.md,
  commit) or skip. Never bulk-applies. Usage: /curate-minions [week]"
---

# /curate-minions

Project-local skill (deployed per-project, same convention as
`fix-review` — canonical source here, a copy in each opted-in project's
`.claude/skills/curate-minions/`, synced manually on update, not
symlinked). Reads the report `minions-curator scan`/`scan-all` already
produced for the **current project** (the one this session is running
in) and triages it interactively. This skill does not scan or score
anything itself — that's `minions-curator`'s job, fully deterministic,
no LLM call. This skill is the part that needs real judgment: is this
refactor safe, is this really a duplicate, does the proposed name make
sense.

Full design rationale: `~/wrk/projects/minions-curator/context/design.md`
(§7 in particular). Read it if anything below is unclear — this skill
is a direct implementation of that section.

## When to invoke

- Any time after `minions-curator scan-all` (weekly cron) or
  `minions-curator scan --project .` (manual) has produced a report for
  the current project.
- User explicitly runs `/curate-minions` (optionally with a week tag,
  e.g. `/curate-minions 2026-W35`; default: latest).

## Inputs

- Report: `~/wrk/common/reports/minions/<project-slug>/<week>.md`
  — `<project-slug>` is `discover.Slug()`'s output for the current
  project (its directory basename; check `internal/discover/discover.go`
  in the `minions-curator` repo if the slug is ambiguous).
- The actual candidate files under `./tmp/` in the current project.
- The current project's `./minions/TOOLS.md` (create if it doesn't exist
  yet — first promotion in a project that hasn't had one before).

## Steps

### 1. Locate the report

```bash
SLUG=$(basename "$(git rev-parse --show-toplevel)")
WEEK="${1:-latest}"
REPORTS_DIR="$HOME/wrk/common/reports/minions/$SLUG"
if [[ "$WEEK" == "latest" ]]; then
  # Robust selector: handles spaces/specials in path and filename, and
  # doesn't hardcode a calendar year (an ISO-week filename like
  # 2026-W01.md rolls into 2027-W## eventually — a literal "2026-"
  # prefix would silently stop matching future reports).
  REPORT=$(find "$REPORTS_DIR" -maxdepth 1 -type f -name '[0-9][0-9][0-9][0-9]-W*.md' \
           -printf '%T@ %p\n' 2>/dev/null \
           | sort -rn | head -1 | cut -d' ' -f2-)
else
  REPORT="$REPORTS_DIR/$WEEK.md"
fi
```

No report found → tell the user to run `minions-curator scan --project .`
first (or wait for the weekly cron), don't fabricate candidates.

### 2. Parse candidates

Each report section (`## N. \`tmp/...\``) has: Confidence, Evidence,
optionally a Genericity warning, optionally a "Possible duplicate"
warning, and a Suggested name. Read the whole report — it's small,
generated by a deterministic tool, not worth chunking.

### 3. Show a summary, then walk each candidate

```
Found N candidate(s) in <week>: X high, Y medium, Z low confidence.
Process all? [y/select/skip-low/abort]
```

For each candidate, in confidence order (high → medium → low, same as
`apply-dreaming`'s triage order):

```
[1/N] tmp/dump_users.py → minions/dump-users.py
  Confidence: medium (genericity+substance passed)
  Evidence: 3 run(s) across 2 session(s), 28 non-blank line(s)
  Genericity: looks tied to a one-off value — needs a parameter

  [a]pply / [s]kip / [e]dit-name / [v]iew-full-script / [q]uit
```

- **`view-full-script`** — Read the actual `tmp/` file before deciding;
  the report's evidence is a summary, not a substitute for reading the
  code being promoted.
- **`edit-name`** — override the suggested `minions/<name>` before
  applying.
- **A "Possible duplicate" warning never auto-skips** — show it, let the
  human decide; `minions-curator`'s duplicate check is a cheap name-
  overlap heuristic, not a reliable one.
- **Before recommending `apply` on any candidate — even one with no
  "Possible duplicate" warning** — read the current `minions/TOOLS.md`
  and skim what each existing entry actually does, not just its name.
  The heuristic only catches name overlap (`dump_users.py` vs
  `dump-users.py`); it has no way to notice that `tmp/cdp-eval.py` (a
  stdlib-only fallback for a missing `websockets` module) already
  duplicates `minions/cdp`'s `eval` mode under a completely different
  name. A semantic duplicate the heuristic missed is exactly the kind
  of judgment call this skill exists for — don't let the absence of a
  flag stand in for having actually checked.

### 4. On `apply`

1. **Backup the original `tmp/` file first.** Non-negotiable — copy to
   the harness's scratchpad directory or a `tmp/.curator-backup/`
   subdirectory before touching anything. No exceptions, regardless of
   confidence level.
2. **Decide refactor aggressiveness.** If the report flagged a
   genericity failure (an embedded UUID/timestamp/absolute one-off
   path), read the actual file and judge whether replacing that literal
   with a CLI flag/argument is safe and unambiguous:
   - **Confident** → generate the diff (hardcode → flag, plus a short
     usage header if the script doesn't already have one) and **show it
     before writing it**. Never apply a refactor the human hasn't seen.
   - **Not confident** (the hardcoded value is load-bearing in a way
     that isn't a simple substitution, or the script's structure makes a
     flag non-obvious) → don't guess. Move the file as-is and add a note
     in its `TOOLS.md` entry that it needs manual cleanup.
3. **Move** `tmp/<file>` → `minions/<name>` (`git mv` if the project's
   git is otherwise clean about it, plain `mv` + `git add` is fine too).
4. **Update `minions/TOOLS.md`** — one line, same format as existing
   entries (see any current entry for the pattern: backtick-quoted
   invocation with real flags, then a one-sentence description grounded
   in what the script actually does — read it, don't infer from the
   filename alone).
5. **Delete the `tmp/` original** only after the move is confirmed to
   have succeeded (file exists at the new path, is executable if it was
   before).
6. **Commit** in the current project, using that project's own
   commit/push convention (check its `CLAUDE.md` — most personal
   projects under `~/wrk/` commit and push freely; don't assume, verify).

### 5. On `skip`

Leave the file in `tmp/` untouched. Record the skip in
`tmp/.curator-skip.json` (git-ignored, same convention as
`tmp/.exec_log`) so next week's triage doesn't re-litigate a decision
already made for the same reason:

```jsonc
// tmp/.curator-skip.json — one entry per skipped candidate, keyed by path
{
  "cdp-eval.py": {
    "skipped_at": "2026-09-01",
    "reason": "duplicate of minions/cdp's eval mode"
  }
}
```

Before showing a candidate in Step 3's walk, check this file: if an
entry exists **and** the file's `mtime` hasn't changed since
`skipped_at` (i.e. it wasn't edited to become genuinely different),
list it in the summary as already-triaged rather than re-asking —
`"tmp/cdp-eval.py — skipped 2026-09-01 (duplicate of minions/cdp);
re-flag with 'e' to reconsider"`. Give the human an escape hatch (an
`e` option in that line) to force it back into the normal walk — this
is a memory aid against re-litigating, not a hard suppression. If the
file's `mtime` is newer than `skipped_at`, treat it as a fresh
candidate again (something changed) and drop the stale entry.

This is a lightweight file-marker, not `minions-curator` report
annotation — the scan tool itself stays free of any per-skip state (it
would need to read this file on every run just to skip re-flagging,
adding a second reason its scoring output can vary run to run). If
this marker file itself turns out to be worth surfacing in the report
(e.g. so `scan --project .` can silently exclude an already-skipped,
unchanged candidate instead of the skill filtering it post-hoc), that's
a `minions-curator` binary change to consider later — not a reason to
block this skill-level fix now.

## Hard constraints

- **No bulk-apply, ever.** Every candidate gets its own individual
  accept/skip, regardless of confidence level or how many candidates
  there are.
- **No silent refactor.** A diff is always shown before it's written.
- **No deletion without a prior backup.** Applies even to a "confident"
  high-confidence candidate.
- **Never touch a `tmp/` file the scan already excluded as git-tracked**
  — if you find one anyway (race condition, manual report edit), treat
  it as a bug in the report, not something to act on.
- **This skill only edits the current project.** It never reaches into
  another project's `tmp/`/`minions/` even if its report is sitting
  right there in the shared `~/wrk/common/reports/minions/`
  directory — that directory is shared storage for reports, not license
  to cross project boundaries from a single invocation.