Github Issues

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

# 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 
Stack trace

TypeError: Cannot read property 'status' of undefined at handleChargeError (payments.ts:214) ...

## 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

## 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)

• 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. (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

## 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

# 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

# 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:

## 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)

## 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kid-sid
• Source: kid-sid/claude-spellbook
• License: MIT

Install and usage instructions live in the source repository linked above.