---
name: github-issues
description: Use when creating, triaging, or filing GitHub issues — writing bug reports, feature requests, or task tickets; classifying severity; using the gh CLI; or handling edge cases like regressions, flaky failures, security vulnerabilities, or cross-repo dependencies.
---

# GitHub Issues

Write issues that are acted on — not ignored, misrouted, or reopened for missing info.

## When to Activate

- Filing a bug report, feature request, or engineering task on GitHub
- Triaging an issue and assigning severity or priority
- Using the `gh` CLI to create or manage issues programmatically
- Handling special cases: regressions, flaky tests, security holes, data-loss bugs
- Writing acceptance criteria or reproduction steps
- Linking issues across repositories or to pull requests

## Issue Types & When to Use Each

| Type | Label | Use When | Must Include |
|---|---|---|---|
| Bug | `bug` | Observed behavior differs from documented or expected | Repro steps, expected vs actual, environment |
| Regression | `bug`, `regression` | Previously working behavior broke in a specific version | Commit/PR that introduced it, last-good version |
| Feature | `enhancement` | New capability that doesn't exist yet | Problem statement, proposed solution, AC |
| Task / Chore | `chore` | Non-feature engineering work (refactor, migration, upgrade) | Why now, success criteria, estimated scope |
| Performance | `performance` | Measurable slowdown or resource regression | Benchmark before/after, profiling output |
| Security | (private) | Vulnerability, auth bypass, data exposure | **Do NOT file publicly — use private advisory** |
| Documentation | `documentation` | Missing, wrong, or outdated docs | Affected page/file, what's wrong, correct behavior |
| Flaky Test | `flaky`, `ci` | Test fails intermittently with no code change | Failure frequency, CI run links, log excerpts |

## Severity × Priority Matrix

Severity = impact if it occurs. Priority = urgency to fix.

| | High Priority | Low Priority |
|---|---|---|
| **High Severity** | P0: fix immediately, page oncall | P1: fix this sprint |
| **Low Severity** | P2: schedule soon, workaround exists | P3: backlog, good first issue |

**P0 triggers:** data loss, auth bypass, production down, PII exposure, charge errors.  
**P1 triggers:** feature broken for >1% of users, no workaround, SLA at risk.

Add severity to issue title: `[P0]`, `[P1]`, etc. for anything P1 and above.

## gh CLI Reference

```bash
# Create issue (interactive)
gh issue create

# Create issue with all fields
gh issue create \
  --title "feat: add rate limiting to /api/v1/export" \
  --body-file issue-body.md \
  --label "enhancement,api" \
  --assignee "@me" \
  --milestone "v2.1"

# Create from heredoc (no temp file needed)
gh issue create --title "fix: null pointer in PaymentService.charge" --body "$(cat <<'EOF'
## Description
...
EOF
)"

# List, filter, search
gh issue list --label "bug" --state open --assignee "@me"
gh issue list --search "is:open label:regression sort:created-desc"

# View and edit
gh issue view 42
gh issue edit 42 --add-label "priority:high" --remove-label "needs-triage"

# Close with comment
gh issue close 42 --comment "Fixed in #87. Verified in staging."

# Reopen
gh issue reopen 42 --comment "Regression in v2.3 — reopening."

# Pin critical issues
gh issue pin 42

# Create in another repo
gh issue create --repo org/other-repo --title "..." --body "..."

# Bulk label
gh issue list --label "needs-triage" --json number --jq '.[].number' | \
  xargs -I{} gh issue edit {} --add-label "bug" --remove-label "needs-triage"
```

## Bug Report Template

```markdown
## Description
One sentence: what breaks, under what conditions.

## Steps to Reproduce
1. Go to `/settings/billing`
2. Click "Update card"
3. Enter card number `4000 0000 0000 0002` (decline test card)
4. Submit the form

## Expected Behavior
Error toast: "Card declined. Please try a different card."

## Actual Behavior
Spinner runs indefinitely. Network tab shows `POST /api/v1/charges` hanging.
Console: `Uncaught TypeError: Cannot read property 'status' of undefined`

## Environment
- OS: macOS 15.2
- Browser: Chrome 132 / Node 22.3
- App version / commit: v2.4.1 / `a3f9b12`
- Relevant config: `STRIPE_ENV=test`

## Logs / Screenshots
<details>
<summary>Stack trace</summary>

```
TypeError: Cannot read property 'status' of undefined
  at handleChargeError (payments.ts:214)
  ...
```
</details>

## Workaround
None found. All card submissions are broken in test mode.

## Acceptance Criteria
- [ ] Declined card returns 402 with user-facing error message
- [ ] Spinner stops on error
- [ ] No console errors thrown
```

## Feature Request Template

```markdown
## Problem
Describe the pain point without prescribing the solution.
"As a team admin, I cannot revoke individual API keys without deleting the entire
integration — so a single compromised key forces us to rotate all integrations."

## Proposed Solution
What you want to happen.
"Add per-key revocation on the API Keys settings page. Revoked keys return 401
immediately; no grace period."

## Alternatives Considered
- Short-lived keys (doesn't solve the emergency revoke case)
- IP allowlisting (different problem)

## Acceptance Criteria
- [ ] Admin can revoke any key independently
- [ ] Revoked key returns 401 within 60 seconds
- [ ] Audit log entry created on revocation
- [ ] Key owner notified by email

## Additional Context
Affects all teams using our Zapier integration (~400 accounts per support data).
```

## Regression Bug: Extra Requirements

A regression needs more than a standard bug report:

````markdown
## Regression Details
- **Last good version:** v2.3.0
- **First bad version:** v2.3.1
- **Introducing commit:** `git bisect` result → `c8d1e4f`
  ([commit link](https://github.com/org/repo/commit/c8d1e4f))
- **Introducing PR:** #312 — "Refactor payment middleware"

## Bisect Log
```
git bisect start
git bisect bad HEAD
git bisect good v2.3.0
# ... binary search ...
c8d1e4f is the first bad commit
```
````

Always run `git bisect` before filing a regression — "it worked before" without a
commit is not actionable.

## Flaky Test: Extra Requirements

````markdown
## Failure Rate
~30% of runs over the last 7 days (tracked manually / via CI dashboard).

## CI Run Examples
- Failed: https://github.com/org/repo/actions/runs/12345678
- Failed: https://github.com/org/repo/actions/runs/12345900
- Passed: https://github.com/org/repo/actions/runs/12345800

## Failure Pattern
Fails consistently on: parallel runs, slow CI runners, after `db:reset`.
Never fails locally. Timing-dependent (test passes with `sleep 100ms` injected).

## Log Excerpt (failure)
```
FAIL src/payments/__tests__/charge.test.ts
  ● PaymentService › charge › handles decline
    Expected: "declined"
    Received: undefined
    at Object.<anonymous> (charge.test.ts:42)
```

## Suspected Cause
Async setup in `beforeEach` not awaited before first assertion.
````

## Security Vulnerabilities: Do NOT File Publicly

```
# WRONG — never do this
gh issue create --title "SQL injection in /api/v1/search"

# CORRECT — use GitHub's private security advisory
gh api repos/org/repo/security-advisories \
  --method POST \
  --field summary="SQL injection in search endpoint" \
  --field description="..." \
  --field severity="high"

# Or via UI: repo → Security tab → Advisories → New advisory
```

Security issues must stay private until a patch is released and deployed.
Coordinated disclosure: notify maintainer → agree on fix timeline → publish advisory.

## Performance Issues: Extra Requirements

```markdown
## Benchmark: Before (v2.3.0)
```
GET /api/v1/reports/monthly  p50=120ms  p95=340ms  p99=890ms
(k6: 50 VUs, 5 min, 1000 req/min)
```

## Benchmark: After (v2.4.0)
```
GET /api/v1/reports/monthly  p50=1200ms  p95=4100ms  p99=timeout
```

## Profiling Output
Attached: `profile-v2.4.0.png`
Hotspot: `ReportAggregator.groupBy()` — 83% of CPU time.
Introduced by #318 (full-table scan, missing index on `reports.created_at`).

## Acceptance Criteria
- [ ] p95 ≤ 400ms under same load profile
- [ ] No full-table scans (verified via EXPLAIN ANALYZE)
```

## Linking Issues and PRs

```markdown
# In an issue body — creates a tracked reference
Depends on #42
Blocks #55
Related to #67
Part of #80 (epic)

# In a PR body — auto-closes the issue when PR merges to default branch
Fixes #42
Closes #42
Resolves #42

# Cross-repo
Fixes org/other-repo#42

# In commit message (also closes on merge)
git commit -m "fix: handle declined cards in test mode

Closes #42"
```

Use `Fixes` only in the PR/commit that resolves the issue — not in the issue itself.

## Duplicate Detection Before Filing

```bash
# Search before creating
gh issue list --search "payment decline spinner" --state all
gh issue list --search "card test mode broken" --state all

# Check closed issues too (may have a workaround)
gh issue list --search "charge 402" --state closed
```

If a duplicate exists:
- If open: add a comment with your reproduction details, don't file a new issue
- If closed and regressed: reopen with a comment linking the regression context

## Labels Reference

| Label | Meaning |
|---|---|
| `bug` | Confirmed behavior defect |
| `regression` | Was working, now broken |
| `enhancement` | New capability |
| `chore` | Maintenance, no user-visible change |
| `documentation` | Docs only |
| `performance` | Measurable slowdown |
| `flaky` | Intermittent test failure |
| `security` | Vulnerability (use sparingly on public repos) |
| `good first issue` | Isolated, well-scoped, beginner-friendly |
| `needs-triage` | Filed but not yet classified |
| `needs-repro` | Cannot reproduce without more info |
| `wontfix` | Intentional behavior or out of scope |
| `blocked` | Waiting on another issue or external dependency |
| `breaking-change` | Fix or feature changes existing behavior |

## Edge Cases

### Issue Spans Multiple Repositories
Create a **tracking issue** in the primary repo:
```markdown
## Scope
- [ ] org/frontend#— (UI changes)
- [ ] org/backend#— (API changes)
- [ ] org/infra#— (database migration)

This issue tracks overall completion. Sub-issues are self-contained.
```
File sub-issues in each repo, link back to the tracker.

### Breaking Change
A fix that itself breaks existing behavior needs two issues:
1. The bug issue (what's broken now)
2. A separate `breaking-change` issue documenting the behavior change, migration path, and which major version it ships in

### Issue Has Insufficient Information
Add `needs-repro` label and comment:
```
Thanks for the report. To investigate, we need:
- Exact app version (run `app --version`)
- Browser console output when the error occurs
- Whether this reproduces in an incognito window

Will keep open for 14 days awaiting info.
```

### Data-Loss Bug
Always P0. Beyond the standard bug template:
- Quantify scope: how many records, which users, time window
- Identify if the data is recoverable (backups, event log, audit trail)
- Document any immediate mitigation applied

### Issue is Actually a Support Request
Close with:
```
This looks like a configuration question rather than a bug.
Please open a support ticket at support.example.com or ask in #help on Discord.
Closing to keep the issue tracker focused on confirmed defects.
```

### Cross-Platform Bug (Only Fails on Windows/Linux)
```markdown
## Platform
- Fails on: Windows 11 (PowerShell 5.1, path separator `\`)
- Passes on: macOS 15, Ubuntu 22.04

## Root Cause Hypothesis
Path concatenation uses hardcoded `/` — breaks on Windows.
Candidate line: `config.ts:88`
```

## Red Flags

- **Title is a symptom, not a location** — "App crashes" tells nothing; "NullPointerException in PaymentService.charge when card is declined" is actionable
- **No reproduction steps** — "It doesn't work" forces the maintainer to reverse-engineer the bug; every bug needs numbered repro steps
- **Filing a security vuln as a public issue** — exposure before a patch is deployed can cause immediate harm; always use private advisories
- **Regression without a bisect** — "it worked last month" is impossible to act on; run `git bisect` and identify the introducing commit before filing
- **Flaky test filed as a bug** — flaky tests need failure rate and CI run links, not just a one-time failure screenshot
- **Feature request with no problem statement** — "add dark mode" without explaining who needs it and why will be deprioritized or misbuilt
- **Performance issue with no benchmark** — "it's slow" requires before/after numbers and a profiling output; without data it can't be triaged
- **Duplicate filed without searching first** — adds noise, splits discussion, wastes maintainer time; always search `--state all` before filing
- **Acceptance criteria missing checkboxes** — prose acceptance criteria can't be tracked; always use `- [ ]` items so progress is visible

## Checklist

- [ ] Searched existing issues (`--state all`) before filing to detect duplicates
- [ ] Title is specific: what breaks, where, under what condition (not "it doesn't work")
- [ ] Issue type identified and correct label applied
- [ ] Severity classified (P0–P3); title prefixed for P0/P1
- [ ] Bug: numbered reproduction steps that a stranger can follow
- [ ] Bug: expected vs actual behavior stated explicitly
- [ ] Bug: environment captured (OS, version, browser, config)
- [ ] Regression: introducing commit identified via `git bisect`
- [ ] Flaky test: failure rate and CI run links included
- [ ] Performance: benchmark numbers before/after attached
- [ ] Security: filed as private advisory, NOT a public issue
- [ ] Feature: problem statement written before solution
- [ ] Acceptance criteria written as `- [ ]` checkboxes
- [ ] Related issues and PRs linked (`Blocks`, `Depends on`, `Related to`)
- [ ] Correct milestone set if fix is version-targeted
- [ ] Assignee set if ownership is known at filing time

> See also: `development-workflow` (branch naming, commit conventions, PR process)
> See also: `ci-cd` (flaky test triage in GitHub Actions, workflow run links)