bug

name: bug description: Create a structured bug ticket (Given/When/Then scenario, repro steps, severity). argument-hint: "" allowed-tools: Bash, Read, Write

/bug — Create a Bug Report Ticket

Creates a structured GitHub Issue for a bug with Given/When/Then scenario, repro steps, environment, and severity. Asks guided questions, shows the formatted ticket for confirmation, then creates the issue.

Path resolution

Read the registry path via portfolio_registry, the per-project docs dir via portfolio_projects_dir, and the ideas backlog via portfolio_ideas_backlog — all from .claude/hooks/_lib-portfolio-paths.sh. Source the helper at the top of any bash block that touches those paths:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
registry=$(portfolio_registry)

Defaults match today's single-fork layout (./apexyard.projects.yaml, ./projects, ./projects/ideas-backlog.md). Adopters in split-portfolio mode override the portfolio.{registry, projects_dir, ideas_backlog} keys in .claude/project-config.json. Don't hardcode literal apexyard.projects.yaml or projects/ paths in bash blocks — the helper resolves whichever mode the adopter is in. See docs/multi-project.md.

Usage

/bug Profile picture upload fails
/bug RTL resets on navigation
/bug Follow button state not persisted

Process

0. Write the active-issue-skill marker (REQUIRED — me2resh/apexyard#268)

Before any gh issue create (or other tracker CLI), write this skill's name to the active-issue-skill marker so require-skill-for-issue-create.sh lets the command through. At skill entry:

ops_root="$(r=$PWD;while [ ! -f \"$r/onboarding.yaml\" ] && [ \"$r\" != / ];do r=${r%/*};done;echo $r)"
mkdir -p "$ops_root/.claude/session"
echo "bug" > "$ops_root/.claude/session/active-issue-skill"

Remove the marker on every exit path (success, early-exit, user cancel, error):

rm -f "$ops_root/.claude/session/active-issue-skill"

The clear-issue-skill-marker.sh SessionStart hook sweeps stale markers from killed sessions, but a clean exit should never leave one behind. See AgDR-0030.

1. Resolve the target repo

Read .claude/session/current-ticket to determine which repo we're working in. If no active ticket, check apexyard.projects.yaml for managed projects. If only one project, use it. If multiple, ask:

Which project is this bug in?

If no projects are registered, ask for the repo in owner/repo format.

2. Parse or ask for the title

Take the title from $ARGUMENTS. If empty, ask:

What's the bug? Give me a short description.

3. Gather details (one question at a time)

Ask conversationally — do NOT batch all questions. Wait for each answer before asking the next.

a) Bug Scenario

Describe the bug scenario:
- Given: what's the starting state?
- When: what action triggers the bug?
- Then: what happens (the broken behavior)?
- Expected: what should happen instead?

If the user gives a casual description, restructure it into Given/When/Then/Expected format and confirm.

b) Repro Steps

What are the exact steps to reproduce?

c) Severity

How severe is this?
1. P0 — blocks a core feature, must fix immediately
2. P1 — important, fix soon
3. P2 — minor, fix when convenient

d) Environment (optional)

Any environment details? (browser, device, staging/prod, or Enter to skip)

e) Investigation Notes (optional)

Any initial investigation? (root cause hypothesis, relevant code paths, or Enter to skip)

4. Resolve the bug body template

Resolve the bug body template via the portfolio helper so adopter overrides win when present:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
template=$(portfolio_resolve_template tickets/bug.md)   # → custom-templates/tickets/bug.md if present, else templates/tickets/bug.md

Single-fork adopters (no portfolio block) and adopters with no override fall straight through to templates/tickets/bug.md. Adopters who want a customised bug-body shape drop their version at <private_repo>/custom-templates/tickets/bug.md. See templates/README.md for the path-mirroring convention.

Backward-compat fallback: if portfolio_resolve_template returns empty (template file missing — partial adopter setup), fall back to the inline heredoc body below and print a one-line WARN on stderr (WARN: tickets/bug.md template missing — using inline fallback). This preserves the pre-refactor behaviour for adopters whose installations don't yet have the new template files.

5. Show the formatted ticket for confirmation

Substitute the gathered inputs into the resolved template (or the inline heredoc fallback), then display the full ticket using the resolved shape (the default templates/tickets/bug.md shape is reproduced below):

Here's the ticket I'll create:

---
**[{P0|P1|P2}] {title}**

## Bug Scenario
**Given** {precondition}
**When** {action}
**Then** {unexpected result}
**Expected** {correct behavior}

## Repro Steps
1. {step 1}
2. {step 2}
3. ...

## Environment
{environment or "Not specified"}

## Severity
{P0-critical / P1-important / P2-later}

## Mitigation
{workaround or "—"}

## Investigation Notes
{notes or "—"}

## Glossary
| Term | Definition |
|------|------------|
| {term} | {definition} |
---

Labels: bug, {P0|P1|P2}
Repo: {owner/repo}

Create this ticket? (yes / edit / cancel)

6. Handle response

• yes / looks good / go → create the issue
• edit / change X → ask what to change, update, re-show
• cancel / no → abort

7. Create the GitHub Issue

gh issue create --repo {owner/repo} \
  --title "[{P0|P1|P2}] {title}" \
  --label "bug,{priority}" \
  --body "{formatted body}"

8. Return the URL

Created: {owner/repo}#{number} — {title}
{url}

Rules

1. One question at a time. Never batch questions. Wait for each answer.
2. Always confirm before creating. Show the full ticket and get explicit "yes".
3. Given/When/Then is required. Restructure casual descriptions into the format.
4. At least one repro step. Don't create bugs without repro.
5. Labels auto-applied. bug always, plus the severity label. Severity label scheme reads from .claude/project-config.*.json → .ticket.label_priority_scheme (default P0,P1,P2,P3).
6. Title prefix. The accepted prefix list reads from .claude/project-config.*.json → .ticket.prefix_whitelist; [Bug] must be in that list. Some teams prefer [Bug] prefix with the severity as a label (the default); others embed severity in the title ([P0], [P1]). Skill respects whichever is configured. See apexyard#109.

Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.