agentleFS
jayminwestjayminwest/warren/.agents/skills/seeds-issue-audit/SKILL.md

seeds-issue-audit

Skill519 starsChanged 3 months agoMITView on GitHub

Audit and triage open Seeds (sd) issues — find which can be closed, auto-close high-confidence completed ones, and report borderline cases. Activate for prompts like "audit open issues", "which seeds issues can be closed", "clean up the issue tracker", "triage the seeds backlog".

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

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

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

    Reconcile plans against code: If any open issue carries a plan_id, or recon shows active plans, run sd plan show <pl-id> and walk its steps.

    line 60
  2. Very specific:

    Avoid sd list --json over the full open set — it embeds full descriptions and is SLOW / may time out.

    line 66
  3. Very specific:

    If the issue carries a plan_id, pull the plan and map this issue to its step so you can judge it against sibling progress and shipped PRs:

    line 112
  4. Distinctive:

    BORDERLINE (report only): only weak/partial signals, an unconfirmed PR reference, stale-but-otherwise-quiet, or any ambiguity.

    line 157
  5. Very specific:

    Prefer individual closes so each --reason is accurate.

    line 185
  6. Distinctive:

    When you have closed every child of a plan, record the outcome:

    line 202
  7. Very specific:

    After all close passes and cascades settle, stage/commit the .seeds/ changes:

    line 208
  8. Distinctive:

    Do not push — the user pushes per the repo session-completion protocol.

    line 215
  9. Very specific:

    Never close an issue with a blocker that is still OPEN (a closed blocker does not count — verify live status, don't trust the blocked …

    line 218
  10. Very specific:

    Never auto-close an in_progress issue without explicit user confirmation.

    line 220
  11. Distinctive:

    If evidence is unconfirmed or contradictory, downgrade to BORDERLINE.

    line 222

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Protocol: Seeds Issue Audit & Triage

You audit the project's open Seeds (sd) issues, decide which are safely closeable, auto-close only the high-confidence completed ones, and report everything borderline for a human to review. You NEVER guess: every auto-close must cite concrete evidence. Staleness alone is never enough to close anything.

1. Operating Principles

  • Auto-close only HIGH confidence. A HIGH-confidence issue has at least one strong completion signal AND no unresolved blockers. Close it.
  • Report, never close, BORDERLINE. Weak/partial/ambiguous signals are surfaced in the report for a human — you do not touch them.
  • Leave contradicted issues open. Open blockers, "WIP" / "in progress" language, or a reopened history means NOT closeable, full stop.
  • A blocker only counts if it is still OPEN. sd blocked / sd ready membership is a SNAPSHOT, not proof — a "blocked" issue may be sitting behind a blocker that is already closed (stale dependency edge), and its work may be fully shipped. Audit the blocked set too; never auto-exclude it. Re-resolve every blocker's LIVE status before trusting the gate.
  • Cascade until the set stabilizes. Closing an issue can unblock its downstream consumers. After every close pass, RE-AUDIT anything that was blocked solely by the issues you just closed — its work may already be done and merely waiting on a stale edge. Loop until a pass closes nothing.
  • Plans drift ahead of their seeds. A plan can be fully implemented and released while its child seeds stay open. Always reconcile plans against shipped code (Section 2) — don't trust plan_status/open child seeds at face value.
  • Evidence-first. Seeds has no first-class PR/commit field — references live only in free-text description / closeReason. Confirm them against git / gh before trusting them.
  • sd close is the only mutating command you run (plus sd sync to commit and sd plan outcome to record a finished plan). It is reversible via reopen. Never run sd update on others' issues; never push.

2. Recon (always run first, read-only)

Count the open set to pick an execution mode and gather candidates:

sd stats                       # totals by status/type/priority
sd list --format ids           # bare open issue ids, one per line (fast)
sd list --format compact       # "id Priority status title" one-liner (fast)
sd ready --json                # open issues with NO unresolved blockers
sd blocked                     # issues that ARE blocked (audit too — see below)
  • sd ready is the closeable-candidate gate for the FIRST pass — but it is a snapshot. Audit BOTH the ready set and the blocked set. The blocked set's edges are frequently stale: a "blocked" issue may sit behind a blocker that is already closed, with its own work fully shipped. Never silently exclude blocked issues from the audit.
  • For every blocked issue, resolve each blocker's LIVE status (sd dep list <id>, then sd show <blocker> if unsure). If all blockers are already closed, the issue is auto-close-eligible and must be scored like any other.
  • Reconcile plans against code. If any open issue carries a plan_id, or recon shows active plans, run sd plan show <pl-id> and walk its steps. A plan whose phase PRs have all merged/released is materially DONE even if several child seeds are still open — those children are stale-open and should be verified (Section 4) and closed. After closing all of a plan's children, record sd plan outcome <pl-id> --result success.
  • Avoid sd list --json over the full open set — it embeds full descriptions and is SLOW / may time out. Page it or use per-issue sd show <id> [more ids] --json (single or batched ids are fast).

3. Choose Execution Mode (adaptive by open-issue count)

Count open issues with sd stats or sd list --format ids | wc -l, then:

Open issuesMode
<= 15INLINE — audit every issue yourself in this agent.
> 15FAN OUT — split ids into batches (~10 per batch) and dispatch one parallel worker subagent per batch via the Task tool.

In FAN OUT mode, each worker audits its batch (Sections 4–5) and returns a structured per-issue verdict. The orchestrator then aggregates all verdicts, performs the auto-closes itself (Section 6), and compiles the report (Section 7). Workers MUST NOT run sd close / sd sync — auditing only.

Required worker return format (one block per issue)

- id: <issue-id>
  title: <title>
  score: <integer>
  signals: [<merged-pr|plan-done|blockers-clear|stale|wip|...>]
  recommendation: <auto-close | report-borderline | leave-open>
  close_reason: "<proposed concise evidence-based reason, or empty>"

4. Gather Signals (per issue)

Pull the full record and scan it:

sd show <id> --json            # id, status, type, priority, createdAt,
                               # updatedAt, description, closeReason,
                               # labels, blockedBy, blocks, plan_id,
                               # plan_status, parentId, extensions
sd dep list <id>               # list "Blocked by" edges

For EVERY blocker listed, confirm its LIVE status — a blocker that is already closed does not count. Do not infer "blocked" from sd blocked membership alone; resolve the actual edge:

sd show <blocker-id> --json | grep -E '"status"'   # closed blocker ≠ a blocker

If the issue carries a plan_id, pull the plan and map this issue to its step so you can judge it against sibling progress and shipped PRs:

sd plan show <plan-id>         # steps, child seeds, blocks edges, status

Extract references from description + closeReason (the only place PRs / commits appear) with these patterns:

ReferenceRegex
PR / issue number#\d+
Plan idpl-[0-9a-f]+
Warren tracker idwarren-[0-9a-f]+
Commit SHA\b[0-9a-f]{7,40}\b
Completion languagemerged, done, closed, shipped, landed

Confirm references are REAL completions (best-effort; gh is optional):

git log --oneline --all | grep -iE "<issue-id>|#<pr-number>|<sha>"
gh pr view <N> --json state,merged   # state=MERGED / merged=true → confirmed

A PR reference counts as a strong signal only when gh reports it MERGED, or the commit/PR is found on the default branch via git log.

5. Score & Decide (weighted rubric)

Score each issue, then map to a verdict.

Signals & weights

  • Merged PR / commit confirmed (gh merged=true, OR commit/PR on default branch): strong (+3).
  • plan_status == "done" for the issue's plan, paired with completion language: strong (+3).
  • blockedBy empty OR every listed blocker already closed: required gate (+1). If ANY blocker is still open → NOT auto-closeable, period.
  • Staleness: updatedAt older than the threshold (default 90 days, override if the user prompt specifies one): weak (+1), flag-only. Staleness ALONE never auto-closes.

Confidence bands

  • HIGH (auto-close): at least one strong signal AND no unresolved blockers AND no contradiction.
  • BORDERLINE (report only): only weak/partial signals, an unconfirmed PR reference, stale-but-otherwise-quiet, or any ambiguity.
  • NOT CLOSEABLE (leave open): any open blocker, "WIP"/"in progress" language, or evidence the work is unfinished/reopened.

Decision table

Strong signal?Blockers clear?Other signalsVerdict
Yes (merged PR / plan done)Yes—AUTO-CLOSE
YesNo (open blocker)—LEAVE OPEN
NoYesunconfirmed PR ref / completion language onlyREPORT BORDERLINE
NoYesstale only (updatedAt past threshold)REPORT BORDERLINE
NoYesnone / fresh / no signalsLEAVE OPEN
AnyAny"WIP" / reopened / unfinishedLEAVE OPEN
——status == in_progressREPORT (never auto-close w/o explicit OK)

6. Closing Protocol (orchestrator only)

Close ONLY the HIGH-confidence set. Cite the signal in every reason.

# Close one — reason cites concrete evidence
sd close <id> --reason "PR #197 merged; plan pl-55a3 done"

# Batch-close ONLY when issues share the exact same reason
sd close <id1> <id2> <id3> --reason "shared evidence here"
  • Prefer individual closes so each --reason is accurate; batch only when the reason genuinely applies to all.

Cascade re-audit (mandatory after every close pass). Closing an issue can clear the last open blocker of a downstream issue. Before you sync:

  1. Collect the issues that were blocked SOLELY by the ones you just closed (sd ready will now list newly-unblocked items; cross-check against the blocks edges of the closed set).
  2. Re-audit each (Sections 4–5) with its blockers now resolved. Many will be stale-open work that already shipped — verify evidence and auto-close the HIGH-confidence ones.
  3. Repeat until a full pass closes nothing (the set has stabilized).

This is how a fully-shipped-but-unclosed plan chain gets caught: closing the early phases unblocks the later phases, whose PRs already merged.

  • When you have closed every child of a plan, record the outcome:
sd plan outcome <plan-id> --result success   # or partial / failure
  • After all close passes and cascades settle, stage/commit the .seeds/ changes:
sd sync
  • Do not push — the user pushes per the repo session-completion protocol.

Hard safety rules

  • Never close an issue with a blocker that is still OPEN (a closed blocker does not count — verify live status, don't trust the blocked snapshot).
  • Never auto-close an in_progress issue without explicit user confirmation.
  • Staleness-only is never an auto-close.
  • If evidence is unconfirmed or contradictory, downgrade to BORDERLINE.

7. Final Report

End with a concise, scannable summary — two tables.

Auto-closed

idtitlereason
......evidence-based close reason

Borderline (needs human review)

idtitlesignalswhy not auto-closedsuggested action
......stale 140d; PR #x unconfirmedno confirmed completion signalverify PR #x merged, then close

Optionally render these with the <json-render> Table / Card components for the terminal UI. Lead with the counts (e.g. "Closed 6, flagged 9 borderline, left 29 open") so the outcome is obvious at a glance.

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.