Writing a bead

Somebody has asked for a bead.

What this skill is for, and what it is not

Interview until a designer or developer picking the bead up cold knows what the navigator wants and why, and need not ask them again. No design decisions, no file lists, no test plans: those are the producer's and the navigator's. Which field each thing goes in, P4, and the title rule are Writing a good bead in beads-workflow.

Before you ask anything: has this already been filed?

bd dolt pull
bd search "<the strongest noun of the request>"
bd search "<a second noun>"

Two or three nouns, one search each. Closed beads are included on purpose. --desc-contains only narrows the query, so it cannot search descriptions alone.

Show what comes back. If anything is close, ask whether to file new, add to it, or drop it. If nothing comes back, say nothing.

The interview

Three things, and the bead is not describable until you have them all:

1. What the outcome is. What improves for the user or the developer?
2. What done looks like from the outside. Observable, not internal — this becomes the acceptance line.
3. Whether the change touches anything a person sees or presses.

Ask through the question tool, up to four questions per round, each round chosen from what the last one answered. There is no cap on rounds: keep going until you can describe the work.

The third is not a design question: record the answer and design nothing. A yes is the line A person sees this: yes under ## Scope, so that Cerebro's understand step sees it answered and asks nothing; a no is the label ux:none at filing (below), the navigator's word that there is no experience to agree and the one thing that lets a bead reach a producer without a UX session. The rule of who may add it is one row of the routing table in beads-workflow, invisible by declaration: the filing interview, wherever it happens, Forge and Sage; never a bugfix bead; and a producer that finds otherwise sends the bead to UX, removing it.

When you have all three, file the bead without asking for approval.

Filing it

Write the description to a file first. It opens with ## Outcome — the first of the three things, in the navigator's words — so that the verifier can quote it back when the work is done and ask whether the problem was solved, not only whether the acceptance was met:

## Outcome
<what improves, and for whom>

## Scope
<what is in, what is out; a yes to the third question is recorded here>

Then:

bd create "<the title>" --type task -p 4 --body-file /tmp/bead-body.md \
  --acceptance "<what done looks like, in the navigator's own terms>" \
  --labels ux:none      # only when the answer to the third question was no, and never on a bug
bd dolt push

Two commands, not a chain: a && whose first half fails quietly leaves a bead no other machine can see. The flags follow Writing a good bead in beads-workflow. Report the id and the title.

If the request is a defect to be fixed (wrong behaviour, regression, breakage), file it as --type bug and add the bugfix label at creation time. bugfix is the routing label that sends the bead to the bugfixer flow instead of UX → producer.

Offering the ranking, once

After filing, ask once how to rank it, through Ranking the backlog in agents/orchestrator.md — that pass, not one of your own. Its first step, understanding the bead, is already done by this interview, so go straight to its second: the summary and the priority. That pass also loads this skill for a bead that arrived without the interview, and for a split. If they decline, say it goes to the next ranking pass and stop. Invoked by hand outside a Cerebro session there is no pass: say it goes to the next one and stop.

When the navigator says "just file it"

Honour it: skip the interview, write the bead from what they said, and name in your report which of the three things went unanswered, so Cerebro's understand step knows to ask. The duplicate search still runs.

When one request is several beads

Name the pieces you heard and ask whether to file one bead or several, before interviewing. Never split silently, and never file only the first.

If several, the request is an epic with children, filed as one family in one session, so that nobody has to decompose it later by hand:

1. Interview the pieces one at a time, the same three things each (the first two only for a bug: its route never enters UX); a piece is a child when a producer, or the bugfixer, could deliver it on its own and a person could tell it landed.

2. File the parent first, then each child under it. Every one at P4; a child takes its parent's priority when the parent is ranked (Dependencies and breakdown in beads-workflow), and the navigator is asked about the parent only.

   bd create "<the outcome, as a whole>" --type epic -p 4 --body-file /tmp/epic-body.md
   bd create "<one child>" --type task -p 4 --parent <epic-id> --body-file /tmp/child-1.md \
     --acceptance "<what done looks like for this piece>" \
     --external-ref <the parent's, if it came from an issue> \
     --labels ux:none      # only when this child's answer to the third question was no
   bd dep add <later-child> <earlier-child>     # only where the navigator said the order matters
   bd dolt push

   Splitting a bead that already exists starts with bd update <id> --type epic: only an epic with children is bookkeeping to the queues (scripts/work-beads), so a task given children and left a task is offered to UX and producers as if whole. A child of an issue-born bead carries the parent's external_ref so Moira can follow the family. A child of a bugfix bead is filed --type bug --labels bugfix and never ux:none: the pieces of a bug are bugs, on the bugfixer's route, and the parent keeps bugfix as it becomes an epic.

   A guessed edge makes bd ready lie, so an edge is the navigator's word, never your inference. Each child routes on its own from here: UX, a producer when ux:none, or the bugfixer when bugfix. The parent is bookkeeping while it has children and is closed by whoever closes the last one.

3. Report the family: the parent id and title, then each child on its own line.

Never split a bead that is already ux:agreed or claimed: that work has left the interview, and a change to it goes through the navigator and the role that holds it.

What you never do

• Never decide a design, a file layout or a test plan.
• Never set a priority the navigator did not choose. Every bead is filed at P4, unranked.
• Never plan the bead you just filed.