Skill: linux2010/issue-finder (version 1.0.0)

--- name: issue-finder description: "Discover valuable GitHub issues and analyze bug fix feasibility and feature implementation potential. Use when: (1) Finding good issues to contribute to open source projects, (2) Analyzing bug complexity and fix difficulty, (3) Evaluating feature request feasibility, (4) Assessing contribution value and learning opportunities, (5) Searching for issues by labels, complexity, or project type." --- # 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: ```bash # 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](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): | Factor | Weight | Criteria | |--------|--------|----------| | Impact | 30% | User-facing vs internal, number of affected users | | Learning | 25% | New skills/concepts learned | | Community | 20% | Maintainer responsiveness, community activity | | Complexity | 15% | Time investment vs. value gained | | Portfolio | 10% | Demonstrable value for portfolio/career | **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 ```bash # 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 ```bash # 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](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: ```bash # 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: ```bash # 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: ```bash # 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

path: references/analysis-template.md
content: # Issue Analysis Report Template

Use this template for structured issue analysis.

---

## Issue Overview

**Repository**: owner/repo
**Issue Number**: #XXX
**Title**: [Issue Title]
**Type**: Bug / Feature / Enhancement / Documentation
**Created**: YYYY-MM-DD
**Last Updated**: YYYY-MM-DD

---

## Issue Summary

### Description
[One-paragraph summary of what the issue is about]

### Labels
- `label1`
- `label2`

### Current Status
- [ ] Needs triage
- [ ] Confirmed
- [ ] In progress
- [ ] Blocked

---

## Root Cause Analysis (Bug)

### Symptoms
[What the user experiences]

### Expected Behavior
[What should happen]

### Actual Behavior
[What actually happens]

### Root Cause
[Technical explanation of why this happens]

### Affected Components
- Component A
- Component B

### Code References
- `file1.ts:line_number` - Description
- `file2.ts:line_number` - Description

---

## Feature Scope (Feature Request)

### Problem Statement
[What problem does this feature solve?]

### Proposed Solution
[What should be implemented?]

### Use Cases
1. [Use case 1]
2. [Use case 2]

### Acceptance Criteria
- [ ] Criteria 1
- [ ] Criteria 2

### Out of Scope
[What this feature will NOT include]

---

## Proposed Approach

### Solution Strategy
1. Step 1
2. Step 2
3. Step 3

### Code Changes Needed
- [ ] File 1: Description of changes
- [ ] File 2: Description of changes
- [ ] New file: Description

### Test Strategy
- [ ] Unit tests for X
- [ ] Integration tests for Y
- [ ] Manual testing steps

---

## Effort Estimation

### Time Estimate
- Research: X hours
- Implementation: Y hours
- Testing: Z hours
- Documentation: W hours
- **Total**: T hours

### Complexity Level
- [ ] Tiny (hours)
- [ ] Small (days)
- [ ] Medium (weeks)
- [ ] Large (weeks-months)

### Files Affected
- Count: N files
- Scope: frontend/backend/both

---

## Risk Assessment

### Technical Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| Risk 1 | H/M/L | H/M/L | How to mitigate |

### Breaking Changes
- [ ] No breaking changes
- [ ] Minor breaking changes (describe)
- [ ] Major breaking changes (describe)

### Dependencies
- [ ] No new dependencies
- [ ] New dependencies needed: [list]
- [ ] Dependency version changes: [list]

---

## Learning Opportunities

### Technical Skills
- [ ] New technology/framework
- [ ] Design pattern
- [ ] Testing approach
- [ ] Performance optimization

### Domain Knowledge
- [ ] Business logic
- [ ] Industry standard
- [ ] User experience

### Soft Skills
- [ ] Code review process
- [ ] Technical communication
- [ ] Collaboration

---

## Project Health Check

### Maintainer Engagement
- Response time: X days average
- Last maintainer comment: YYYY-MM-DD
- Assigned to: [maintainer username or "unassigned"]

### Community Activity
- Stars: N
- Contributors: N
- Recent commits: N commits in last 30 days
- Open issues: N
- Open PRs: N

### CI/CD Status
- Tests: ✅ Passing / ❌ Failing
- Build: ✅ Passing / ❌ Failing
- Lint: ✅ Passing / ❌ Failing

---

## Feasibility Scores

### Bug Fix Feasibility
| Criterion | Score (1-10) | Notes |
|-----------|--------------|-------|
| Reproducibility | | |
| Root Cause Clarity | | |
| Scope | | |
| Dependencies | | |
| Test Coverage | | |
| **Average** | | |

### Feature Implementation Feasibility
| Criterion | Score (1-10) | Notes |
|-----------|--------------|-------|
| Requirements Clarity | | |
| Project Alignment | | |
| Implementation Complexity | | |
| Breaking Changes | | |
| Maintainability | | |
| **Average** | | |

### Contribution Value
| Criterion | Score (1-10) | Weight | Weighted |
|-----------|--------------|--------|----------|
| Impact | | 30% | |
| Learning | | 25% | |
| Community | | 20% | |
| Complexity | | 15% | |
| Portfolio | | 10% | |
| **Total** | | 100% | |

---

## Recommendation

### Overall Assessment
- Feasibility Score: X/10
- Value Score: X/10
- Risk Level: Low / Medium / High
- Effort Level: Tiny / Small / Medium / Large

### Decision
- [ ] **PROCEED** - Good opportunity, start work
- [ ] **CONSIDER** - Moderate value, evaluate alternatives
- [ ] **SKIP** - Low ROI or high risk

### Rationale
[Why this recommendation?]

### Next Steps
1. [First action]
2. [Second action]
3. [Third action]

---

## Additional Resources

### Related Issues
- #XXX: Related issue
- #XXX: Similar issue

### Related PRs
- #XXX: Previous attempt
- #XXX: Related PR

### Documentation
- [Link to relevant docs]
- [Link to relevant code section]

---

## Analysis Metadata

**Analyzed by**: [Your username]
**Analysis date**: YYYY-MM-DD
**Analysis version**: 1.0
**Confidence level**: High / Medium / Low

path: references/evaluation-criteria.md
content: # Issue Evaluation Criteria

Detailed framework for assessing GitHub issues for contribution value.

## Bug Fix Assessment

### Reproducibility Check

**High Reproducibility** (Score: 9-10):
- Clear step-by-step reproduction instructions
- Includes environment details (OS, version, config)
- Minimal reproduction case provided
- Screenshots/logs attached

**Medium Reproducibility** (Score: 5-8):
- General description of issue
- Some environment context
- Needs investigation to reproduce

**Low Reproducibility** (Score: 1-4):
- Vague description
- Missing environment details
- Cannot reproduce with provided info

### Root Cause Complexity

**Simple** (Score: 9-10):
- Single function/method affected
- Clear cause from error message/stack trace
- Logic error, typo, or missing null check

**Moderate** (Score: 5-8):
- Multiple files/components involved
- Requires understanding of module interaction
- May need debugging or logging

**Complex** (Score: 1-4):
- Architectural or design-level issue
- Multiple systems affected
- Requires deep domain knowledge

### Fix Scope Analysis

| Scope | Files | Risk | Effort |
|-------|-------|------|--------|
| Tiny | 1 | Low | Hours |
| Small | 1-3 | Low-Medium | Days |
| Medium | 3-10 | Medium | Weeks |
| Large | 10+ | High | Weeks-Months |

### Dependency Impact

**Low Impact**:
- No external dependency changes
- Internal changes only
- Backward compatible

**Medium Impact**:
- Version bumps needed
- API changes within module
- Some breaking changes

**High Impact**:
- Major dependency updates
- Breaking API changes
- Requires migration path

## Feature Implementation Assessment

### Clarity of Requirements

**Clear Requirements** (Score: 9-10):
- Detailed specification
- Acceptance criteria defined
- Mockups or examples provided
- Use cases documented

**Moderate Clarity** (Score: 5-8):
- General idea described
- Some requirements implied
- Needs design discussion

**Unclear Requirements** (Score: 1-4):
- Vague feature request
- No acceptance criteria
- Requires significant design work

### Alignment with Project

**High Alignment**:
- Fits project's stated goals
- Maintainers have expressed interest
- Similar features exist

**Medium Alignment**:
- Reasonable extension
- May need discussion
- Some maintainer interest

**Low Alignment**:
- Niche use case
- Diverges from project vision
- No maintainer interest shown

### Implementation Complexity

**New Code Path** (easier):
- Adding new function/module
- Minimal changes to existing code
- Clear extension points

**Modifying Existing Code** (harder):
- Refactoring needed
- Breaking changes possible
- Must understand existing patterns

### Breaking Change Risk

**No Breaking Changes**:
- Additive only
- New optional features
- Backward compatible

**Minor Breaking Changes**:
- Deprecation needed
- Migration guide required
- Version bump required

**Major Breaking Changes**:
- API rewrites
- Data migration needed
- Significant user impact

## Project Health Indicators

### Maintainer Responsiveness

| Response Time | Score |
|---------------|-------|
| < 24 hours | 10 |
| 1-3 days | 8 |
| 3-7 days | 6 |
| 1-2 weeks | 4 |
| 2-4 weeks | 2 |
| > 1 month | 1 |

### Community Activity

**Active Community** (Score: 9-10):
- Multiple active contributors
- Regular PR reviews
- Recent releases
- Active discussions

**Moderate Activity** (Score: 5-8):
- Some contributors active
- Occasional reviews
- Releases every few months
- Some discussions

**Low Activity** (Score: 1-4):
- Few active contributors
- Slow/no reviews
- No recent releases
- Stale discussions

### Documentation Quality

**Excellent**:
- Clear contributing guidelines
- Well-documented codebase
- Active wiki/docs
- Good code comments

**Adequate**:
- Basic contributing docs
- Some code documentation
- Acceptable comments

**Poor**:
- Missing contributing guidelines
- Undocumented code
- Sparse comments

## Risk Assessment Matrix

### Technical Risk

| Risk Level | Indicators | Mitigation |
|------------|------------|------------|
| Low | Simple fix, well-understood, existing tests | None needed |
| Medium | Moderate complexity, some unknowns | Extra testing, maintainer guidance |
| High | Complex, many unknowns, no tests | Spike/POC first, maintain close coordination |

### Time Risk

| Risk Level | Indicators | Mitigation |
|------------|------------|------------|
| Low | Clear scope, familiar tech stack | Time buffer 10-20% |
| Medium | Some unknowns, partial familiarity | Time buffer 30-50% |
| High | Many unknowns, unfamiliar stack | Time buffer 50-100%, consider spike |

### Social Risk

| Risk Level | Indicators | Mitigation |
|------------|------------|------------|
| Low | Responsive maintainers, active community | Standard communication |
| Medium | Somewhat responsive, moderate activity | Regular updates, ask questions early |
| High | Unresponsive, inactive or toxic community | Consider alternative projects |

## Decision Matrix

### When to Proceed

- Feasibility score ≥ 6
- Value score ≥ 7
- Project health score ≥ 6
- All risks manageable
- Time investment acceptable

### When to Consider Carefully

- Feasibility score 4-5
- Value score 5-6
- Project health score 4-5
- Some risks concerning
- Consider partial approach

### When to Skip

- Feasibility score < 4
- Value score < 5
- Project health score < 4
- High risks
- Better alternatives exist

path: scripts/analyze_issues.py
content: #!/usr/bin/env python3
"""
GitHub Issue Analyzer - Analyze issues for contribution potential.

Usage:
    python analyze_issues.py --repo owner/repo --issue 123
    python analyze_issues.py --repo owner/repo --all --limit 20
    python analyze_issues.py --repo owner/repo --labels "good first issue,help wanted"
"""

import argparse
import json
import subprocess
import sys
from datetime import datetime, timezone
from typing import Any


def run_gh_command(args: list[str]) -> dict[str, Any] | list[Any] | None:
    """Run a gh CLI command and return JSON output."""
    try:
        result = subprocess.run(
            ["gh"] + args,
            capture_output=True,
            text=True,
            check=True,
        )
        return json.loads(result.stdout) if result.stdout else None
    except subprocess.CalledProcessError as e:
        print(f"Error running gh command: {e.stderr}", file=sys.stderr)
        return None
    except json.JSONDecodeError:
        return None


def analyze_issue_health(issue: dict[str, Any]) -> dict[str, Any]:
    """Analyze health indicators for a single issue."""
    created = datetime.fromisoformat(issue["createdAt"].replace("Z", "+00:00"))
    updated = datetime.fromisoformat(issue["updatedAt"].replace("Z", "+00:00"))
    now = datetime.now(timezone.utc)

    age_days = (now - created).days
    time_since_update = (now - updated).days

    labels = [label["name"] for label in issue.get("labels", [])]

    return {
        "number": issue["number"],
        "title": issue["title"],
        "age_days": age_days,
        "time_since_update": time_since_update,
        "comment_count": issue.get("comments", 0),
        "labels": labels,
        "is_good_first_issue": "good first issue" in labels,
        "is_help_wanted": "help wanted" in labels,
        "has_bug_label": "bug" in labels,
        "has_enhancement_label": "enhancement" in labels,
        "health_score": calculate_health_score(age_days, time_since_update, issue.get("comments", 0)),
    }


def calculate_health_score(age_days: int, time_since_update: int, comments: int) -> int:
    """Calculate a health score for an issue (1-10)."""
    score = 10

    # Fresh issues are better
    if age_days > 365:
        score -= 3
    elif age_days > 180:
        score -= 2
    elif age_days > 90:
        score -= 1

    # Recent activity is good
    if time_since_update > 60:
        score -= 2
    elif time_since_update > 30:
        score -= 1

    # Some discussion is good
    if comments == 0:
        score -= 1
    elif comments > 10:
        score -= 1  # Too much discussion might indicate complexity

    return max(1, min(10, score))


def analyze_issue_complexity(issue: dict[str, Any]) -> str:
    """Estimate issue complexity based on labels and description."""
    labels = [label["name"] for label in issue.get("labels", [])]

    if "good first issue" in labels or "documentation" in labels:
        return "Tiny-Small"
    elif "help wanted" in labels and "bug" in labels:
        return "Small-Medium"
    elif "enhancement" in labels:
        return "Medium"
    elif "feature" in labels:
        return "Medium-Large"
    else:
        return "Unknown"


def generate_report(repo: str, issues: list[dict[str, Any]]) -> str:
    """Generate a markdown report from analyzed issues."""
    report_lines = [
        f"# Issue Analysis Report for {repo}",
        f"\nGenerated: {datetime.now(timezone.utc).isoformat()}",
        f"\n## Summary",
        f"\nTotal issues analyzed: {len(issues)}",
        "\n## Issues by Health Score\n",
        "| # | Title | Score | Complexity | Age (days) | Labels |",
        "|---|-------|-------|------------|------------|--------|",
    ]

    sorted_issues = sorted(issues, key=lambda x: x["health_score"], reverse=True)

    for issue in sorted_issues:
        labels_str = ", ".join(issue["labels"][:3])
        if len(issue["labels"]) > 3:
            labels_str += "..."
        report_lines.append(
            f"| #{issue['number']} | {issue['title'][:40]}... | "
            f"{issue['health_score']}/10 | {issue.get('complexity', 'Unknown')} | "
            f"{issue['age_days']} | {labels_str} |"
        )

    report_lines.extend([
        "\n## Recommendations\n",
        "### High Priority Issues\n",
    ])

    high_priority = [i for i in sorted_issues if i["health_score"] >= 7 and i["is_good_first_issue"]]
    for issue in high_priority[:5]:
        report_lines.append(f"- #{issue['number']}: {issue['title']}")

    if not high_priority:
        report_lines.append("No high priority issues found.")

    report_lines.extend([
        "\n### Good for Learning\n",
    ])

    learning_issues = [i for i in sorted_issues if i["is_help_wanted"] or i["is_good_first_issue"]]
    for issue in learning_issues[:5]:
        report_lines.append(f"- #{issue['number']}: {issue['title']}")

    if not learning_issues:
        report_lines.append("No beginner-friendly issues found.")

    return "\n".join(report_lines)


def main():
    parser = argparse.ArgumentParser(description="Analyze GitHub issues for contribution potential")
    parser.add_argument("--repo", required=True, help="Repository in owner/repo format")
    parser.add_argument("--issue", type=int, help="Specific issue number to analyze")
    parser.add_argument("--all", action="store_true", help="Analyze all open issues")
    parser.add_argument("--limit", type=int, default=20, help="Limit number of issues to analyze")
    parser.add_argument("--labels", help="Filter by labels (comma-separated)")
    parser.add_argument("--output", help="Output file for report (default: stdout)")

    args = parser.parse_args()

    # Build gh command
    cmd_args = [
        "issue", "list",
        "--repo", args.repo,
        "--state", "open",
        "--limit", str(args.limit),
        "--json", "number,title,labels,createdAt,updatedAt,comments,state",
    ]

    if args.labels:
        for label in args.labels.split(","):
            cmd_args.extend(["--label", label.strip()])

    if args.issue:
        cmd_args = [
            "issue", "view",
            str(args.issue),
            "--repo", args.repo,
            "--json", "number,title,labels,createdAt,updatedAt,comments,state,body",
        ]
        issue_data = run_gh_command(cmd_args)
        if issue_data:
            analyzed = analyze_issue_health(issue_data)
            analyzed["complexity"] = analyze_issue_complexity(issue_data)
            issues = [analyzed]
        else:
            print("Failed to fetch issue", file=sys.stderr)
            sys.exit(1)
    else:
        issues_data = run_gh_command(cmd_args)
        if not issues_data:
            print("Failed to fetch issues", file=sys.stderr)
            sys.exit(1)

        issues = []
        for issue in issues_data:
            analyzed = analyze_issue_health(issue)
            analyzed["complexity"] = analyze_issue_complexity(issue)
            issues.append(analyzed)

    # Generate report
    report = generate_report(args.repo, issues)

    if args.output:
        with open(args.output, "w") as f:
            f.write(report)
        print(f"Report written to {args.output}")
    else:
        print(report)


if __name__ == "__main__":
    main()

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)