Create GitHub Issue

Create a GitHub issue using the repository's issue templates. Optional argument: $ARGUMENTS (issue type: feature, bug, or spike).

Available Issue Types

| Type | Template | Title Format | Labels | |------|----------|--------------|--------| | feature | FEATURE-REQUEST.yml | [REQUEST] - <title> | — | | bug | BUG-REPORT.yml | [BUG] - <title> | bug | | spike | SPIKE-REQUEST.yml | [REQUEST] - <title> | — |

Step 0: Check for Existing Related Issues

Before creating a new issue, search for existing issues (open or closed) that may already cover this work or could be a parent for it:

bash
# Search for related issues using keywords from the user's description
gh issue list --search "<keywords>" --state all --limit 10 --json number,title,state,labels,url

Also check the current sprint for related work:

bash
# List current sprint issues from the project board
gh project item-list 1 --owner nudgebee --format json --limit 200 | jq '[.items[] | select(.status != "Done") | {number: .content.number, title: .content.title, type: .content.type, status: .status}]' 2>/dev/null | head -50

If related issues exist, present them to the user:

I found these potentially related issues:
- #1234 [open] - <title>
- #5678 [closed] - <title>

Options:
1. Link to an existing issue (add a comment or reference)
2. Create a new issue anyway
3. Skip issue creation

Only proceed to create a new issue if the user confirms none of the existing issues cover the work.

Step 1: Determine Issue Type

If $ARGUMENTS specifies a type (feature, bug, spike), use that. Otherwise, ask the user:

What type of issue would you like to create?
- feature: New feature or enhancement request
- bug: Report a bug or defect
- spike: Exploratory work to answer a question

Step 2: Gather Information Based on Type

For Feature Request

Ask or infer from context. The web form is the source of truth for this schema — these mirror .github/ISSUE_TEMPLATE/FEATURE-REQUEST.yml one for one.

1. Title: Short descriptive title for the feature
2. Function (required): Troubleshooting / collectors · AI · Integrations · Notifications / tickets / optimize · UI / API / auth · Platform · Not sure
3. Who asked for this (required): Customer — named account · Prospect — active deal · Sales / field feedback · Support — recurring ticket · Our own judgement · Internal / team need. Never invent a customer — "Our own judgement" is valid and common.
4. Summary (required): Brief explanation of the feature
5. What this unblocks (required): The account, deal, renewal or support load behind it — or a stated bet on product direction
6. How we will know it worked (required): The observable change after it ships; a number is best
7. What we are not doing instead (required): The trade-off accepted. "Nothing" is legitimate for small work
8. Basic Example (optional): Specific examples of how the feature would work
9. Drawbacks (optional): Potential drawbacks or impacts
10. Unresolved questions (optional): Questions that remain unresolved
11. Parent / epic (optional): The larger piece of work this slices, as #<n>
12. Related work (optional): One link per line, prefixed with the relationship — Part of #123 · Blocked by #123 · Blocks #123 · Related to #123

If you cannot answer 5, 6 or 7 from context, ask rather than inventing plausible text — a fabricated customer or metric survives into prioritisation as if it were evidence.

For Bug Report

Ask or infer from context:

1. Title: Short descriptive title for the bug
2. Description (required): Explicit description of the issue
3. Reproduction URL (required): GitHub URL or relevant link
4. Reproduction Steps (required): Step-by-step instructions to reproduce
5. Screenshots (optional): Screenshots if applicable
6. Logs (optional): Relevant log output
7. Browsers (optional): Affected browsers (Firefox, Chrome, Safari, Edge, Opera)
8. OS (optional): Affected operating systems (Windows, Linux, Mac)

For Spike Request

Ask or infer from context:

1. Title: Short descriptive title for the spike
2. Summary (required): Brief explanation of the exploration
3. Objectives (required): What you want to learn/answer
4. Result Summary (required): Expected outcome format
5. Next Steps (required): What happens after the spike
6. Unresolved Questions (optional): Open questions
7. Reference Issues (optional): Related issue numbers

Step 3: Generate Issue Content

Based on the type, format the issue body in markdown:

Feature Request Body

The web form is the source of truth for this schema. GitHub renders .github/ISSUE_TEMPLATE/FEATURE-REQUEST.yml as ### headings whose text matches each field's label. Match them exactly so form-filed and skill-filed issues parse the same.

markdown
### Function
{function}

### Who asked for this
{source}

### Summary
{summary}

### What this unblocks
{unblocks}

### How we will know it worked
{success}

### What we are not doing instead
{tradeoff}

### Basic Example
{basic_example or "None"}

### Drawbacks
{drawbacks or "None"}

### Unresolved questions
{unresolved_questions or "None"}

### Parent / epic
{parent or "None"}

### Related work
{related or "None"}

Bug Report Body

The web form is the source of truth for this schema. GitHub renders .github/ISSUE_TEMPLATE/BUG-REPORT.yml as ### headings whose text matches each field's label exactly. Emit the same headings, in the same order, with the same capitalisation, so an issue filed by this skill is indistinguishable from one filed through the form. Use ###, not ##, and do not rename the headings.

Omit any optional heading you have nothing for rather than writing "N/A" — an empty section is worse than an absent one.

markdown
### Environment
{Exactly one of: Production | QA / Test | Dev | Local only | Not sure}

### Description
{description}

### Impact
- **Who is affected**: {all tenants / specific feature users / dev-only / etc.}
- **Severity**: {what the user can't do, or what they see incorrectly}
- **Since when**: {date or version, "unknown" if not known}

### Link
{URL to the affected page, dashboard or conversation. Omit the heading if none.}

### Reproduction steps
{reproduction_steps}

### Logs
{logs — omit the heading if none}

### Screenshots
{screenshots — omit the heading if none}

### Client details
{Browser / OS, e.g. "Chrome 128 / macOS". UI bugs only — omit for backend bugs.}

Environment, Description, Impact and Reproduction steps are required by the form: always emit all four, writing "unknown" where you must. Environment must be one of the five literal dropdown options above, spelled exactly — any other string will not match what the form produces.

If you change the form, change this block in the same PR. The two drifting apart is what made half the bug corpus unparseable in the first place.

Spike Request Body

markdown
## Summary
{summary}

## Objectives
{objectives}

## Result Summary
{result_summary}

## Next Steps
{next_steps}

## Unresolved Questions
{unresolved_questions or "None"}

## Reference Issues
{reference_issues or "None"}

Step 4: Confirm with User

Show the user the formatted issue:

Title: {title_with_prefix}
Labels: {labels}
Body:
---
{body}
---

Create this issue? (yes/no)

Step 5: Create the Issue

Use GitHub CLI to create the issue:

bash
gh issue create 
  --title "{title}" 
  --body "$(cat <<'EOF'
{body}
EOF
)" 
  --label "{labels}"  # Only if labels exist

Step 6: Add to Project with Current Iteration

After creating the issue, automatically add it to the project board and set iteration to "current":

bash
# Get the issue number from the created issue URL
ISSUE_NUMBER={extracted_issue_number}

# Add issue to the project (project number 1 = "Nudgebee" main project)
gh project item-add 1 --owner nudgebee --url "https://github.com/nudgebee/nudgebee/issues/${ISSUE_NUMBER}"

# Get the item ID for the newly added issue
ITEM_ID=$(gh project item-list 1 --owner nudgebee --format json --limit 1000 | jq -r ".items[] | select(.content.number == ${ISSUE_NUMBER}) | .id")

# Set the iteration field to current iteration
# Iteration field ID: PVTIF_lADOCG7t1c4ATt4GzgMmEFQ
gh project item-edit --project-id PVT_kwDOCG7t1c4ATt4G --id "${ITEM_ID}" --field-id PVTIF_lADOCG7t1c4ATt4GzgMmEFQ --iteration-id "@current"

Note: If the project commands fail (e.g., project not found or permissions), the issue is still created successfully. The iteration assignment is a best-effort addition.

Step 7: Output Result

Issue created: {url}
Title: {title}
Type: {type}
Number: #{number}
Iteration: Current (if project assignment succeeded)

Context-Aware Creation

If the user is working on code changes and asks to create an issue, try to infer:

• Feature: If they've implemented something new, suggest documenting it as a feature request for tracking
• Bug: If they've fixed something, suggest creating a bug report to document the issue
• Spike: If they've been exploring/researching, suggest a spike to document findings

Example: After implementing the new/recurring issues feature, suggest:

Would you like to create a feature request issue to track this work?
Title: [REQUEST] - Add new vs recurring issue tracking to Kubernetes events