beads-writer

name	beads-writer
description	Use when creating or decomposing Beads issues for a project backlog, including new features, bugs, epics, backlog grooming, or converting vague asks into actionable Beads work in a Beads-backed repository.
metadata	{"owner":"tze","authors":["tze","OpenAI Codex"],"status":"active","last_reviewed":"2026-07-18"}
compatibility	Requires a Beads-backed repository with the `bd` CLI available. Assumes the agent can inspect the target project workspace before creating issues.

Beads Writer

Create high-quality beads issues through repo-grounded research and deliberate field selection. This skill is a routing layer over the Beads operating model described in ../../../../../README.md: issue writing should reinforce that workflow, not compete with it.

Every bead must be a self-contained handoff for a future independent session. Subbeads are not reminders; they must read like full standalone prompts, with enough context that a fresh session can execute them without the bead-creation chat.

Use This Skill When

• A user asks to create one or more beads issues for a feature, bug, task, or backlog item
• A user wants a vague ask decomposed into actionable beads or an epic with child beads
• A discovered issue needs a proper bead instead of a quick title-only stub
• A backlog-grooming pass needs better scope, dependencies, or acceptance criteria

Do Not Use This Skill When

• The work already exists as a well-formed bead and should now be implemented: use beads-worker
• The task is to review a whole repository or generate a roadmap from audit findings: use th-projects (project-review or project-direction subskills)
• The task is exhaustive spec-versus-code reconciliation rather than issue writing: use th-projects (project-review spec-reconciliation mode)

Core Rules

• Ground every bead in the target repo's actual code, naming, issue graph, and constraints before writing it.
• Prefer one bead per testable outcome. Split unrelated acceptance criteria.
• Apply the shared th-projects work-allocation contract before creating or decomposing implementation work.
• Keep epics focused: 3-7 children is usually the right range once overhead is counted.
• End every epic with a terminal reconciliation bead that depends on all implementation children.
• Use bd create, not bd q, when you need a real description.
• Do not pass dependency flags to bd create; create first, then wire with bd dep add.
• Stamp an execution-complexity label on every bead at creation: complexity:low, complexity:medium, complexity:high, or complexity:epic. The coordinator maps this label straight to a worker model tier (see ../beads-coordinator/references/runtime-and-safety.md) instead of re-deriving complexity per dispatch. Calibrate honestly: low is docs/config/test-only or single-file mechanical work with no design judgment; when in doubt between two tiers, pick the lower — the coordinator escalates on evidence.

Read Order

File	Read when	Content
references/workflow.md	Every real use of this skill	Research-first workflow, decomposition rules, creation sequence, and verification flow
../../../th-projects/references/work-allocation.md	Shaping implementation boundaries or dispatch packets	Cohesion threshold, additive rollout, structured dispatch readiness, and discovery triage
references/fields-and-examples.md	Crafting issue text or choosing fields	Field schema, type/priority guidance, and example beads
references/reconciliation-beads.md	Writing or checking an epic	Required reconciliation-bead contract, generation rules, and template
references/quality-checklist.md	Before finalizing or after creating beads	Final checklist, persistence checks, and anti-patterns

Trigger Sanity Check

• Should trigger: "Break this feature request into beads and make sure each child has enough context for a fresh worker."
• Should not trigger: "Implement bead bd-123 in its assigned worktree."

Resources

references/

• workflow.md — Primary execution flow for research, decomposition, creation, and verification.
• fields-and-examples.md — Field schema, type selection guide, priority calibration table, and exemplary beads.
• reconciliation-beads.md — Required reconciliation-bead template and generation rules for epics.
• quality-checklist.md — Final review checklist, persistence checks, and anti-patterns to remove.