--- name: bead-authoring description: Single-bead lifecycle playbook — authoring worked examples (bd create with description/ACs/non-goals), dedupe search, validation mechanics (bd lint / --dry-run), wisps, JIT verification on pickup, progress notes, self-review before close, close-reason format with examples, and the bd remember when/when-not manual. Trigger phrases: "bead authoring", "write this bead", "draft the bd create", "picking up a bead", "close this bead", "close reason", "should I remember this". --- # Bead Authoring The procedure for the single-bead lifecycle: writing a bead worth picking up cold, verifying it on pickup, and closing it with evidence. The always-on rules state the law — the `beads-quality` rule owns the authoring standards (self-containment, What/Where/How/Why, AC-by-type), the `bead-completion` rule owns the close-side law (AC ownership, evidence policy, the do-not-defer invariant, the memory litmus test). This skill is how you meet them. The B-IDs below are shared with the split's obligations checklist in the kit repo. This skill reads no overlay keys — the procedure is identical in every project. ## When to Use This Skill - Creating a bead and you want the worked example, validation mechanics, or wisp mechanics - Picking up a bead (the JIT-verification question list) - Closing a bead (the self-review pass, close-reason format and examples) - Deciding whether to `bd remember` after a close **Skip when:** the concern is graph or epic management — dependency wiring, `--graph`, epic steering in a 3+-bead breakdown belong to `skills/graph-planning` (per-bead authoring within a multi-bead breakdown still uses Phases 1–3 here). Test discipline by bead type is the `pragmatic-tdd` rule + its skill. ## Core Process ### Phase 1 — Before creating: dedupe search (B1) Check that the work doesn't already have a bead (the `beads-quality` rule's anti-pattern 4 is the law here): ```bash bd search "loading indicator" # text search for related beads bd list --status=open # scan open beads for overlap ``` If a related bead exists, consider: should this be a child of that bead (`--parent`), a dependency (`bd dep add`), or an update to the existing bead's description? **When to skip the search:** if the beads DB isn't running (cold start, broken redirect) or you're creating the first beads on a new project, proceed without search and run `bd doctor` afterward (embedded-mode substitutes per the `session-lifecycle` rule § Extended close). ### Phase 2 — Author the bead (B2) Apply the `beads-quality` rule's standards: What/Where/How/Why description, ACs as observable outcomes, a Non-goals line. Worked example: ```bash # BAD — no ACs, no non-goals, description restates title bd create "Fix loading state" -t bug -p 1 # GOOD — self-contained with ACs and non-goals bd create "Add loading indicators to beads-ui tab switching" \ --description="When switching tabs in beads-ui, the UI shows 'No issues' while data loads — indistinguishable from an empty workspace. Track subscription state in subscription-issue-store. Render spinner while loading. Files: src/client/subscription-issue-store.js, src/client/views/*.js. Non-goals: not changing the subscription protocol or server-side caching in this bead." \ --acceptance="Switching to an unloaded tab shows a loading indicator, not 'No issues'. Tab with zero real issues still shows 'No issues' after load completes. Loading indicator disappears within 1s of data arriving." \ -t feature -p 1 ``` ### Phase 3 — Validate (B3) - `bd create --dry-run` to preview before creating - `bd lint` to check open beads for missing required sections - `bd config set validation.on-create warn` enables auto-validation at creation time ### Phase 4 — Structure: hierarchy and wisps (B4) **Parent-child and dependency-graph mechanics** (`--parent`, hierarchical IDs, `bd dep add` vs containment, `bd create --graph`) are owned by `skills/graph-planning` Phase 2. **Ephemeral issues (wisps):** use `--ephemeral` for short-lived tracking that doesn't warrant permanent storage — agent heartbeats, exploratory investigation notes, temporary coordination signals. Wisps are subject to TTL compaction and excluded from exports. To promote a wisp to a permanent bead: `bd promote --reason "..."`. ### Phase 5 — Pick up: JIT verification (B5) Before writing any code, check what you're working on (`bd show --current`) and verify the bead's description against reality: - Do the files and paths mentioned still exist? - Do the APIs, interfaces, or patterns described still match the current codebase? - Has anything changed since the bead was created that affects the approach? If reality doesn't match: update the implementation approach, note the discrepancy, and proceed. **Never modify the acceptance criteria** — ownership and escalation are the `bead-completion` rule's § AC ownership law. ### Phase 6 — During work: progress tracking (B6) Use `bd note "progress update"` to append implementation notes to the bead's notes field (persistent, visible in `bd show`). Use `bd comment "observation"` for timestamped discussion entries. Notes record decisions; comments record conversation. This keeps context attached to the work item rather than only in the scratchpad. ### Phase 7 — Close: self-review, then evidence (B7, B8) **Self-review pass (B7)** — the same agent that did the work, not a separate reviewer; a deliberate pause to check the work against the spec: 1. Re-read each acceptance criterion from the bead (`bd show `) 2. For each AC, verify it is satisfied by the code as written 3. If any AC is not met, fix it or escalate — do not declare done **Close reason (B8)** — evidence mapped to ACs, with a commit hash, branch name, or PR URL (the policy, per-type table, and do-not-defer invariant are the `bead-completion` rule's law): ```bash # BAD — vague bd close gastown-abc --reason "Done" # GOOD — evidence mapped to ACs bd close gastown-abc --reason "Commit a1b2c3f on feature/loading-ux. AC1: spinner renders on tab switch (verified manually). AC2: empty state shows after load (test_empty_tab passes). AC3: spinner gone <1s (verified manually)." ``` Continuation flags: `bd close ... --suggest-next` (show newly unblocked issues) or `--claim-next` (auto-claim the next highest-priority ready issue). ### Phase 8 — After close: knowledge capture (B9) The `bead-completion` rule owns the litmus test; this phase is the manual for applying it. ```bash bd remember "AccountService.sync silently skips soft-deleted records — \ the WHERE clause in account_repo.rb:47 filters them with no error" \ --key account-sync-soft-deletes ``` **When to remember:** - A fix that required non-obvious investigation (the root cause wasn't where you first looked) - A codebase pattern not apparent from reading the code ("module X is called by a background job, not the controller") - A corrected assumption — something you got wrong that cost investigation time - A library/config quirk or environment-specific behavior not in docs - A misleading error message where the real cause was different from what the error suggested **When NOT to remember:** - Task-specific progress notes (that's the scratchpad) - Anything already codified in the project's agent rules - Obvious facts derivable from the code or docs - Temporary workarounds (create a follow-up bead instead) - Performance numbers or benchmarks (too volatile) - Speculative improvements ("this could be refactored to use X") **Key discipline:** - Always use `--key` with a descriptive kebab-case identifier (`-`) — enables deduplication and future pruning; never rely on auto-generated keys from content - Check before creating: `bd memories ` to search for existing memories on the topic; update with `bd remember --key "corrected info"` rather than creating a parallel entry - One memory per bead, max — capturing more than two means the bead was too large or you're recording progress notes Staleness handling (a memory contradicts the codebase) is the `bead-completion` rule's law.