create

Create Issue: $title

You are creating a new beads issue. Every issue must be self-contained — an agent picking it up in a fresh session should be able to implement it without asking clarifying questions.

Follow these steps exactly.

Step 1: Determine issue details

From the title and any provided context, determine:

• Type: task, bug, or feature. If unclear, ask the user.
• Priority: 0=critical, 1=high, 2=medium, 3=low, 4=backlog. Default to 2 if not specified. Use integers only.

Additional context provided: $context

Step 2: Write the description

The description is the what and why. It must answer:

• What needs to happen?
• Why does it need to happen? (business reason, user need, technical debt)
• What is the scope? (what's included and what's explicitly NOT included)

Keep it concise but complete. A few paragraphs max.

Step 3: Write acceptance criteria

Acceptance criteria are the definition of done. Each criterion must be:

• Specific and testable (not vague like "works correctly")
• Written as "Given X, when Y, then Z" or as a checklist item
• Cover the happy path AND relevant edge cases

Format as a markdown checklist:

- [ ] Given a logged-in doctor, when they view the patient list, then archived patients are hidden
- [ ] Given an admin, when they toggle the archive filter, then archived patients appear with a badge
- [ ] Edge case: empty state shows "no patients" message

Step 4: Write the design (if applicable)

The design is the how — implementation approach. Include:

• Which files/classes/models are involved
• Key technical decisions (new migration? new model? modify existing?)
• Any patterns to follow (reference existing code)

If the issue is simple enough that the implementation is obvious (e.g., a config change, a label fix), skip this field.

Step 5: Create the issue

Run a single bd create command with all fields populated:

bd create --title="$title" --type=<type> --priority=<priority> --description="<description>" --acceptance="<acceptance criteria>" --design="<design>" --add-label=needs-triage

Every new issue starts with needs-triage so it gets reviewed before anyone claims it.

Step 6: Confirm creation

Show the user:

• The issue ID that was created
• A brief summary of the fields you populated
• Remind them to run triage (/triage) or assign labels before an agent can pick it up

Rules

• Never cram everything into description. Description, acceptance criteria, and design are separate fields — use them.
• Never leave acceptance criteria empty. If you can't define "done", the issue isn't ready to be created.
• Embed full content in fields. Never reference file paths or "see above" — the issue must stand alone.
• One concern per issue. If the work has distinct parts, create multiple issues with parent-child relationships instead of one mega-issue.
• Use --json for bd commands whenever available.