backlog-groomer
Manage the beads backlog for this project. Use when the user wants to review or triage open issues, reprioritize the backlog, identify obsolete issues to close, investigate a topic to inform future wo
SKILL.mdskills/backlog-groomer/SKILL.md
GitHubBacklog Groomer
Triage, prioritize, and research work tracked in the beads issue tracker. This
skill operates on the bd CLI — all mutations (create, close, update) require
explicit user approval before execution.
Determine which workflow the user needs based on their request. If ambiguous, default to workflow 1 (review and triage) for grooming requests, or workflow 4 (Investigate topic as spike) for research requests.
Issue Types Reference
Beads v1.0+ defines nine core issue types. Pick the type that matches the
shape of the work, not just its size. The validation.on-create=error gate
enforces required markdown sections per type — a bd create will fail if the
required sections are missing.
| Type | Required markdown sections | When to use |
|---|---|---|
task |
none | General work item (default) |
bug |
## Steps to Reproduce, ## Acceptance Criteria |
Defect — behavior diverges from intended |
feature |
## Acceptance Criteria |
New system capability (system-centric framing) |
chore |
none | Maintenance / housekeeping with no user-visible behavior change |
epic |
## Success Criteria |
Large body of work that decomposes into child issues |
decision |
## Decision, ## Rationale, ## Alternatives Considered |
Architecture decision record (ADR) — outcome of deliberation |
spike |
## Goal, ## Findings |
Timeboxed investigation that reduces uncertainty before a story |
story |
## Acceptance Criteria |
User-centric framing of a feature ("As a X, I want Y...") |
milestone |
none | Structural marker; contains no work itself |
Authoritative source: the ### Issue Types (Core Vocabulary) section of
the Basic Memory note brew/brew-beads. The required-sections table was
discovered empirically per the
engineering/agents/cli-validation-discovery-via-json-error-probing Basic
Memory note (probe each type with bd create --json and parse the error).
Type-pair conventions worth knowing: spike → story and spike → decision
(investigation precedes commitment); epic ⊃ stories ⊃ tasks (containment
hierarchy); milestone ⊐ {epics, stories, tasks} (set marker for release
boundaries).
Grooming Workflows
1. Review and triage
Scan the open backlog for issues that need attention: stale items, potential duplicates, blocked chains, and missing context.
Steps:
Run
bd list --status openandbd list --status in_progressto get the full picture. Runbd statsfor summary counts.Run
bd stale --days 60to flag aging issues. Separately flagin_progressissues stale >30 days as "stalled."Run
bd duplicatesto detect content-hash matches (if available; if not, usebd searchwith keywords from suspicious titles for near-matches).Run
bd find-duplicates(aliasfind-dups) to surface near-duplicates thatbd duplicatesmisses. Two-stage similarity architecture:- Mechanical Jaccard tokenization is the default
(
--method=mechanical, threshold0.5). Free, fast, pre-filters AI calls. Drop to--threshold=0.4for more recall when the backlog is small. - AI semantic comparison is opt-in (
--method=ai). Requiresai.api_keyconfig and bills per call (mechanical pre-filter limits spend). Only invoke when the user explicitly requests it orBD_AI_DUPES=1is set in the environment. - Distinct from
bd duplicates(which catches only exact content matches). - Present each candidate pair with a merge or supersede recommendation
using
bd supersede <loser> <winner>(preserves history) orbd duplicate <loser> <winner>(marks duplicate without closing). Apply only with explicit per-pair user approval.
- Mechanical Jaccard tokenization is the default
(
Run
bd blockedto identify issues stuck on unresolved dependencies.Cross-reference with
UPSTREAM-*.mdandSYNERGY-*.mdfiles if they exist (useGlobto find them). Note any UPSTREAM friction or SYNERGY extraction candidates that should have a corresponding beads issue.If Basic Memory MCP tools are available, call
mcp__basic-memory__search_notesfor key dependencies frompackage.jsonto surface known friction not yet in the backlog. Skip silently if unavailable.Present a structured triage table:
| ID | Title | Age | Priority | Flags | |----|-------|-----|----------|-------| | vp-beads-xxx | ... | 45d | P3 | stale, missing description |Suggest per-issue actions: close, reprioritize, merge with duplicate, refine scope, or leave as-is. No mutations without explicit per-item approval.
2. Reprioritize
Propose a priority reordering based on current sprint goals and blocking relationships.
Steps:
- Ask the user for current sprint goals if not obvious from conversation
context. Infer from recent commits and
bd list --status in_progressif the user does not state goals explicitly. - Run
bd list --status opento get all open issues with current priorities. - Run
bd blockedto identify blocked chains. Ifbd dep treeis available, use it to visualize blocking power — issues that unblock the most downstream work should rank higher. - Propose a reordered priority list with reasoning per change. Present as a diff: current priority → proposed priority, with a one-line rationale.
- User approves, edits, or rejects each proposed change.
- Run
bd update <id> --priority Nper approved change.
3. Suggest closures
Identify issues that are likely obsolete and propose closing them.
Steps:
- Run
bd list --status open, focusing on P3/P4 items and issues older than 60 days. - Cross-reference
git log --oneline -50with issue titles — useGrepto match issue keywords against commit messages. Find issues already addressed by commits but never formally closed. - Check
bd list --status closedfor issues that supersede open ones. - Run
bd stale --days 90for deeply stale items. - Classify each closure candidate:
- Addressed by commit: cite the commit
- Superseded: cite the replacement issue
- Out of scope: note the scope shift (user must confirm)
- Stale beyond recovery: >120 days, no activity, low priority
- Present candidates with rationale per item.
bd close <id> --reason "..."per approved closure.
See references/backlog-health-heuristics.md for closure criteria and
staleness thresholds.
Research Workflows
4. Investigate topic as spike
(formerly: investigate-topic)
Research a topic to inform future work — a timeboxed investigation that
reduces uncertainty before committing to a story or decision. When the
investigation is itself worth tracking in beads (e.g. multi-session research),
the result is a spike issue with ## Goal + ## Findings sections. When the
investigation immediately produces actionable items, hand off to workflow 5
(Create issues from findings) which will create the appropriate downstream
types (story, feature, task, decision, etc.).
Takes a topic from the user's request or the argument-hint.
Steps:
- Parse the user's topic. Classify: technology/library question, project refactor, or feature request. This guides the research tool mix.
- Basic Memory search first (non-negotiable). Call
mcp__basic-memory__search_notesfor the topic and related terms. For relevant matches, callmcp__basic-memory__read_noteto get full content — surface existing engineering notes, package notes, or upstream friction entries. If Basic Memory is unavailable, note the gap and proceed. - Check existing beads issues:
bd search <keywords>to find overlap with already-tracked work. - Scan the codebase: use Glob and Grep for existing code related to the topic. Understand the current state — what exists, what patterns are established.
- Check Raindrop bookmarks: call
mcp__raindrop__find_bookmarkswith topic keywords to surface previously bookmarked articles and resources. If relevant bookmarks are found, usemcp__raindrop__fetch_bookmark_contentto extract key insights. Skip silently if unavailable. - External research (if needed based on classification):
mcp__deepwiki__ask_questionfor package/framework architecture questionsmcp__tavily__tavily_searchfor broader implementation patternsmcp__tavily__tavily_extractfor deep-diving specific URLs found in search If external tools are unavailable, proceed with what is available.
- Synthesize into a concise brief: what exists now, what needs to change, key technical decisions, known pitfalls. Cap at 4-6 bullet points.
- Flag items that should become issues (hand off to workflow 5 (Create issues from findings)) or enrich an existing issue (hand off to workflow 6 (Enrich an existing issue)).
5. Create issues from findings
Turn research findings into structured beads issues. Takes output from workflow 4 (Investigate topic as spike) or user-provided findings.
Steps:
- Review the findings and identify discrete, actionable items. Each issue should be completable in roughly one session of focused work.
- Dedup check: run
bd search <keywords>for each proposed title against existing issues. Surface near-matches for the user to review. - Propose structured issues. For each:
- Title:
[Area] Action verb + subjectconvention - Type: pick from the nine core types —
task,bug,feature,chore,epic,decision,spike,story,milestone. See the Issue Types Reference above for the full table; consultreferences/backlog-health-heuristics.mdfor assignment logic - Priority: 0-4 with explicit reasoning
- Description: must include the type's required sections (e.g.
bugneeds## Steps to Reproduce+## Acceptance Criteria;spikeneeds## Goal+## Findings;decisionneeds## Decision+## Rationale+## Alternatives Considered). Thevalidation.on-create=errorgate will reject creates that miss these headings. Beyond required sections, follow the problem + why it matters- suggested first step pattern
- Title:
- If >3 related issues emerge from one topic: propose a tracking issue
(
bd create -t epic) as a group container, with child issues linked. Usemilestoneinstead ofepicif the parent represents a release boundary or set of work with no decomposition of its own. - If the investigation itself yielded enough output to warrant a record but
not yet enough to commit to downstream work, create a
spikecapturing## Goaland## Findingsrather than forcing prematurestoryorfeatureissues. - If >8 issues from one topic: suggest splitting into multiple research sessions rather than creating a sprawling epic.
- User approves, edits, or rejects each proposed issue before any
bd createcommand runs. Present the full list first, then confirm. - Run
bd create "title" -t <type> -p <priority> --description "..."per approved issue. The description string must include the literal required markdown headings for the chosen type. - Add dependencies where natural ordering exists:
bd dep add <child> <parent>. Common type-pair patterns:spike → story,spike → decision,story → task,epic ⊃ stories. - Report: created issue IDs, dependency graph, and suggested first issue to start (highest priority with no unsatisfied dependencies).
See references/backlog-health-heuristics.md for title conventions, description
templates, and creation limits.
6. Enrich an existing issue
Add research context to an existing issue that needs more information before work can begin.
Steps:
- User identifies the issue by ID or title. Run
bd show <id>to read the current state (title, description, status, priority, dependencies). - Research the topic using the same pipeline as workflow 4 (Investigate topic as spike): Basic Memory search → Raindrop bookmarks → codebase scan → external research (DeepWiki, Tavily) as needed.
- Draft an enriched description. Preserve the original description and append
a
## Research Contextsection with findings, relevant links, and suggested approach. - Show the draft to the user for approval before applying.
- Run
bd update <id> --description "..."with the enriched description after approval.
Guidelines
- User approval is non-negotiable. Every write operation (
bd create,bd close,bd update) must be explicitly approved per item. Present candidates first, confirm, then execute. Never auto-mutate. - Beads required (Tier B). Beads is available iff a
.beads/directory exists andcommand -v bdsucceeds; this component is Tier B per CLAUDE.md### Beads-availability convention. Backlog grooming operates on the beads backlog — with no beads there is no backlog to groom. Stop cleanly, naming the missing predicate, and redirect to a beadless alternative: for the planning / sprint triggers in this skill's description ("plan the sprint", "what should we work on", "break down into issues"), use/swarm-wave— it plans waves from aROADMAP.mdor a manual list — or editROADMAP.mddirectly. Do not attempt to groom aROADMAP.mdhere. - Basic Memory is opportunistic. Check for BM tool availability and skip silently if unavailable. BM enriches grooming with cross-project context but is not required for the core workflows.
- Infer from context. When the user asks to groom or research, read the conversation history for recent friction, decisions, and goals rather than starting a Q&A. The user should not have to re-explain context.
- Keep output scannable. Use tables for triage results, diffs for priority changes, numbered lists for issue proposals. Cap output at what fits in a conversation turn.
- Respect the priority vocabulary. Use the 0-4 numeric scale consistently: 0=critical, 1=high, 2=medium, 3=low, 4=backlog.