Issue Finder

GitHub Issue Finder & Analyzer

Systematically discover and evaluate GitHub issues for open source contribution opportunities.

Core Workflow

1. Issue Discovery

Search for issues using GitHub CLI:

# Find good first issues
gh issue list --repo owner/repo --label "good first issue" --state open

# Find help wanted issues
gh issue list --repo owner/repo --label "help wanted" --state open

# Find bug issues
gh issue list --repo owner/repo --label "bug" --state open

# Find feature requests
gh issue list --repo owner/repo --label "enhancement" --state open

# Search across multiple repos
gh search issues --label "good first issue" --state open --limit 20

Key labels to search:

• good first issue - Beginner-friendly
• help wanted - Maintainers seeking contributors
• bug - Defects needing fixes
• enhancement / feature - New functionality
• documentation - Doc improvements
• performance - Performance optimizations

2. Issue Evaluation Framework

Read the referenced evaluation criteria: references/evaluation-criteria.md

Feasibility Assessment

Bug Fix Feasibility:

1. Reproducibility - Can you reproduce the issue?
2. Root Cause - Is the cause identifiable from issue description/code?
3. Scope - How many files/components affected?
4. Dependencies - Does fix require changes to external dependencies?
5. Test Coverage - Are there existing tests? Can you write tests?

Feature Implementation Feasibility:

1. Clarity - Is the feature well-defined?
2. Alignment - Does it fit project's roadmap/vision?
3. Complexity - New code vs. modifying existing code?
4. Breaking Changes - Will it break existing functionality?
5. Maintainability - Long-term maintenance implications?

Value Assessment

Contribution Value Score (1-10):

Scoring Guide:

• 9-10: High impact, great learning, active maintainers
• 7-8: Good contribution opportunity
• 5-6: Moderate value, consider carefully
• 1-4: Low ROI, skip unless specific reason

3. Issue Analysis Process

Step 1: Gather Information

# Get issue details
gh issue view <issue-number> --repo owner/repo

# Check issue comments/discussion
gh issue view <issue-number> --repo owner/repo --comments

# Check linked PRs
gh pr list --repo owner/repo --search "fixes #<issue-number>"

# Check project files
gh api repos/owner/repo/contents

Step 2: Analyze Codebase Context

# Clone or navigate to repo
cd /path/to/repo

# Understand structure
find . -type f -name "*.ts" | head -20

# Check recent commits
git log --oneline -20

# Look for similar patterns
grep -r "related_functionality" --include="*.ts"

Step 3: Generate Analysis Report

Use the template: references/analysis-template.md

Report Structure:

1. Issue Summary
2. Root Cause Analysis (for bugs) / Feature Scope (for features)
3. Proposed Solution Approach
4. Estimated Effort
5. Risk Assessment
6. Learning Opportunities
7. Recommendation

4. Decision Framework

Go/No-Go Checklist:

✅ Proceed if:

• Issue is well-documented
• Maintainers are responsive (< 1 week avg)
• You understand the affected code
• Effort matches available time
• Clear path to solution

❌ Skip if:

• Issue is unclear or lacks details
• Maintainers unresponsive for months
• Requires deep domain expertise you lack
• Breaking changes or major refactoring needed
• No clear acceptance criteria

5. Execution Strategy

Once you've identified a good issue:

1. Comment on issue - Express interest, ask clarifying questions
2. Wait for maintainer feedback - Get assigned before starting
3. Create feature branch - fix/issue-number-description
4. Implement incrementally - Small, focused commits
5. Test thoroughly - Unit tests, integration tests
6. Document changes - Update docs if needed
7. Submit PR - Reference issue, describe changes

Advanced Techniques

Pattern-Based Issue Finding

Search for specific code patterns that indicate common issues:

# Find TODO comments
gh search code "TODO" --repo owner/repo

# Find deprecated patterns
gh search code "deprecated" --repo owner/repo --language TypeScript

# Find error handling gaps
gh search code "catch.*{}" --repo owner/repo

Project Health Indicators

Before investing time, check project health:

# Recent activity
gh repo view owner/repo --json updatedAt,pushedAt

# Contributor count
gh api repos/owner/repo/contributors --paginate | jq length

# Open issues/PRs ratio
gh repo view owner/repo --json openIssuesCount,openPullRequestsCount

# CI/CD status
gh api repos/owner/repo/actions/workflows

Healthy Project Signs:

• Recent commits (within days/weeks)
• Active PR reviews
• CI/CD passing
• Maintainers respond to issues/PRs
• Clear contributing guidelines

Batch Analysis

For analyzing multiple issues efficiently:

# Export issues to JSON for analysis
gh issue list --repo owner/repo --state open --limit 50 --json number,title,labels,state,createdAt,comments

# Use the analysis script
python3 scripts/analyze_issues.py --repo owner/repo --output report.md

Best Practices

1. Start Small - Begin with good first issue or documentation
2. Understand Before Coding - Read code, understand patterns
3. Communicate Early - Comment on issue before starting work
4. Test Your Changes - Write tests, run existing tests
5. Follow Conventions - Match project's coding style
6. Be Patient - Reviews take time, iterate on feedback

Common Pitfalls

• Starting work without maintainer acknowledgment
• Missing existing PRs that address the same issue
• Underestimating scope or complexity
• Ignoring project conventions and patterns
• Submitting large, unfocused PRs

Quick Reference

Issue Labels Priority (easiest to hardest):

1. documentation → good first issue → help wanted
2. bug (small scope) → bug (medium scope)
3. enhancement (small) → feature (medium) → feature (large)

Time Estimation Guide:

• Hours: Documentation, typo fixes, config changes
• Days: Small bug fixes, minor features, test additions
• Weeks: Medium bugs, moderate features, refactoring
• Months: Large features, architectural changes

Success Indicators:

• Clear issue description
• Reproducible steps (for bugs)
• Maintainer engagement
• Existing similar PRs to learn from
• Well-structured codebase