GitHub Issue Planner

Plan issues collaboratively, then create them in GitHub using gh CLI.

Workflow

1. Determine Issue Type

Ask if not obvious from context:

• Bug – Something broken or not working as expected
• Feature – New functionality or enhancement
• Task – Internal task or chore
• Epic – Large initiative requiring multiple child issues

Big Task Detection

Before creating an issue, evaluate whether the request is a “big task” that should be an Epic with subtasks. A task qualifies as big if it has:

• Multiple distinct components – The work involves several separate features or pieces
• Cross-cutting concerns – Requires work across different areas (frontend, backend, database)
• Extended scope – Would take more than a few days to complete
• Multiple acceptance criteria – Has several user stories or distinct outcomes
• System-wide impact – Affects multiple parts of the codebase

When a big task is detected, follow the Epic Creation Workflow below instead of creating a single issue.

2. Gather Requirements

Ask targeted questions based on type:

Bug:

• What’s happening vs what should happen?
• Steps to reproduce?
• Environment details?

Feature:

• Who is this for and what problem does it solve?
• What does “done” look like?
• Any constraints or dependencies?

Task

• What needs to be done?
• What does “done” look like?

Epic:

• What’s the high-level goal?
• What are the major milestones?
• What’s explicitly out of scope?

Keep questions minimal—gather just enough to write a clear issue.

3. Draft the Issue

Use templates from references/templates.md.

Present the draft to the user:

Here's the draft issue:

**Title:** [title]

[body content]

---
Ready to create this in GitHub?

4. Create in GitHub

After user confirms, create with gh:

gh issue create --title "Title here" --body "Body here"

For epics, create the parent issue first, then offer to create child issues that reference it.

Title Standards

• Sentence case – Capitalise only the first word and proper nouns.
• No type prefixes – Use GitHub issue types, not Bug:, Feature: etc…
• Imperative mood for enhancements – “Fix N+1 issue” not “Fixing N+1 issue”
• Descriptive for bugs – Describe the symptom “Failed to allocate booking to staff member”
• Specific – “Be specific, it must be understandable without opening the issue body”

Notes

• Always show the draft before creating
• For epics, confirm which child issues to create
• If gh isn’t authenticated, tell user to run gh auth login
• Never include “Generated with Claude Code”
• Never use title case for descriptions – use sentence case
• Always follow the Label Management Process – See references/labels.md for available labels and the process to check/create/apply them
• Map priority to urgency labels: P1=Critical, P2=High, P3=Medium, P4=Low