create-issues-skill

SKILL.md

name	create-issues
description	Create issues for the Beads issue tracker. Iteratively gathers requirements through clarifying questions, then creates well-structured issues. Triggers on: create an issue, write issue for, plan a feature, requirements for, spec out, file a bug.

Beads Issue Creator

Create well-structured issues for the Beads issue tracker through iterative requirements gathering.

---

Overview

This skill helps you create actionable issues that AI agents can execute autonomously. It:

1. Gathers context through targeted questions
2. Structures requirements into discrete, executable tasks
3. Creates issues directly in the Beads tracker with proper dependencies

Output: Beads issues ready for agent execution, NOT just documentation.

---

Workflow

[User Request] → [Gather Context] → [Clarify Requirements] → [Create Beads Issues]
     ↓                  ↓                    ↓                       ↓
  Feature idea    Project detection    3-5 Q&A rounds         Epic + tasks
  Bug report      Quality gates        Scope boundaries       with deps

---

Phase 1: Project Context Detection

Before asking questions, attempt to detect pertinent project context:

1. Check for justfile - Run just --list to see available recipes
2. Check pyproject.toml/package.json - Identify build/test commands
3. Check existing patterns - Look at recent beads issues with mcp__beads__list

Use this to pre-populate quality gate suggestions.

---

Phase 2: Clarifying Questions (Iterative)

Ask questions one set at a time. Each answer informs the next questions.

Question Categories

Category	Purpose	Example
Problem/Goal	Why does this need to exist?	"What pain point does this solve?"
Core Functionality	What must it do?	"What are the key actions?"
Scope/Boundaries	What should it NOT do?	"What's explicitly out of scope?"
Success Criteria	How do we verify completion?	"What proves it works?"
Priority	How urgent is this?	"Blocking, high, normal, or low?"
Dependencies	What must exist first?	"Does this depend on other work?"

Question Format

Use numbered questions with lettered options for quick responses:

1. What is the primary goal?
   A. Fix broken functionality (bug)
   B. Add new capability (feature)
   C. Improve existing behavior (enhancement)
   D. Other: [please specify]

2. What priority level?
   A. Critical - blocking other work (P0)
   B. High - needed soon (P1)
   C. Normal - standard priority (P2)
   D. Low - nice to have (P3)

Users can respond with "1B, 2C" for quick iteration.

Quality Gates (REQUIRED)

Always ask about quality gates. Use detected project context to suggest options:

For Python projects (detected justfile/pyproject.toml):

What quality commands must pass?
   A. just format && just check (Recommended)
   B. just lint && just typecheck
   C. pytest only
   D. Other: [specify]

For Node projects (detected package.json):

What quality commands must pass?
   A. pnpm typecheck && pnpm lint
   B. npm run test
   C. bun run check
   D. Other: [specify]

Adaptive Flow

After each response:

• Ambiguity detected → Ask follow-up questions
• Scope creep risk → Clarify boundaries explicitly
• Clear understanding → Move to issue creation
• Complex feature → Suggest breaking into epic + subtasks

Typically 3-5 rounds are needed. Stop when you can write specific acceptance criteria.

---

Phase 3: Issue Structure

Structure requirements into one of these patterns:

Pattern A: Single Issue (simple bugs/tasks)

For focused work that can complete in one session:

issue_type: bug | task | chore
title: Clear, actionable title (imperative verb)
description: |
  ## Problem
  What's wrong or missing

  ## Solution
  What to implement
priority: 0-4 based on user input
acceptance: |
  - [ ] Specific verifiable criterion
  - [ ] Another criterion
  - [ ] Quality gates pass: `just format && just check`

Pattern B: Epic + Subtasks (features/large work)

For work spanning multiple sessions or files:

# Parent Epic
issue_type: epic
title: Feature name
description: Overview and goals

# Child Tasks (each independently completable)
issue_type: task
title: Specific subtask
deps: [epic-id]  # Links to parent
acceptance: Verifiable criteria

---

Phase 4: Create Beads Issues

After gathering requirements, create issues using Beads MCP tools.

Field Mapping

Requirement Element	Beads Field	Notes
Title	title	Imperative verb, clear action
Problem/Solution	description	Markdown supported
Priority (P0-P4)	priority	0=critical, 2=normal, 4=low
Done criteria	acceptance	Checklist format
Implementation notes	design	Technical approach (optional)
Related work	deps	Issue IDs this depends on
Category tags	labels	e.g., ["ui", "api", "tests"]

Priority Mapping

User Says	Beads Priority
Critical, blocking, urgent	0
High, important, soon	1
Normal, standard	2 (default)
Low, backlog, nice-to-have	3
Someday, maybe	4

Issue Types

Type	When to Use
bug	Something is broken
feature	New capability
task	General work item (default)
chore	Maintenance, cleanup, deps
epic	Large work with subtasks

Creating Issues

Create issues in dependency order (dependencies first):

# 1. Create epic (if applicable)
epic = mcp__beads__create(
    title="Add dark mode support",
    issue_type="epic",
    description="Overview...",
    priority=2
)

# 2. Create subtasks with dependency
mcp__beads__create(
    title="Add theme configuration schema",
    issue_type="task",
    description="Add theme field to config...",
    acceptance="- [ ] theme field in schema\n- [ ] defaults to 'light'",
    deps=[epic.id]  # Links to epic
)

Dependency Types

Use mcp__beads__dep for relationships:

Type	Meaning
blocks	Must complete before dependent can start
related	Soft link, no blocking
parent-child	Epic/subtask relationship
discovered-from	Found during other work

---

Writing for AI Agents

Issues will be executed by AI coding agents. Optimize for autonomous execution:

Do

• Use specific file paths when known
• Reference existing code patterns
• Include quality gate commands in acceptance
• Make each issue independently completable
• Use verifiable acceptance criteria

Don't

• Use vague criteria ("works correctly")
• Create issues that depend on unstated context
• Bundle unrelated changes in one issue
• Skip acceptance criteria

Good vs Bad Acceptance Criteria

Bad	Good
"Works correctly"	"Returns 200 OK with JSON body"
"Handles errors"	"Raises ValueError with message for invalid input"
"Tests pass"	"just test tests/test_auth.py passes"
"Looks good"	"Follows existing Button component patterns"

---

Example Conversation

User: Create an issue for adding dark mode

Assistant: I'll help create issues for dark mode. Let me check your project setup first.

[Runs just --list, checks recent beads issues]

I see you're using Python with a justfile. A few questions:

1. What's the primary goal? A. Reduce eye strain (accessibility) B. Match system preferences C. Visual customization option D. Other

2. What's the scope? A. All UI components B. Main view only C. Configurable subset

3. Priority? A. High - users are asking (P1) B. Normal - planned work (P2) C. Low - nice to have (P3)

User: 1A, 2A, 3B

Assistant: Good context. One more round:

4. Should theme persist across sessions? A. Yes, save to config file B. No, session only C. Follow system preference

5. Quality gates to pass? A. just format && just check (Recommended) B. just test only C. Other

User: 4A, 5A

Assistant: Perfect. I'll create an epic with subtasks.

[Creates issues via Beads MCP tools]

Created the following issues:

Epic: bd-a1b2 - Add dark mode support

• Priority: P2 (Normal)
• Type: epic

Tasks:

1. bd-c3d4 - Add theme configuration schema
   • Depends on: none (can start immediately)
2. bd-e5f6 - Create dark color palette
   • Depends on: bd-c3d4
3. bd-g7h8 - Apply theme to UI components
   • Depends on: bd-e5f6
4. bd-i9j0 - Add theme toggle in settings
   • Depends on: bd-g7h8

All tasks include acceptance criteria with just format && just check as quality gates.

Run mcp__beads__ready to see which tasks can start now.

---

Checklist

Before creating issues, verify:

• Asked clarifying questions (3-5 rounds)
• Identified quality gates from project context
• Determined issue type (single vs epic+subtasks)
• Mapped priority from user input
• Each issue has specific acceptance criteria
• Dependencies are explicit
• Issues are independently completable
• Created issues in Beads (not just documented)