/create-ticket

Create a single well-structured bead that meets the project’s Definition of Ready — the four Power Sections, an effort estimate, a priority, and a safety class — without you having to remember the shape from memory.

The model: GitHub Issues are the inbox

GitHub Issues are the public intake layer — the inbox where feature requests, bug reports, and external contributions arrive. They are not the working queue.

Once an issue is actionable, grooming imports it into the beads tracker as a bead via bd create --external-ref gh-<N>. The original GitHub issue is then closed with a pointer comment (e.g. Tracked as bead <id> — closing the inbox item). From that point the bead is the source of truth: it carries the 4 Power Sections, the safety class, and the dependency graph. GitHub Issues carry only the provenance trail.

For work that starts inside the repository — an idea, a follow-up, an internal task — skip the GitHub-Issue step and create the bead directly.

When to use it

Use this when a feature request, bug report, or work item is ready to become a bead. The command walks you through a guided workflow: it asks clarifying questions about the change, reads docs/TECHNICAL-ARCHITECTURE.md and docs/PRODUCT-REQUIREMENTS.md to pre-fill the Environment Context and Guardrails sections, searches existing beads to catch duplicates, drafts a bead against the canonical format, and only then creates it. The output is a bead that /groom-backlog can refine and that /work-ticket can claim without further ceremony.

Use this for single beads you’ve decided to create. For deciding whether a feature is worth building at all, run /evaluate-feature first — that command produces a BUILD verdict that hands off to this one. For batch prioritization across the whole backlog, use /groom-backlog.

Don’t bypass this for “small” changes that lack the ceremony of a linked bead — that’s what /quick-fix is for. The split is intentional: beads carry context that survives across sessions; quick fixes are the lightweight path when there’s nothing worth carrying.

How it fits

Sources are a GitHub Issue from the inbox, a direct internal request, or a BUILD verdict from /evaluate-feature. Output is an open bead in the backlog, which bd ready surfaces once grooming completes Definition-of-Ready.

What it does (quick)

• Verifies gh CLI auth, repo access, and beads tracker availability (pre-flight)
• Asks clarifying questions about the change to populate sections A–D
• Reads docs/TECHNICAL-ARCHITECTURE.md and docs/PRODUCT-REQUIREMENTS.md to pre-fill Environment Context and Guardrails
• Searches existing beads to surface duplicates before creating (bd list --json + text match, or bd search "<terms>")
• Drafts the bead per docs/TICKET-FORMAT.md (4 Power Sections, effort estimate, priority, safety class)
• Self-checks the draft against the format before showing it to you
• Creates the bead (bd create) with type, priority, and labels
• If the bead originates from a GitHub Issue: records --external-ref gh-<N>, then closes the GitHub Issue with a pointer comment

Related commands

• /evaluate-feature — upstream; a BUILD verdict feeds directly into this command
• /groom-backlog — downstream; the natural next gate that completes DoR so the bead surfaces via bd ready
• /quick-fix — the lightweight alternative for changes too small for bead ceremony

Canonical spec: .claude/commands/create-ticket.md