agentleFS
kurofunekurofune/claudit/.agents/skills/reaper/SKILL.md

reaper

Skill4 starsChanged 2 days agoMITView on GitHub

Interactive, review-first smart-reaper triage from inside a session. Drives the Tier-2 content-judgment pass (the SAME /freshness-triage mechanism the scriptable `reaper --judge` subcommand uses) over the current idle candidate set, presents each candidate's keep/close verdict with its cited HEAD evidence for operator review, and closes a bead ONLY on explicit operator confirmation — mutating no bead state until you approve. Honors every reaper exemption (reaper:keep, the MinPriority floor, follow-up grace, structural type protections) and the djinn-yume invariant (idle-age alone never closes). Triggers on: /reaper, interactive reaper, smart-reaper triage, review dead beads, content-aware reaping in session, triage the idle backlog.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before anything else: run djinn skills check --here in the repo you are working in.

    line 9
  2. Very specific:

    Read the same idle candidate set the reaper tool reads, via bd stale:

    line 64
  3. Very specific:

    Before judging anything, filter out every exempt candidate.

    line 118
  4. Very specific:

    Before firing any /freshness-triage call, report the count of ELIGIBLE (non-exempt) candidates to the operator — judgment is O(n) in that …

    line 155

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- djinn-compat-check: begin -->

Before anything else: run djinn skills check --here in the repo you are working in. If it exits non-zero, stop: relay its output to the user verbatim — it names the fix — and run no other step of this skill. On exit 0, continue.

<!-- djinn-compat-check: end -->

/reaper — Interactive Smart-Reaper Triage

Overview

/reaper is the interactive, review-first trigger for the smart reaper. It drives the Tier-2 content-judgment pass over the current idle candidate set from inside a session and presents each candidate's keep / close verdict — with the cited HEAD evidence behind it — for operator review, then closes a bead only on your explicit confirmation.

No defer from this surface. /reaper only ever produces keep or close: the /freshness-triage edge yields a high-confidence dead verdict (already-done/obsolete → close) or fresh → keep. The reaper's defer disposition (reaper.Defer, internal/djinn/reaper/judgment.go) is a scriptable-edge-only state reachable from reaper --judge; this interactive surface never emits it.

It is the in-session sibling of the scriptable reaper --judge subcommand (cmd/reaper, the scheduled/headless surface). The two share ONE judgment mechanism — the existing /freshness-triage skill — so they can never diverge in how a bead is judged. They differ only in trigger and disposition:

scriptable reaper --judge/reaper (this skill)
Triggerscheduled / CLI, --live to actin-session slash command
Judgmentdrives /freshness-triage headlessly (claude -p)drives /freshness-triage in-session
Close dispositionacts under --live (unattended)review-first; closes only on explicit operator approval
Defaultmutate nothing without --livemutate nothing until you approve

This skill is NOT the cheap SessionStart dry-run hook (that runs reaper with no flags and never judges — it costs no tokens). /reaper is on-demand, costs tokens (one /freshness-triage pass per eligible candidate), and needs an operator in the loop — that is the whole point of the review-first gate.

It is a single-pass triage: one /freshness-triage judgment per candidate, one review table, one confirmation. It does not iterate or fan out.

Scope boundary — what this skill does and does NOT do

  • It judges whether a bead's premise is still real (via /freshness-triage) and offers genuinely-dead beads for close. It does NOT re-plan work, judge acceptance-criteria quality, or close a bead on idle-age alone.
  • It never closes a bead the reaper exemptions protect, and never closes a bead with no positive deadness verdict — idle-age alone is advisory only (the djinn-yume invariant).
  • It mutates no bead state — no bd close, no defer — until you explicitly approve the proposed closes (the confirmation gate, below).

Process

Step 1 — Gather the candidate set AND its exemption metadata (read-only)

Read the same idle candidate set the reaper tool reads, via bd stale:

bd stale -d 7 -s open -n 0 --json

bd stale takes flags, not positional args: -d 7 is the idle-day window (the reaper's IdleThreshold, 168h), -s open is the candidate status, and -n 0 lifts the default 50-row cap so the WHOLE idle set is triaged (the reaper adapter passes -n 0 for exactly this reason — bd stale otherwise truncates at 50). Mirror the production reaper defaults so /reaper triages the same set the scriptable subcommand would. If the operator named a different window or status, pass it through; otherwise use these defaults. An empty result means nothing is idle — report "no idle candidates" and stop.

bd stale --json is NOT sufficient by itself for Step 2. Its records carry only id, title, description, design, acceptance_criteria, notes, status, priority, issue_type, owner, created_at, created_by, updated_at — no labels field and no dependencies field at all. But the Step-2 exemption predicate (below) needs each candidate's labels (for reaper:keep and review-follow-up) and dependency types (for the discovered-from follow-up signal). So you MUST enrich the stale set before filtering — do not try to apply the reaper:keep, review-follow-up-grace, or discovered-from exemptions from bd stale output alone (you cannot, and silently skipping them would offer an exempt bead for close — an AC3 violation).

Enrich with one additional read-only query — bd list --json carries both labels and dependencies[] (each dep entry has a type field, e.g. discovered-from, parent-child):

bd list --json -n 0          # every bead, WITH labels + dependencies[].type

-n 0 lifts bd list's row cap the same way it does for bd stale (the default caps well under the full backlog). Join on id: for each candidate the bd stale set returned, look up the same id in the bd list output and attach its labels array and its dependencies[].type set. A candidate's:

  • reaper:keep / review-follow-up exemption reads from the joined labels.
  • discovered-from exemption reads from the joined dependencies[] — the candidate is an auto-filed follow-up when any joined dep has type == "discovered-from" ({"depends_on_id": "...", "type": "discovered-from"}).
  • priority / issue_type / updated_at are present in BOTH outputs; either copy is fine.

This is the documented enrichment join — bd list --json -n 0 is the single command that supplies the labels and dependency types bd stale --json omits, so Step 2 can apply every exemption from in-band data with no out-of-band lookup. (Equivalently, a per-candidate bd show <id> --json carries labels and a dependency_type field; prefer the single bd list join over N bd show calls.)

Step 2 — Apply the exemptions FIRST (AC3 — never offer an exempt bead for close)

Before judging anything, filter out every exempt candidate. This mirrors the pure reaper.JudgmentEligible / judgmentExempt predicate (internal/djinn/reaper/judgment.go) exactly — do NOT invent a different exemption set. Read each candidate's labels and dependencies[].type from the Step-1 enrichment join (bd list --json -n 0), NOT from the bare bd stale record — the reaper:keep, review-follow-up, and discovered-from checks below all depend on those joined fields, which bd stale --json does not carry. A candidate is exempt (skip it; it is NEVER offered for close, it falls through to keep/advisory) when ANY of these holds:

  • It carries the reaper:keep label (the operator retention override) — read from the joined labels.
  • It is not age-reapable (an iter bead / structurally protected bead — beads.IsAgeReapable is false).
  • Its type is epic, or any type NOT in the reapable set (task, feature, bug, chore).
  • Its priority is above the floor — Priority < MinPriority (default MinPriority = 3, so P0 / P1 / P2 beads are protected; only P3 / P4 are eligible).
  • It is an auto-filed follow-up (joined labels contain review-follow-up, OR a joined dependencies[] entry has type == "discovered-from") with a non-zero UpdatedAt still within its grace window — now - UpdatedAt ≤ IdleThreshold + FollowupGrace (168h + 14d). A follow-up PAST the grace window is no longer protected. Caveat (mirrors judgmentExempt, internal/djinn/reaper/judgment.go): the grace check is gated on && !UpdatedAt.IsZero() — a follow-up with a ZERO UpdatedAt (never updated) does NOT take the grace exemption; it falls through to non-exempt and is judged like any other candidate.

Surface the exempt candidates in the review table as keep (exempt: <which rule>) so the operator sees they were considered and protected — do not silently drop them. Only the NON-exempt candidates proceed to judgment, so no token is spent judging a bead that can never be closed (a cost guard AND the AC3 correctness guarantee).

Step 2b — Disclose the eligible-candidate count (cost preview)

Before firing any /freshness-triage call, report the count of ELIGIBLE (non-exempt) candidates to the operator — judgment is O(n) in that count (one /freshness-triage pass per eligible bead, each costing tokens). For a large backlog (e.g. 250+ eligible) this discloses the token cost BEFORE it is spent, so the operator can scope the window down (Step 1 flags) or proceed knowingly. Keep it to one line, e.g. 42 eligible candidates to judge (42 /freshness-triage passes); proceeding.

Step 3 — Judge each eligible candidate via /freshness-triage (AC4 — reuse, do not reinvent)

For each NON-exempt candidate, drive the /freshness-triage skill against the current worktree at HEAD — the SAME mechanism the scriptable reaper --judge subcommand drives headlessly. Do NOT improvise a fresh judgment; invoke the named procedure so the in-session and scriptable surfaces stay in lockstep. Pass the candidate's bead id; /freshness-triage reads bd show <id> itself and emits its fenced verdict sidecar.

Map each /freshness-triage verdict to a /reaper disposition exactly as the scriptable edge's parseFreshnessVerdict does (cmd/reaper/judge.go):

/freshness-triage verdict/reaper dispositionClose reason
freshkeep(premise still real — not offered for close)
already-doneclose (high confidence)the sidecar reason (the retired/landed premise)
obsoleteclose (high confidence)the sidecar reason (the removed/redesigned premise)
(unrecognized / no fence)keepbias toward keep on any uncertainty

Two guardrails carried over from the scriptable edge:

  • A dead verdict (already-done/obsolete) with NO reason is downgraded to keep — a close must cite the retired premise (AC1); an empty reason cannot, so do not offer it for close.
  • Cross-check the sidecar's bead field against the candidate id. If /freshness-triage emits a verdict whose bead names a DIFFERENT id (LLM confusion, or a crafted description), the verdict is not attributable — leave that candidate untouched (keep), do not close it on another bead's verdict. A BLANK sidecar bead is tolerated (the skill simply omitted it) — only a present-and-different id is non-attributable (mirrors parseFreshnessVerdict in cmd/reaper/judge.go: sb != "" && sb != candidateID).

A candidate /freshness-triage cannot judge (skill error, no parseable sidecar) is left untouched (keep) with the failure noted — one un-judgeable bead never aborts the pass and never becomes a close.

Step 4 — Present the review table (AC1)

Present every candidate, grouped by disposition, with its cited reason:

CLOSE (genuinely dead — your approval required):
  djinn-abcd  P4  "Old foo migration"   — obsolete: foo subsystem removed in djinn-wxyz (commit 7ab9c28); the cited handler no longer exists at HEAD
  djinn-efgh  P3  "Duplicate bar task"  — already-done: bar shipped via djinn-1234; cited test TestBar passes at HEAD

KEEP (premise still real / exempt / no deadness signal):
  djinn-ijkl  P3  "Live feature work"   — fresh: the named endpoint still does not exist; work is real
  djinn-mnop  P2  "Important refactor"   — keep (exempt: P2 above MinPriority floor)
  djinn-qrst  P4  "reaper:keep roadmap"  — keep (exempt: reaper:keep label)
  djinn-uvwx  P4  "Idle but live"        — keep (no positive deadness signal; idle-age alone never closes — djinn-yume)

Each CLOSE row MUST name its cited HEAD evidence (the /freshness-triage reason). A candidate with no positive deadness verdict appears under KEEP, never CLOSE — this is the djinn-yume invariant made visible: idle-age alone never graduates to a close offer.

Step 5 — Confirmation gate (AC2 — close ONLY on explicit operator approval)

This is the load-bearing interactive affordance. After presenting the table:

  • Mutate NO bead state yet. Up to this point /reaper has run only read-only commands (bd stale, bd show, /freshness-triage). Nothing has been closed.
  • Ask the operator to approve the CLOSE set explicitly. Offer: approve all proposed closes, approve a subset (name the ids), or none. Do not proceed on silence, an ambiguous reply, or a generic "looks good" that does not clearly authorize closing — when in doubt, ask again. Default is review-first: no close happens without an explicit yes.
  • On approval, close ONLY the approved beads:
    bd close <id> --reason "reaper content-judgment close: <the cited /freshness-triage reason>"
    Close exactly the approved ids — never a bead the operator did not name, never an exempt or keep bead. After the approved closes, persist the bead-state to the Dolt remote so collaborators see the closures:
    bd dolt commit -m "reaper: interactive content-judgment closes (<ids>)"
    bd dolt push
  • If the operator approves none, mutate nothing and report that the triage was review-only — the candidates remain open for a future pass.

Report a final summary: which beads were closed (with their cited reasons), which were kept, and which were exempt.

Why this exists

The reaper's deterministic Tier-1 sweep (PlanStaleness) and the scheduled Tier-2 reaper --judge subcommand both act unattended. /reaper is the operator's surface: a content-aware reaping pass an operator can run from within a session and review before any bead is closed, seeing each keep/close verdict with its cited HEAD evidence rather than hand-triaging the whole idle backlog. The review-first confirmation gate is what makes it safe to run interactively — the unattended --live subcommand acts on its own judgment; /reaper acts only on yours. Driving the SAME /freshness-triage mechanism the scriptable subcommand drives is what guarantees the two surfaces never disagree about whether a bead is dead (AC4): one judgment, two triggers.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.