aspiers/ai-config / .agents/skills/beads-blocker-review
beads-blocker-review
VerifiedReview every Beads issue waiting on a person, one at a time, using the interactive questionnaire UI rather than plain-text prompts. Use when asked to go through blockers, clear the human queue, answer beads waiting on the user, triage `bd human list`, or unblock agent work that needs a decision.
Beads Blocker Review
Clear the queue of Beads issues waiting on a person, one at a time, asking each question through the interactive questionnaire tool.
When to Use This Skill
Use this skill when the user asks to:
- Go through blockers, or clear the human queue
- Answer beads that are waiting on them
- Triage
bd human list - Unblock agent work that stalled on a decision
What Is In the Queue
Two mechanisms park work on a person, and they do not overlap. Check both.
- Beads labelled
human— listed bybd human list. This is the raw inventory, not the actionable queue: a human bead can itself be waiting on unfinished agent work. The bundled helper intersects it withbd readyso only decisions whose prerequisites are complete are asked. - Open human gates —
bd gate listshows open gates; the human ones are those of typehuman, which resolve only by hand. A gate blocks another bead until someone resolves it. Gates do not carry thehumanlabel, so they never appear inbd human list; checking only the first queue misses them silently.
Do not widen the sweep to bd blocked. Ordinary dependency blockers are
agent-resolvable work, not questions for the user.
Record the Answer, Don't Do the Work
Recording the user's answer is the whole job. For each blocker: ask, record, move on.
Do not implement what the answer implies, even when the change looks small. The user invoked this to drain a decision queue in one pass, and stopping to write code after every answer defeats that.
This works because a bead waiting on a person contains only their part — the dependent agent work lives in its own bead. Answering releases that work to be picked up later, by a grind or by you in a separate session.
If you meet a bead that mixes the two — the person's part and agent work in one issue — say so when you report. It should have been split, and answering it will close work nobody did.
This boundary covers only work the answers imply. It does not suspend
duties that other loaded rules make automatic, such as regenerating a
stale working mixdown you notice along the way: do those once the
queue is done, as you would in any other turn.
Workflow
-
Inventory both queues freshly.
Resolve the bundled
scripts/list-actionable-human-beads.pyrelative to thisSKILL.md, run it, then run:bd gate list --limit=0 --jsonThe helper returns
actionablehuman beads that also appear in Beads' authoritativebd readyresult, pluswaitinghuman beads whose prerequisites are incomplete. Never prompt an item fromwaiting. Usebd show "$id" --jsonfor each waiting bead to identify and report its unfinished blocking prerequisites without asking the user anything.If
actionableand the human-gate queue are both empty, report anywaitingbeads separately and stop. Do not go hunting for other work. -
Report the actionable total up front so the user knows how many questions are coming — e.g. "7 beads and 1 gate are ready for you; 2 more human beads are waiting on agent prerequisites."
-
For each actionable item, in priority order (P0 first), repeat steps 4-7.
-
Read it fully, including comments — the question is often in a comment rather than the description:
bd show "$id" bd comments "$id"Also note what depends on it, so you can tell the user what their answer will release. Note the direction:
upshows what this bead blocks, which is what you want here — the defaultdownshows the opposite.bd dep tree "$id" --direction=up -
Summarise the decision in a few lines before asking: what the bead is, why it is waiting, and what turns on the answer. Always name a bead as
<id> (<title>), never by bare ID. When thebeads-linksskill is available, link the ID too, so the user can open the bead before answering; see that skill for the forms. -
Ask using the questionnaire tool, one bead per call:
- Claude Code:
AskUserQuestion - OpenCode: the interactive questionnaire tool
- Pi:
ask_user
Derive the options from the bead itself — its "Alternatives Considered" section, the comment posing the question, or the genuine choices the work presents. Give 2-4 concrete, mutually exclusive options with descriptions that state the consequence of picking each. If you have a recommendation, make it the first option and append "(Recommended)" to its label.
A bead's options were written when it was filed, possibly before decisions or rules now in force. Before recommending one, check it against the code it touches and the rules loaded now. If it adds a new file, format or setting for values the existing structure can already hold, recommend the smaller option and say why.
Never batch several beads into one call. One bead, one call — that is what makes the review legible.
If a question is genuinely open-ended (naming, free-form text), ask in prose for that one bead. Think hard before concluding it is open-ended; most "open" questions have 2-4 obvious candidates.
- Claude Code:
-
Record the answer immediately, before moving on.
For a labelled bead:
bd human respond "$id" --response "<the decision, plus rationale>"This adds the response as a comment and closes the bead with reason "Responded", which releases anything that depended on it. The
humanlabel stays attached — that is deliberate, andbd human statsreads it.If the answer makes the bead moot rather than deciding it:
bd human dismiss "$id" --reason "<why it no longer applies>"For a gate, resolve it instead:
bd gate resolve "$gate-id" --reason "<the decision>"Write the response so a reader six months from now understands it without this conversation: the decision, the reason, and the rejected option.
-
Summarise at the end: how many were answered, dismissed, or skipped; which beads are now unblocked and ready for agent work; and any follow-up work the answers created.
Name the released beads specifically, linked as in step 5. The user wants to know what their answers freed up, not just that the queue is empty.
Released or unclaimed agent beads are findings, not your next step, unless picking them up is work this session was given. Say who picks them up, such as the coordinator, or leave that to the user.
Handling Interruption
The user may bail out partway through, or answer with something that changes the rest of the queue. Both are fine.
Because each answer is recorded before the next question is asked, stopping early loses nothing. If the user stops, summarise what was cleared and what remains, and do not press on.
If an answer to one bead obviously settles a later one, still ask about the later bead — but say what the earlier answer implies and offer that as the first option.
Rules
- Never answer on the user's behalf. Do not call
bd human respond,bd human dismiss, orbd gate resolvewith a decision you invented. If you cannot construct sensible options, ask in prose rather than guessing. - Never skip an item silently. Report prerequisite-blocked human beads as
waiting, without prompting them. If an actionable item cannot be asked about, say why. - Verify before recording. Only record what the user actually chose, including any free text they added to their selection.
- Re-read both queues if the session is long. Run the helper again rather than reusing its output: closing the final prerequisite must make a human bead actionable on the next fresh read. Items can be added or closed while the review runs; check again before declaring the queues empty.
Verification
Run the bundled scripts/list-actionable-human-beads.py again, resolving it
relative to this SKILL.md, then run:
bd gate list --limit=0 --json # no open human gates left
bd human stats # responded and dismissed counts
bd ready # work released by the answers
The final helper output should have an empty actionable list. A non-empty
waiting list is not an unanswered human queue; report which agent
prerequisites still prevent those questions from being asked.
Related Skills
beads-best-practices— how beads reach this queue, and the one-bead-one-doer rule that keeps them answerablebeads-grinding— the serial grind that fills this queue and consumes the work it releasesbeads— general Beads workflow
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |