backlog-groomer

Backlog 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:

1. Run bd list --status open and bd list --status in_progress to get the full picture. Run bd stats for summary counts.

2. Run bd stale --days 60 to flag aging issues. Separately flag in_progress issues stale >30 days as "stalled."

3. Run bd duplicates to detect content-hash matches (if available; if not, use bd search with keywords from suspicious titles for near-matches).

4. Run bd find-duplicates (alias find-dups) to surface near-duplicates that bd duplicates misses. Two-stage similarity architecture:

   • Mechanical Jaccard tokenization is the default (--method=mechanical, threshold 0.5). Free, fast, pre-filters AI calls. Drop to --threshold=0.4 for more recall when the backlog is small.
   • AI semantic comparison is opt-in (--method=ai). Requires ai.api_key config and bills per call (mechanical pre-filter limits spend). Only invoke when the user explicitly requests it or BD_AI_DUPES=1 is 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) or bd duplicate <loser> <winner> (marks duplicate without closing). Apply only with explicit per-pair user approval.

5. Run bd blocked to identify issues stuck on unresolved dependencies.

6. Cross-reference with UPSTREAM-*.md and SYNERGY-*.md files if they exist (use Glob to find them). Note any UPSTREAM friction or SYNERGY extraction candidates that should have a corresponding beads issue.

7. If Basic Memory MCP tools are available, call mcp__basic-memory__search_notes for key dependencies from package.json to surface known friction not yet in the backlog. Skip silently if unavailable.

8. Present a structured triage table:

   | ID | Title | Age | Priority | Flags |
   |----|-------|-----|----------|-------|
   | vp-beads-xxx | ... | 45d | P3 | stale, missing description |
   

9. 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:

1. Ask the user for current sprint goals if not obvious from conversation context. Infer from recent commits and bd list --status in_progress if the user does not state goals explicitly.
2. Run bd list --status open to get all open issues with current priorities.
3. Run bd blocked to identify blocked chains. If bd dep tree is available, use it to visualize blocking power — issues that unblock the most downstream work should rank higher.
4. Propose a reordered priority list with reasoning per change. Present as a diff: current priority → proposed priority, with a one-line rationale.
5. User approves, edits, or rejects each proposed change.
6. Run bd update <id> --priority N per approved change.

3. Suggest closures

Identify issues that are likely obsolete and propose closing them.

Steps:

1. Run bd list --status open, focusing on P3/P4 items and issues older than 60 days.
2. Cross-reference git log --oneline -50 with issue titles — use Grep to match issue keywords against commit messages. Find issues already addressed by commits but never formally closed.
3. Check bd list --status closed for issues that supersede open ones.
4. Run bd stale --days 90 for deeply stale items.
5. 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
6. Present candidates with rationale per item.
7. 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:

1. Parse the user's topic. Classify: technology/library question, project refactor, or feature request. This guides the research tool mix.
2. Basic Memory search first (non-negotiable). Call mcp__basic-memory__search_notes for the topic and related terms. For relevant matches, call mcp__basic-memory__read_note to get full content — surface existing engineering notes, package notes, or upstream friction entries. If Basic Memory is unavailable, note the gap and proceed.
3. Check existing beads issues: bd search <keywords> to find overlap with already-tracked work.
4. Scan the codebase: use Glob and Grep for existing code related to the topic. Understand the current state — what exists, what patterns are established.
5. Check Raindrop bookmarks: call mcp__raindrop__find_bookmarks with topic keywords to surface previously bookmarked articles and resources. If relevant bookmarks are found, use mcp__raindrop__fetch_bookmark_content to extract key insights. Skip silently if unavailable.
6. External research (if needed based on classification):
   • mcp__deepwiki__ask_question for package/framework architecture questions
   • mcp__tavily__tavily_search for broader implementation patterns
   • mcp__tavily__tavily_extract for deep-diving specific URLs found in search If external tools are unavailable, proceed with what is available.
7. Synthesize into a concise brief: what exists now, what needs to change, key technical decisions, known pitfalls. Cap at 4-6 bullet points.
8. 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:

1. Review the findings and identify discrete, actionable items. Each issue should be completable in roughly one session of focused work.
2. Dedup check: run bd search <keywords> for each proposed title against existing issues. Surface near-matches for the user to review.
3. Propose structured issues. For each:
   • Title: [Area] Action verb + subject convention
   • 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; consult references/backlog-health-heuristics.md for assignment logic
   • Priority: 0-4 with explicit reasoning
   • Description: must include the type's required sections (e.g. bug needs ## Steps to Reproduce + ## Acceptance Criteria; spike needs ## Goal + ## Findings; decision needs ## Decision + ## Rationale + ## Alternatives Considered). The validation.on-create=error gate will reject creates that miss these headings. Beyond required sections, follow the problem + why it matters
     • suggested first step pattern
4. If >3 related issues emerge from one topic: propose a tracking issue (bd create -t epic) as a group container, with child issues linked. Use milestone instead of epic if the parent represents a release boundary or set of work with no decomposition of its own.
5. If the investigation itself yielded enough output to warrant a record but not yet enough to commit to downstream work, create a spike capturing ## Goal and ## Findings rather than forcing premature story or feature issues.
6. If >8 issues from one topic: suggest splitting into multiple research sessions rather than creating a sprawling epic.
7. User approves, edits, or rejects each proposed issue before any bd create command runs. Present the full list first, then confirm.
8. 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.
9. Add dependencies where natural ordering exists: bd dep add <child> <parent>. Common type-pair patterns: spike → story, spike → decision, story → task, epic ⊃ stories.
10. 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:

1. User identifies the issue by ID or title. Run bd show <id> to read the current state (title, description, status, priority, dependencies).
2. 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.
3. Draft an enriched description. Preserve the original description and append a ## Research Context section with findings, relevant links, and suggested approach.
4. Show the draft to the user for approval before applying.
5. 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 and command -v bd succeeds; 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 a ROADMAP.md or a manual list — or edit ROADMAP.md directly. Do not attempt to groom a ROADMAP.md here.
• 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.