freshness-triage
Skill4 starsChanged 3 days agoMITView on GitHub
The reaper's content judgment of one idle bead: is its premise still real against the repo at HEAD? Emits a structured fresh | already-done | obsolete verdict. Called by `reaper --judge` (headless `claude -p`, cmd/reaper/judge.go) and by the in-session /reaper skill (Step 3); a dead verdict is what lets the reaper close the bead. Read-only; it never closes anything itself.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ac-quality-reviewSkill
- beadsSkill
- consult-councilSkill
- create-beadSkill
- playwright-cliSkill
- reaperSkill
- reviewSkill
- rubSkill
- verify-acceptanceSkill
- wishSkill
- create-beadSkill
- wishSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Before anything else: run djinn skills check --here in the repo you are working in.
- Very specific: line 47
If bead_id is missing, stop and ask.
- Distinctive: line 71
Read-only only. Do NOT edit, build artifacts, or mutate the tree.
- Distinctive: line 154
Verify against the repo at HEAD: Read the actual checked-out code, not your memory of it.
≈ “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.
Files
<!-- 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 -->Freshness Triage
Overview
This skill judges one idle bead and answers one question:
"Is this bead's premise still real against the current codebase — should this bead exist at all?"
Idle backlogs accumulate beads whose work landed through another bead or commit, or whose premise was redesigned away. Idle age alone never closes a bead; this judgment against HEAD is the content evidence that can.
Two callers, both the reaper:
| Caller | Surface | Acts on the verdict |
cmd/reaper/judge.go | reaper --judge, headless claude -p driver; parseFreshnessVerdict decodes the sidecar | fresh → keep; already-done / obsolete → close, high confidence, reason as the close reason |
core/skills/reaper/SKILL.body.md | in-session /reaper, Step 3 | same mapping; closes only on operator confirmation |
Both callers reject a dead verdict with an empty reason and a sidecar whose bead names a different id — either leaves the candidate untouched.
This is a single-pass judgement — one agent, one pass, one verdict. It does not iterate, dedupe, or fan out.
Scope boundary — what this judgment does and does NOT do
It answers ONLY "should this bead exist at all?" It does NOT:
- Refresh stale file paths. Design
file:linereferences are hints, not contracts; whoever implements the bead re-grounds them. A real premise with moved breadcrumbs isfresh. Do NOT emitobsoletemerely because a cited path moved. - Judge acceptance-criteria quality. That is
ac-quality-review, run by/create-beadat filing time. A bead with a real premise and vague criteria is stillfreshhere. - Re-plan the work. Whether this is the right work is decided when it is filed (
/create-bead). This judgment only asks whether the premise the bead already states is still true.
Inputs
The invoker must provide:
bead_id— e.g.phoenix-abcd. The skill readsbd show <bead_id> --jsonto fetchdescription,acceptance_criteria,design, andnotes.
If bead_id is missing, stop and ask.
Process
Step 1. Read the bead
bd show <bead_id> --json | jq -r '.[0] | {type, description, acceptance_criteria, design, notes}'Identify the bead's claimed deliverable: the concrete capability, symbol, file, endpoint, or behavior the bead says it will produce. This is what you check against HEAD.
Step 2. Check the deliverable against the repo at HEAD
You are running in the reaper's checkout at HEAD. Use read-only commands to test whether the deliverable already exists:
# Does the named symbol / file / endpoint already exist?
git grep -n "<named symbol or string>" -- '<likely path glob>'
ls <cited deliverable path>
# Does the cited test already exist and pass?
go test ./<cited package> -run '<CitedTest>' # or the project's test commandRead-only only. Do NOT edit, build artifacts, or mutate the tree.
Step 3. Decide the verdict
Apply this decision order:
- Is the deliverable already present and satisfied at HEAD? If the named symbol/file/endpoint exists and the cited acceptance is already met (e.g. the cited test exists and passes), the work landed via another path → verdict
already-done. Thereasonnames the concrete evidence (which symbol/test you found). - Is the premise still real? Re-read the bead's
description— the thing it wants to change. Does that thing still exist to be changed? Was the subsystem removed, the feature redesigned away, or the approach explicitly ruled out (e.g. by a parent epic's non-goals)? If the premise no longer exists, no implementation can satisfy the bead → verdictobsolete. Thereasonnames what was removed/redesigned and (where possible) the bead/commit/decision that removed it. - Otherwise →
fresh. The premise holds and the work is real and unstarted (or only partially done — a partially-done bead with real remaining work isfresh, notalready-done;already-donemeans the acceptance is FULLY satisfied at HEAD). Thereasonnames why the premise still holds (e.g. "the named handler does not yet exist; the design file it references is still present").
Bias toward fresh under uncertainty. Closing a live bead as stale costs more than keeping a dead one another reaper pass. Emit already-done or obsolete only when the evidence is concrete — a found symbol, a passing cited test, a removed subsystem, an explicit non-goal. Vague suspicion is fresh.
Step 4. Emit the structured sidecar
Emit a fenced json block (and at most ~300 words of prose above it). The reaper parses ONLY the fenced JSON.
{
"verdict": "fresh",
"bead": "<bead_id>",
"reason": "<one or two sentences naming the concrete evidence for the verdict>"
}verdict MUST be exactly one of fresh, already-done, or obsolete (lowercase canonical; the reaper normalizes casing but emit lowercase). bead MUST equal bead_id. reason MUST be non-empty — it becomes the bd close reason for a stale verdict, and the reaper refuses to close on an empty one.
The schema is checks.FreshnessSidecar (internal/djinn/formula/checks/freshness_verdict.go); the implement step's already-done exit (internal/djinn/session/implement_verdict.go) writes the same shape without running this skill. Change the keys or tokens only together with both readers.
Verdict reference
| Verdict | Meaning | Reaper disposition |
fresh | Premise still holds; work is real and unstarted/partial | keep |
already-done | Acceptance is FULLY satisfied at HEAD (work landed elsewhere) | close, high confidence |
obsolete | Premise no longer exists (subsystem removed / redesigned away / explicit non-goal) | close, high confidence |
Worked examples
Example 1 — fresh
Bead asks to add a djinn.bead_claim_v2 handler. git grep djinn.bead_claim_v2 returns nothing; the design file it cites still exists.
{
"verdict": "fresh",
"bead": "djinn-abcd",
"reason": "The named handler djinn.bead_claim_v2 does not exist at HEAD and the design file it references is still present; the work is real and unstarted."
}Example 2 — already-done
Bead asks for a capability that a sibling bead already shipped. git grep finds the symbol; the cited acceptance test passes.
{
"verdict": "already-done",
"bead": "djinn-abcd",
"reason": "The deliverable landed via sibling bead djinn-wxyz (commit 7ab9c28); the cited test TestFoo exists and passes at HEAD, so the acceptance is already satisfied."
}Example 3 — obsolete
Bead asks to modify a subsystem the parent epic's non-goals explicitly removed.
{
"verdict": "obsolete",
"bead": "djinn-abcd",
"reason": "This bead modifies the summoner triage path, but parent epic djinn-aaqu's non-goals decision explicitly removed triage logic from the summoner; the premise no longer exists to be changed."
}Failure-mode handling
- Bead not found.
bd show <bead_id>exits non-zero. Emit verdictfreshwith a reason naming the lookup failure — do NOT close a bead you could not read. - Probe commands unavailable (
git/goabsent). Default tofresh— never close a bead on a toolchain failure. Inconclusive evidence isfresh.
Universal constraints
- Verify against the repo at HEAD. Read the actual checked-out code, not your memory of it. A claim about a symbol's presence names the
git grepyou ran. - Read-only. The skill never edits the bead or the tree. Closing a stale bead is the reaper's job; this skill emits the verdict only.
- Bias toward
fresh. Closing a live bead costs more than keeping a dead one. Emit a stale verdict only on concrete evidence. - Cap output at ~300 words of prose + the JSON sidecar. Tokens go to the HEAD check, not narration.
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
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.

