Issue Cleaner Master

Analyze GitHub issues in the current repository and filter high-quality issues suitable for contribution.

Workflow

Step 1: Get Repository Info

Get the current repository’s owner and repo name:

gh repo view --json nameWithOwner --jq '.nameWithOwner'

Parse into {owner} and {repo} variables for subsequent use.

Validation: Ensure the output is in owner/repo format. If empty or error, verify you’re in a git repository with a GitHub remote.

Step 2: Fetch Issue Data

Use GraphQL API to fetch all open issues (supports pagination, no limit):

gh api graphql --paginate -f query='
query($endCursor: String) {
  repository(owner: "{owner}", name: "{repo}") {
    issues(states: OPEN, first: 100, after: $endCursor) {
      pageInfo { hasNextPage endCursor }
      nodes {
        number
        title
        url
        createdAt
        updatedAt
        labels(first: 20) { nodes { name } }
        assignees(first: 10) { nodes { login } }
      }
    }
  }
}'

Validation: Verify response contains data.repository.issues.nodes array. Handle errors:

• 401/403: Run gh auth status to check authentication
• Rate limit: Wait and retry, or reduce first parameter
• Empty nodes: Valid for new repos, proceed with empty issue list

Step 3: Detect Issues with Linked PRs

Fetch all open PRs and their linked issues via closingIssuesReferences:

gh api graphql --paginate -f query='
query($endCursor: String) {
  repository(owner: "{owner}", name: "{repo}") {
    pullRequests(states: OPEN, first: 100, after: $endCursor) {
      pageInfo { hasNextPage endCursor }
      nodes {
        number
        closingIssuesReferences(first: 10) {
          nodes { number }
        }
      }
    }
  }
}'

Also fetch recently merged PRs (to exclude already-fixed issues):

gh api graphql -f query='
{
  repository(owner: "{owner}", name: "{repo}") {
    pullRequests(states: MERGED, first: 100, orderBy: {field: UPDATED_AT, direction: DESC}) {
      nodes {
        number
        closingIssuesReferences(first: 10) {
          nodes { number }
        }
      }
    }
  }
}'

Aggregate all PR-linked issue numbers into two categories:

• issues_with_open_pr: Issues with in-progress PRs
• issues_with_merged_pr: Issues fixed by merged PRs

Validation: Both queries should return valid arrays. If closingIssuesReferences is empty for all PRs, that’s valid (PRs may not link issues).

Step 4: Apply Filtering Rules

Exclusion Conditions (exclude if any match):

Special Inclusion (include even if assigned):

Mark these issues as [Stale] in output, suggesting users may politely ask if help is needed.

Non-Code Contribution Detection (smart detection, not just labels):

1. Label signals (strong): Contains question/support/duplicate/wontfix/invalid
2. Title patterns (medium):
   • Ends with ?
   • Starts with “How to”/”How do I”/”Why does”/”What is”
   • Contains “[Question]”/”[Help]”/”[Support]” prefix
3. Combined judgment: If only title signals exist without label signals, use gh issue view {number} --json body to read first 500 chars of body for further judgment

Conservative Principle: When uncertain, keep the issue in the list for user judgment.

Step 5: Group by Priority

Refer to references/priority-labels.md for priority definitions:

Step 6: Generate Report Files

Must generate two files in current working directory:

6.1 issues-report.json (Machine-readable)

Complete audit data for all issues. See references/output-examples.md for detailed schema and examples.

Key fields:

• metadata: Repository info, scan time, counts
• issues[]: Each issue with included, priority, status, and include_reason/exclude_reason

6.2 issues-report.md (Human-readable)

Grouped by priority with Markdown tables. See references/output-examples.md for format template.

Key sections:

• Priority groups (P0-P5) with issue tables
• Summary statistics
• Exclusion reasons distribution

Skip empty priority groups.

Hard Constraints

• Use gh CLI GraphQL API to ensure complete data retrieval
• Only analyze the GitHub project corresponding to the current git repository
• Read-only operations, do not modify any issue status
• PR linkage detection uses official closingIssuesReferences field, do not parse PR body
• Must generate both issues-report.json and issues-report.md files
• Every issue must include include_reason or exclude_reason for auditability

Error Recovery