paulund/plan-bug

Plan Bug

Fast-path for logging bugs the user already understands. Interview, file, done — no codebase exploration, no reproduction attempt. The agent that later picks up the issue (via /dev-implement or an orchestrator) does the investigation.

For underspecified bugs that need evaluation or repro, use /ops-triage instead.

Workflow

Phase 1 — Quick context

Confirm the repo from git remote. If the user already gave a one-line description, skip ahead. Otherwise ask: "What's the bug?"

Phase 2 — Interview

Ask one question at a time, conversationally. Skip anything the user has already volunteered. Required fields:

• Title — one-line summary, imperative present (e.g. bug: search returns stale results after filter change).

• Steps to reproduce — numbered, concrete. Push back on "sometimes it breaks" — get the specific path that triggers it.

• Expected behaviour — one or two sentences.

• Actual behaviour — one or two sentences. Include any error message or console output the user has.

• Severity — let the user describe impact (who's affected, how often, is there a workaround). Use that to recommend a priority:

  • p1 — data loss, security, blocks core flow, affects all users
  • p2 — significant feature broken, has workaround, or affects many users
  • p3 — edge case, cosmetic, low impact

  Show the recommendation and reasoning. Let the user override.

• Environment (only when relevant) — browser/OS/version, account type, feature flags. Skip for backend-only bugs.

• First seen / regression? — if the user knows when it started, capture it.

If the user can't produce repro steps, don't fabricate them. Recommend hitl with a note that repro is needed.

Phase 3 — Recommend execution label

• Default afk when: clear repro, clear expected vs actual, no judgement call needed on the fix.
• Recommend hitl when: acceptance criteria are fuzzy, fix involves a product/UX trade-off, or the bug touches a sensitive area (payments, auth, data migrations).

State the recommendation and the reason. Let the user override.

Phase 4 — Confirm

Show the drafted issue — title, full body, and the exact label set — before filing. Wait for explicit "yes / file it / go ahead" before creating.

Phase 5 — File the issue

gh issue create \
  --title "bug: <short description>" \
  --label "bug,planned,<afk|hitl>,p<1|2|3>" \
  --body "$(cat <<'EOF'
> *This was generated by AI during bug logging.*

## Summary

<one-paragraph description of the bug>

## Steps to reproduce

1. ...
2. ...
3. ...

## Expected behaviour

<...>

## Actual behaviour

<...>

## Environment

<browser/OS/version, or "n/a — backend">

## First seen

<when it started, or "unknown">

## Acceptance criteria

- [ ] <specific, testable criterion>
- [ ] Regression test added that fails before the fix
EOF
)"

After filing, print the issue URL. The planned + afk labels signal that the issue is ready for autonomous implementation — an orchestrator polling those labels will pick it up, or a human can invoke /dev-implement directly with the issue number.

Constraints

Must:

• Include the AI disclaimer (> *This was generated by AI during bug logging.*) at the top of every issue body.
• Apply exactly: bug + planned + (afk | hitl) + (p1 | p2 | p3).
• Show the full issue draft and wait for explicit user confirmation before running gh issue create.

Must not:

• Explore the codebase, attempt to reproduce, or read source. This is a registration skill.
• Fabricate repro steps. If the user can't produce them, recommend hitl.
• Apply needs-triage or needs-info — those belong to /ops-triage. plan-bug is for bugs the user already understands well enough to file directly.
• Create the issue before the user explicitly confirms.