gh-taylorhuston-ai-toolkit-plugins-ai-toolkit/commands/issue.md

tags, description, argument-hint, allowed-tools, model, references_guidelines

tags	description	argument-hint	allowed-tools	model	references_guidelines
workflow issue task bug spike conversational	Create standalone work items (TASK, BUG, or SPIKE) with AI-assisted type detection	["description"]	Read Write Edit Glob Grep TodoWrite	claude-sonnet-4-5	docs/development/workflows/task-workflow.md docs/development/workflows/bug-workflow.md docs/development/workflows/spike-workflow.md docs/development/workflows/pm-workflows.md

/issue Command

WHAT: Create standalone work items (TASK, BUG, or SPIKE) through natural conversation.

WHY: Single entry point for all standalone work items with AI-assisted type detection and optional spec linkage.

HOW: Describe what you need, AI detects type, confirms with you, optionally links to spec, creates issue directory and skeleton file.

Usage

/issue                              # Start conversation
/issue "Login crashes on Safari"    # AI detects: BUG
/issue "Add CSV export feature"     # AI detects: TASK
/issue "GraphQL vs REST?"           # AI detects: SPIKE

ID Format

All issues use numeric IDs. Type is determined by which file exists in the directory:

pm/issues/001-feature-name/TASK.md   → Task (type from file)
pm/issues/002-bug-name/BUG.md        → Bug (type from file)
pm/issues/003-spike-name/SPIKE.md    → Spike (type from file)
pm/issues/PROJ-123-name/TASK.md      → External (Jira) task

This unified scheme:

• Single counter for all local issues
• External IDs (PROJ-123) work seamlessly
• Type always determined from file, not ID prefix

Type Detection

AI detects issue type from description keywords:

Type	Keywords	Purpose
BUG	fix, broken, crash, error, regression, doesn't work, fails	Something is broken
SPIKE	should we, which, can we, explore, vs, compare, evaluate, feasibility	Technical exploration
TASK	add, implement, create, build, enhance (default)	New feature or enhancement

User can always override the detected type.

Execution Flow

1. Gather Description

If no description provided, ask:

"What do you need to do? Describe the work item."

2. Detect Type

Analyze description for keywords:

• BUG indicators: "fix", "broken", "crash", "error", "regression", "fails", "doesn't work"
• SPIKE indicators: "should we", "which", "can we", "explore", "vs", "compare", "feasibility"
• TASK: default if no BUG/SPIKE indicators

Present detection:

"This sounds like a BUG. Create as issue 001? (yes / task / spike)"

3. Determine Next Issue Number

# Count ALL existing issues (single counter)
ls pm/issues/ | grep -E '^[0-9]{3}-' | sort -n | tail -1
# Extract number, increment for next ID
# Format: 001, 002, 003, ...

4. Ask About Spec Linkage

"Link to an existing spec? (no / SPEC-001 / SPEC-002 / ...)"

If specs exist, list them. If user selects one, add spec: SPEC-### to frontmatter.

5. Conversational Details

Based on type, gather required information using the appropriate template:

For TASK (templates/task-template.md):

• Description (already have from initial input)
• Acceptance criteria
• Technical notes (optional)

For BUG (templates/bug-template.md):

• Description (already have)
• Steps to reproduce
• Expected vs actual behavior
• Severity (critical/high/medium/low)

For SPIKE (templates/spike-template.md):

• Questions to answer
• Time box (max hours)
• Deadline (optional)
• Number of approaches to explore

6. Create Issue

Create directory and file:

pm/issues/###-{slug}/
└── {TYPE}.md    # TASK.md, BUG.md, or SPIKE.md (determines type)

ID format: 3-digit zero-padded number (001, 002, ...) Slug: kebab-case from description (max 50 chars)

7. Next Steps

For TASK/BUG:

"Created issue 001 (task). Next: /plan 001 to create implementation plan."

For SPIKE:

"Created issue 001 (spike). Next: /plan 001 to create exploration plans."

If linked to spec, also update SPEC.md Tasks section.

Example

User: /issue "Login page crashes when clicking submit on Safari mobile"

AI: This sounds like a **BUG** - a crash that needs fixing.
    Create as issue 001? (yes / task / spike)

User: yes

AI: Link to an existing spec?
    - SPEC-001: User Authentication
    - SPEC-002: Mobile Experience
    - no (standalone)

User: SPEC-001

AI: Let me gather a few more details for the bug report.

    Steps to reproduce?

User: 1. Open login page on Safari iOS
       2. Enter valid credentials
       3. Click Submit button
       4. Page crashes

AI: Expected vs actual behavior?

User: Expected: Login succeeds. Actual: White screen crash.

AI: Severity? (critical / high / medium / low)

User: high

AI: Created issue 001 (bug): Login Safari Crash

    📁 pm/issues/001-login-safari-crash/BUG.md
    🔗 Linked to SPEC-001: User Authentication

    Next: /plan 001

File Structure

pm/issues/
├── 001-csv-export/
│   └── TASK.md          # Type = task (from file)
├── 002-login-safari-crash/
│   └── BUG.md           # Type = bug (from file)
├── 003-graphql-vs-rest/
│   └── SPIKE.md         # Type = spike (from file)
└── PROJ-123-oauth/
    └── TASK.md          # External Jira task

Type Detection from Files

Commands detect issue type by which file exists:

# In pm/issues/###-name/ directory:
if [ -f "TASK.md" ]; then type="task"
elif [ -f "BUG.md" ]; then type="bug"
elif [ -f "SPIKE.md" ]; then type="spike"
fi

This enables:

• Numeric IDs for all local issues
• External IDs (PROJ-123) work without modification
• Type always authoritative from file content

Integration

Workflow position:

/issue → /plan {ID} → /implement {ID} → /complete {ID}

Spec linkage:

• Standalone issues work without a spec
• Linked issues appear in SPEC.md Tasks section
• spec: SPEC-### in issue frontmatter enables traceability

Related commands:

• /spec - Create feature specs with multiple tasks (top-down)
• /plan - Create implementation plan for any issue type
• /implement - Execute plan phases
• /complete - Complete issue per workflow requirements