github-issue-autodetect

GitHub Issue Auto-Detection

Expert guidance for automatically detecting GitHub issues that staged changes may fix or close, ensuring proper issue linkage in commit messages.

Core Expertise

• Issue Detection: Match staged changes to open issues
• Keyword Selection: Choose appropriate closing vs reference keywords
• Context Analysis: Parse issue titles, bodies, and labels for relevance
• File Path Matching: Correlate changed files to issue descriptions

Detection Workflow

Step 1: Fetch Open Issues

# Get open issues with relevant metadata (using gh CLI)
gh issue list --state open --json number,title,body,labels --limit 50

# Or filter by specific labels for targeted detection
gh issue list --state open --label bug --json number,title,body
gh issue list --state open --label enhancement --json number,title,body

Step 2: Analyze Staged Changes

# Get list of changed files
git diff --cached --name-only

# Get detailed diff for content analysis
git diff --cached

# Get summary of changes
git diff --cached --stat

Step 3: Match Issues to Changes

Analyze staged changes against issues using these heuristics:

Signal	Weight	Example
File path in issue body	High	Issue mentions src/auth/login.ts, diff includes that file
Error message match	High	Issue title contains error text found in diff
Component/scope match	Medium	Issue labeled auth, changes are in src/auth/
Keyword overlap	Medium	Issue mentions "login", diff modifies login logic
Function name match	Medium	Issue references validateToken(), diff modifies it

Detection Algorithm

For each staged file:
  1. Extract file path components (directory, filename, extension)
  2. Extract modified function/class names from diff
  3. Extract error messages or string literals from diff

For each open issue:
  1. Parse title for keywords, file references, error messages
  2. Parse body for code snippets, file paths, stack traces
  3. Check labels for component/area tags

Score each (file, issue) pair:
  - +3 points: Exact file path match
  - +2 points: Error message or function name match
  - +1 point: Directory/component match
  - +1 point: Keyword overlap (>2 significant words)

Report issues with score >= 2 as potential matches

Keyword Selection Guide

Closing Keywords (Auto-Close on Merge)

Use when the commit fully resolves the issue:

Keyword	Use Case
Fixes #N	Bug fixes - something was broken, now it works
Closes #N	Feature completion - requested feature is implemented
Resolves #N	General resolution - issue is addressed

Reference Keywords (Link Without Closing)

Use when the commit relates to but doesn't fully resolve:

Keyword	Use Case
Refs #N	Partial progress toward issue
Related to #N	Tangentially related changes
See #N	Context or discussion reference
Part of #N	One of multiple commits for an issue

Decision Tree

Is this commit the FINAL fix for the issue?
├─ YES → Is it a bug fix?
│        ├─ YES → Use "Fixes #N"
│        └─ NO → Use "Closes #N"
└─ NO → Does it make progress on the issue?
         ├─ YES → Use "Refs #N"
         └─ NO → Use "Related to #N" or omit

Common Patterns

Bug Fix Detection

# Issue: "Login fails with 'invalid token' error"
# Staged changes in: src/auth/token.ts

# Detection signals:
# - File path: src/auth/* matches "Login" context
# - Error message: "invalid token" may appear in diff
# - Issue label: bug

# Suggested: Fixes #123

Feature Implementation Detection

# Issue: "Add dark mode support"
# Staged changes in: src/theme/dark-mode.ts, src/components/ThemeToggle.tsx

# Detection signals:
# - New files with relevant names
# - Issue label: enhancement
# - Keywords: "dark mode", "theme"

# Suggested: Closes #456

Partial Work Detection

# Issue: "Refactor authentication system"
# Staged changes in: src/auth/oauth.ts (but more work needed)

# Detection signals:
# - File path matches scope
# - Issue is large (multiple sub-tasks in body)
# - Other files mentioned in issue not yet changed

# Suggested: Refs #789

Integration Commands

Quick Issue Scan Before Commit

# One-liner to show relevant issues for staged changes
gh issue list --state open --json number,title,labels --limit 20 | \
  jq -r '.[] | "#\(.number): \(.title)"'

Detailed Issue Analysis

# Get full issue details for matching
gh issue view <number> --json title,body,labels,assignees

# Search issues by keyword
gh issue list --search "keyword in:title,body" --state open

File-Based Issue Search

# Search for issues mentioning specific file
gh issue list --search "filename.ts in:body" --state open

# Search for issues mentioning directory
gh issue list --search "src/auth in:body" --state open

Agentic Optimizations

Context	Command
Quick issue list	gh issue list --state open --json number,title -L 20
Bug issues only	gh issue list --state open --label bug --json number,title
Search by keyword	gh issue list --search "keyword" --state open --json number,title
Full issue detail	gh issue view N --json title,body,labels

Output Format for Agent

When reporting detected issues, use this format:

Detected potentially related issues:

HIGH CONFIDENCE:
- #123 "Login fails with invalid token" → Fixes #123
  Match: File path src/auth/token.ts, error message match

MEDIUM CONFIDENCE:
- #456 "Improve auth error handling" → Refs #456
  Match: Directory src/auth/, keyword "error"

Suggested commit message footer:
Fixes #123
Refs #456

Best Practices

1. Always check for related issues before committing
2. Prefer Fixes over Closes for bug fixes (clearer intent)
3. Use Refs for partial work to maintain traceability without premature closure
4. Include multiple references when a commit addresses several issues
5. Verify issue state - don't reference already-closed issues unless reopening
6. Cross-reference PRs - issues may already have linked PRs in progress

Edge Cases

No Matching Issues Found

If no open issues match the staged changes:

• Consider if an issue should be created first (for traceability)
• For trivial fixes, commit without issue reference is acceptable
• For significant changes, create issue retroactively and link in PR

Multiple Matching Issues

When several issues relate to the same changes:

# Close all that are fully resolved
Fixes #123, fixes #124, fixes #125

# Or mix closing and reference keywords
Fixes #123
Refs #124, #125

Cross-Repository Issues

# Reference issue in another repository
Fixes owner/other-repo#42

# Common for monorepo or multi-repo projects