Issue Finder

GitHub Issue Finder & Analyzer

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

Core Workflow

1. Issue Discovery

1.1 Positive Label Detection (v1.6.0 新增)

核心概念: 现代项目使用自动化标签系统标记 issue 的贡献价值。优先寻找带有正向标签的 issues。

正向标签分类:

OpenClaw 正向标签示例:

# ClawSweeper 自动化标签（高价值信号）
gh issue list --repo openclaw/openclaw --label "clawsweeper:fix-shape-clear" --state open
gh issue list --repo openclaw/openclaw --label "clawsweeper:queueable-fix" --state open
gh issue list --repo openclaw/openclaw --label "clawsweeper:source-repro" --state open

# 影响评估标签
gh issue list --repo openclaw/openclaw --label "impact:auth-provider" --state open

# 价值评级标签（🦞 diamond lobster = 最高价值）
gh issue list --repo openclaw/openclaw --label "issue-rating: 🦞 diamond lobster" --state open
gh issue list --repo openclaw/openclaw --label "issue-rating: *" --state open

通用正向标签发现流程:

# 1. 先探索仓库的标签系统
gh api repos/owner/repo/labels --paginate | jq '.[].name'

# 2. 识别正向标签模式
# 查找包含以下关键词的标签：
# - fix, queue, repro, confirm, impact, rating, value, contribution
# - good, help, welcome, easy, beginner, junior

# 3. 按优先级批量查询
gh issue list --repo owner/repo --state open \
  --label "fix-shape-clear,queueable-fix,source-repro" \
  --json number,title,labels,createdAt

1.2 传统标签发现

# 经典贡献标签
gh issue list --repo owner/repo --label "good first issue" --state open
gh issue list --repo owner/repo --label "help wanted" --state open

# 缺陷和功能
gh issue list --repo owner/repo --label "bug" --state open
gh issue list --repo owner/repo --label "enhancement" --state open

# 跨仓库搜索
gh search issues --label "good first issue,help wanted" --state open --limit 20

1.3 标签优先级矩阵

Tier 1 - 立即行动 (维护者明确标记为值得修复):

• *:fix-shape-* / *:queueable-* / *:queue_fix_pr
• *:source-repro / confirmed / reproducible
• issue-rating: 🦞 / value:high / priority:critical

Tier 2 - 高优先级 (有明确贡献信号):

• good first issue / help wanted / contributions welcome
• impact:* / severity:high
• scope:* (清晰范围)

Tier 3 - 标准候选:

• bug / enhancement / feature
• documentation / performance

Tier 4 - 谨慎评估:

• 无正向标签的普通 issue
• 需要自行判断价值

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  --repo owner/repo

# Check issue comments/discussion
gh issue view  --repo owner/repo --comments

# Check linked PRs
gh pr list --repo owner/repo --search "fixes #"

# 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