bug

name	bug
description	Create a bug sub-issue interactively or with a title, or add existing issues to a tracking PR
argument-hint	["<bug title>"] | [<parent> "<title>"] | [add #issue [to #parent]]
user-invocable	true

Bug Sub-Issue Skill

Create a bug issue with intelligent context gathering, or add existing bug issues to a tracking PR.

Input

The user provides: $ARGUMENTS

Three modes of operation:

Mode 1: Add existing bug issues to tracking PR

• add #<issue> [#<issue>...] [to #<parent>]

Examples:

/bug add #1042                  # Add existing issue #1042 as bug, parent from branch
/bug add #1042 to #723         # Add existing issue #1042 as bug to epic #723
/bug add #1042 #1043           # Add multiple existing bug issues at once

Mode 2: Create new bug issue with title

• "<bug title>" - Auto-detect parent from branch
• <parent-issue> "<bug title>" - Explicit parent override

Examples:

/bug "Webhook signature fails in test mode"        # Parent from branch
/bug 724 "Webhook signature fails in test mode"   # Explicit parent #724

Mode 3: Interactive bug report (no arguments)

• No arguments → interactive mode with context gathering

Examples:

/bug                            # Interactive mode: gather context, write issue

Disambiguation: add → Mode 1. No arguments → Mode 3. Anything else → Mode 2.

Workflow

Mode 1: Add Existing Bug Issues

Use this when you have already-created bug issues that need to be linked to an epic's tracking PR.

Step B1: Parse Arguments

Extract from $ARGUMENTS (after stripping the add keyword):

• Issue numbers: all #<number> tokens before the to keyword (strip the # prefix)
• Parent issue: the #<number> after to, or auto-detect from branch if no to keyword

# Auto-detect parent from branch if needed
PARENT_ISSUE=$(~/.claude/bin/extract-issue-from-branch.sh)

If no parent found and no to #<parent> given: ask the user to provide one explicitly.

Step B2: Find Tracking PR

~/.claude/bin/find-tracking-pr.sh <repo> $PARENT_ISSUE

If no tracking PR exists: Inform the user and suggest using /decompose first.

If parent is a sub-issue, also find the grandparent tracking PR:

~/.claude/bin/gh-save.sh /tmp/parent-issue-body.json issue view [parent-issue] --json body

Use the Read tool to read /tmp/parent-issue-body.json and find Parent issue: #\d+ to get the grandparent issue number.

Step B3: Fetch Issue Details

Fetch details for all issues to be added:

~/.claude/bin/batch-issue-view.sh <repo> [issue-numbers...]

Use the Read tool to read the output. For each issue, extract: number, title, state, labels.

Step B4: Add Bug Label

For each issue, ensure the bug label is present:

gh issue edit [issue-number] --add-label "bug"

Also inherit relevant labels from the parent issue (e.g., payment, backend).

Step B5: Update Tracking PR

5a. Add Closes statements for each new issue (append after existing Closes lines):

Closes #[existing-issues]
Closes #1042  ← NEW

5b. Add rows to tracking table for each new issue (with 🐛 prefix):

| # | Sub-Issue | Status | PR |
|---|-----------|--------|-----|
| ... existing entries ... |
| N | #1042 - 🐛 Bug: [Issue title] | ⏳ Pending | - |   ← NEW

Map issue state to status: OPEN → ⏳ Pending, CLOSED → ✅ Complete.

5c. Update progress line to reflect the new total.

Step B6: Link as Native GitHub Sub-Issues

Link the added bug issues to the parent issue using the GitHub GraphQL API:

1. Fetch the node IDs for parent and all bug issues in one query:

gh api graphql -f query='
{
  repository(owner: "OWNER", name: "REPO") {
    parent: issue(number: [parent-number]) { id }
    sub1: issue(number: [sub-number-1]) { id }
    ...
  }
}'

2. Link each bug issue to the parent:

gh api graphql -f query='
mutation {
  addSubIssue(input: {issueId: "[parent-node-id]", subIssueId: "[sub-node-id]"}) {
    issue { number }
    subIssue { number }
  }
}'

Do this for ALL added issues. This enables GitHub's native sub-issue tracking in the UI.

Step B7: Show Summary

## Bug Issues Added to Epic

✅ Added #1042 - 🐛 [title] to tracking PR #[pr-number]
✅ Bug label added
✅ Closes statements updated
✅ Progress: X of Y sub-issues complete (Z%)

### Quick Links
- Tracking PR: #[pr-number]
- Parent issue: #[parent-issue]
- Bug issue: #1042

---

Mode 3: Interactive Bug Report

Use this when no arguments are provided. Gathers context interactively and writes a well-structured issue.

Step I1: Detect Parent (optional)

Try to detect parent from the current branch:

PARENT_ISSUE=$(~/.claude/bin/extract-issue-from-branch.sh)

• If found: display "Detected parent: #N" and fetch issue title for context
• If not found: continue without parent — the issue will be standalone (no tracking PR updates)

Step I2: Auto-context (silent, before asking anything)

Gather context automatically to enrich the bug report:

1. Recent git activity:

   git log --oneline -10
   git diff --stat
   

2. Branch context: current branch name, uncommitted changes
3. Test failures: check for recent test output in /tmp/ (e.g., pytest output files)
4. Sentry: if the project CLAUDE.md references Sentry and MCP tools (mcp__sentry__*) are available, fetch recent unresolved issues for the project

Store this context internally — do NOT display it to the user yet.

Step I3: Open prompt — let the user dump everything

Ask with AskUserQuestion (use an option that allows free text):

"Beschrijf de bug. Je kunt hier alles kwijt: beschrijving, log output, foutmeldingen, bestandspaden, screenshots — alles door elkaar. Ik sorteer het wel uit."

The user can dump everything at once in any order:

• Error messages / stack traces / console logs
• Description of what went wrong
• File paths that are relevant
• Screenshots (if mentioned or pasted)
• Reproduction steps
• All at once, in any order

Step I4: Parse and classify the input

Analyze the user's dump and classify:

• Description: free text about the problem
• Logs/errors: stack traces, console output, error messages (look for patterns: Traceback, Error:, at line, TypeError, 500, etc.)
• File references: paths to files → read them with the Read tool and extract relevant fragments
• Repro steps: if the user described steps to reproduce
• Severity clues: words like "crash", "data loss", "blocks" → Critical/High; "wrong color", "typo" → Low

Step I5: Follow-up questions (only for what's missing)

Only ask about information that was NOT in the dump. Use AskUserQuestion to ask multiple missing items at once (max 4 questions per call).

Possible follow-up questions (only if missing):

• Severity: "Hoe ernstig is deze bug?" → Critical (blocks work) / High (important) / Medium / Low
• Repro steps: "Kun je beschrijven hoe je de bug kunt reproduceren?" (only if not already in dump)
• Expected behavior: "Wat had er moeten gebeuren?" (only if unclear from context)
• Title: "Wil je een specifieke title, of genereer ik er een?" → Generate for me (Recommended) / Custom title

If the dump is already complete enough (description + evidence + severity inferable from context), skip follow-up questions and go directly to Step I6.

Step I6: Write issue body

Combine all user input + auto-context into a structured issue body:

## Bug Description
<Rewritten description based on user input + auto-context>

## Steps to Reproduce
1. ...
2. ...
3. ...

## Expected Behavior
<Derived from description>

## Actual Behavior
<Derived from description>

## Evidence
<Relevant code fragments, log output, error messages — from step I3>
<If file references were provided: include relevant snippets>

## Context
- Branch: <current-branch>
- Recent changes: <summary of git log>
- Discovered while working on: #<parent-issue> (if available)
- Severity: <chosen or inferred severity>

Step I7: Review before creation

Show the generated issue (title + body) to the user.

Ask with AskUserQuestion: "Ziet dit er goed uit?"

• Aanmaken (Recommended): proceed to Step I8
• Aanpassen: ask what needs to change, adjust, show again
• Annuleren: abort without creating

Step I8: Create + link

1. Write body to /tmp/bug-issue.md using the Write tool
2. Determine title format:
   • If parent found: 🐛 [Parent #XXX] Bug: <title>
   • If standalone: 🐛 Bug: <title>
3. Create the issue:

   gh issue create --title "<title>" --label "bug" --body-file /tmp/bug-issue.md
   

4. If severity is Critical or High: add extra label

   gh issue edit [new-issue] --add-label "priority: high"
   

5. If parent found:
   • Link as GitHub sub-issue (same GraphQL as Mode 2, Step 6)
   • Find and update tracking PR (same as Mode 2, Step 7)
6. If standalone (no parent):
   • Only create the issue, no tracking PR updates
   • Report: "Standalone bug issue — niet gekoppeld aan een epic"

Step I9: Summary

If linked to parent:

## Bug Issue Created

✅ Created: #[new-issue-number] - 🐛 Bug: [title]
✅ Parent: #[parent-issue]
✅ Added to tracking PR #[pr-number]
✅ Will auto-close when PR merges

### Quick Links
- Bug issue: [url]
- Parent issue: #[parent-issue]
- Tracking PR: #[pr-number]

If standalone:

## Bug Issue Created

✅ Created: #[new-issue-number] - 🐛 Bug: [title]
ℹ️ Standalone issue — not linked to an epic

### Quick Links
- Bug issue: [url]

---

Mode 2: Create New Bug Issue (with title)

Step 1: Parse Arguments and Detect Parent Issue

Check if first argument is a number:

• If $ARGUMENTS starts with a number → use that as parent issue
• Otherwise → extract from branch name

Extract from branch:

PARENT_ISSUE=$(~/.claude/bin/extract-issue-from-branch.sh)

Example branch names:

• issue-724-stripe-webhook → parent = 724
• issue-723-stripe-payment-provider → parent = 723

If no parent found: Ask the user to provide one explicitly.

Step 2: Extract Bug Title

After determining parent issue, the rest of $ARGUMENTS is the bug title.

Parse:

• /bug "Webhook fails" → parent=from branch, title="Webhook fails"
• /bug 724 "Webhook fails" → parent=724, title="Webhook fails"

Step 3: Get Parent Issue Info

~/.claude/bin/gh-save.sh /tmp/parent-issue.json issue view [parent-issue] --json number,title,labels

Use the Read tool to read /tmp/parent-issue.json.

Step 4: Find the Tracking PR

Search for the tracking/parent PR:

~/.claude/bin/find-tracking-pr.sh <repo> [parent-issue]

If parent is a sub-issue (e.g., #724), also find the grandparent tracking PR:

~/.claude/bin/gh-save.sh /tmp/parent-issue-body.json issue view [parent-issue] --json body

Use the Read tool to read /tmp/parent-issue-body.json and find Parent issue: #\d+ to get the grandparent issue number.

Step 5: Create Bug Issue

First write the body using the Write tool to /tmp/bug-issue.md:

## Parent Issue
Related to #[parent-issue] ([parent title])

## Bug Description
[To be filled in]

## Steps to Reproduce
1.
2.
3.

## Expected Behavior


## Actual Behavior


## Context
- Discovered while working on: #[parent-issue]
- Branch: [current-branch]

---
_This bug blocks the completion of #[parent-issue]_

Then create the issue:

gh issue create --title "🐛 [Parent #XXX] Bug: [bug title]" --label "bug" --body-file /tmp/bug-issue.md

Step 6: Link as Native GitHub Sub-Issue

Link the newly created bug issue to the parent issue using the GitHub GraphQL API:

1. Fetch the node IDs for parent and the new bug issue:

gh api graphql -f query='
{
  repository(owner: "OWNER", name: "REPO") {
    parent: issue(number: [parent-number]) { id }
    bug: issue(number: [new-bug-number]) { id }
  }
}'

2. Link the bug issue to the parent:

gh api graphql -f query='
mutation {
  addSubIssue(input: {issueId: "[parent-node-id]", subIssueId: "[bug-node-id]"}) {
    issue { number }
    subIssue { number }
  }
}'

Step 7: Add to Tracking PR

Update the tracking PR to include the new bug:

6a. Add to Closes statements (at top of PR body):

Closes #[parent-issue]
Closes #[other-sub-issues]
Closes #[NEW-BUG-ISSUE]  ← Add this

6b. Add to tracking table:

| # | Sub-Issue | Status | PR |
|---|-----------|--------|-----|
| ... | existing entries ... | ... | ... |
| N | #[NEW] - 🐛 Bug: [title] | ⏳ Pending | - |

Step 8: Show Summary

## Bug Issue Created

✅ Created: #[new-issue-number] - 🐛 Bug: [title]
✅ Parent: #[parent-issue]
✅ Added to tracking PR #[pr-number]
✅ Will auto-close when PR merges to develop

### Quick Links
- Bug issue: [url]
- Parent issue: #[parent-issue]
- Tracking PR: #[pr-number]

### Next Steps
- Fix the bug in your current branch
- Or create a separate branch: `git checkout -b issue-[new-bug-number]-fix`

Label Handling

Automatically add labels:

• bug - always
• Inherit relevant labels from parent (e.g., payment, backend)

gh issue edit [new-issue] --add-label "bug"

Example Session

$ git branch --show-current
issue-724-stripe-webhook

$ /bug "Signature verification fails for test webhooks"

Detected parent issue: #724 (from branch: issue-724-stripe-webhook)

Creating bug issue...
✅ Created: #731 - 🐛 [Parent #724] Bug: Signature verification fails for test webhooks

Finding tracking PR...
✅ Found: PR #727 (Stripe Payment Provider)

Updating tracking PR...
✅ Added "Closes #731" to PR #727
✅ Added #731 to tracking table

Done! Bug #731 will auto-close when PR #727 merges.