| name | groom-beads |
| description | Interactive grooming session that takes raw beads (bd) issues or epics and turns them into self-contained, ship-ready work contracts — then emits a ready-to-paste /goal condition for executing them in a later session. Use whenever the user wants to groom, refine, scope, or prep beads issues ("groom abc-42", "grooming session", "make these ready to pick", "prep this epic", "let's scope the backlog", "get these issues ready for /goal"), or wants to turn vague backlog items into something an autonomous session can ship. Run this in an interactive chat — ideally on the strongest available model — NOT inside an autonomous/goal run.
|
Groom beads issues
Turn raw beads issues into contracts a different, context-free session can
ship autonomously. That future session (see the ship-beads skill) will have
nothing but the bead and the repo — no memory of this conversation. Everything
that matters must therefore land on the bead itself, and the finish line
must be verifiable by a goal-mode evaluator that can only read a transcript.
This is a thinking-partner session, not a form-filling exercise. The model
doing the grooming carries the reasoning load — challenge scope, propose
splits, spot missing constraints — which is why grooming runs interactively on
a strong model while implementation is later delegated to cheaper ones.
Phase 0 — intake and homework (before asking anything)
- Resolve the targets: ids from the user's message, else propose candidates
from
bd ready --sort priority / bd list --status open --pretty. For an
epic, bd show <id> and enumerate its children.
- Read each bead fully:
bd show <id> --json (description, design,
acceptance, notes, deps, labels).
- Explore the codebase before asking questions. Read the files the issue
touches, the tests that cover them, the repo's CLAUDE.md verify commands.
A question the code can answer is wasted user time; codebase exploration
also surfaces contradictions worth grilling ("the issue says X but the code
already does Y — what's actually wanted?").
Phase 1 — grill, one question at a time
Invoke the grill-with-docs skill (Skill tool) and run the interview by its
rules — one question per turn, always with your recommended answer, explore
the codebase instead of asking when the code can answer, challenge terms
against the existing glossary. Don't re-implement the interview style from
memory; that skill is its canonical home.
One precedence rule on top of it, because this session has two write-back
targets: the bead is the executor's contract and always gets the outcome
(Phase 2 below); CONTEXT.md and ADRs are the durable record and get updated
per grill-with-docs on top — glossary entries when a term is sharpened, an
ADR only when its three tests pass (hard to reverse, surprising without
context, real trade-off). A bead's design field disappears from view when
the bead closes; a decision that should outlive the issue belongs in the
docs, and the bead's design field should then just reference it.
Push back where the issue is vague, over-broad, or contradicts the code —
capitulating to save time now costs a failed autonomous run later.
Cover, per issue (skip what the bead already answers):
- Problem & why now — what breaks/hurts today; how we know it's fixed.
- Scope in / scope out — name what is explicitly NOT in this issue.
Scope-out lines prevent an autonomous session from wandering.
- Acceptance criteria — observable behaviors, each one checkable by a
command or a concrete manual step. "Works offline" is not checkable;
"airplane mode → profile screen renders cached data read-only" is.
- Verification plan — the exact local commands the executor will run and
watch fail→pass. If no local check exists, design one here (a test to
write first, a stand-in for a cloud dependency). An issue with no local
feedback loop is not groomable — the executor would ship on vibes.
- Design constraints — approach, files involved, patterns to follow,
things that must not change. Capture real trade-off decisions in a line or
two ("chose X over Y because Z") so the executor doesn't relitigate them.
- Edge cases — probe with concrete scenarios ("two members split ₹61
three ways — who eats the paisa?") until boundaries are precise.
- Size — if honest scoping reveals multiple independent shippable slices,
split:
bd create children under the epic (abc-42.1 style), each groomed
to this same standard, and wire ordering with bd dep add.
Phase 2 — write back as decisions crystallize (not batched)
After each resolved thread, update the bead immediately:
bd update <id> --description "…" — problem, scope in/out. The bead must
read as self-contained: assume the reader has zero context.bd update <id> --design "…" — approach, key files (path:line refs),
constraints, decided trade-offs.bd update <id> --acceptance "…" — the numbered, checkable criteria.bd dep add <issue> <blocker> — ordering between siblings.
Long text: write to a temp file and use --body-file / --design-file where
supported; never fight shell quoting inline.
Phase 3 — emit the goal condition and mark groomed
For each groomed issue (or a small sequenced batch), write a /goal condition
following references/goal-conditions.md — read that file now if you haven't.
Shape:
Ship bead <id> via the ship-beads skill (bd show <id> has full scope/design/acceptance).
DONE = <measurable end state, e.g. PR opened + checks green + bd shows closed>.
PROVE IT = <exact commands whose FRESH output must be printed in the transcript>.
CONSTRAINTS = <anti-gaming lines: don't weaken/delete tests, no skips,
acceptance criteria in bd show <id> all demonstrably met, re-run checks as
the final action>.
Keep it under 4000 chars — the how/why lives on the bead (bd show <id> is
the executor's briefing file; that beats a temp file because it survives
across sessions and machines). Then:
bd update <id> --notes "<the goal condition>" — stored with the issue.bd label add <id> groomed — status stays open so bd ready still
surfaces it; the label is the "ready to pick" marker (beads has no native
groomed status — built-ins are open/in_progress/blocked/deferred/closed/
pinned/hooked).- Print the condition in the chat for copy-paste into
/goal next session.
Session close
Summarize: which beads are now groomed, their dependency order, and the
exact /goal line(s) to fire. Then follow the repo's own session-close rules
(export/commit/push of .beads/issues.jsonl per that repo's CLAUDE.md).
