issue-prioritizer

name	issue-prioritizer
description	Prioritize GitHub issues by ROI, solution sanity, and architectural impact. Identifies quick wins, over-engineered proposals, and actionable bugs. Use for issue triage, contributor matching, and filtering non-actionable items. Read-only — never modifies repositories.

Issue Prioritizer

Analyze issues from a GitHub repository and rank them by Adjusted Score — ROI penalized by Tripping Scale (solution sanity), Architectural Impact, and Actionability.

This is a read-only skill. It analyzes and presents information. The user makes all decisions.

Requirements

• gh CLI authenticated (gh auth login)

Instructions

Step 1: Get Repository

If the user didn't specify a repository, ask which one to analyze (format: owner/repo).

Step 2: Fetch Issues

gh issue list --repo {owner/repo} --state open --limit {limit} --json number,title,body,labels,createdAt,comments,url

Default limit is 30. Store the full JSON response.

Error handling:

• Auth error → tell user to run gh auth login
• Rate limited → inform user, suggest reducing --limit
• Repo not found → check format owner/repo
• No issues → report and exit
• Missing fields → treat null/missing body and labels as empty

Step 3: Filter Issues with Existing PRs

Note: If user specified --include-with-prs, skip this entire step and proceed to Step 4 with all fetched issues.

Before analyzing, check for open PRs that already address issues to avoid duplicate work.

gh pr list --repo {owner/repo} --state open --json number,title,body,url

Detect linked issues using ALL of these methods:

Method 1 — Explicit Keywords (high confidence): Scan PR title and body (case-insensitive):

• fixes #N, fix #N, fixed #N
• closes #N, close #N, closed #N
• resolves #N, resolve #N, resolved #N

Method 2 — Issue References (medium confidence):

• #N anywhere in text
• issue N, issue #N, related to #N, addresses #N

Method 3 — Title Similarity (fuzzy): Normalize titles (lowercase, remove punctuation/common words). If 70%+ word overlap → likely linked.

Method 4 — Semantic Matching (ambiguous cases): Extract key terms from issue (error names, function names, components). Check if PR body discusses same things.

Confidence icons:

• 🔗 Explicit link (fixes/closes/resolves)
• 📎 Referenced (#N mentioned)
• 🔍 Similar title (fuzzy match)
• 💡 Semantic match (same components)

Remove linked issues from analysis. Report them separately before the main report.

If all issues have PRs, report that and exit.

Step 4: Analyze Each Issue

For each remaining issue, score the following:

Difficulty (1-10)

Base score: 5. Adjustments:

Signal	Adjustment
Documentation only	-3
Has proposed solution	-2
Has reproduction steps	-1
Clear error message	-1
Unknown root cause	+3
Architectural change	+3
Race condition/concurrency	+2
Security implications	+2
Multiple systems involved	+2

Importance (1-10)

Range	Level	Examples
8-10	Critical	Crash, data loss, security vulnerability, service down
6-7	High	Broken functionality, errors, performance issues
4-5	Medium	Enhancements, feature requests, improvements
1-3	Low	Cosmetic, documentation, typos

Tripping Scale (1-5) — Solution Sanity (How "Out There" Is It?)

Score	Label	Description
1	Total Sanity	Proven approach, standard patterns
2	Grounded w/Flair	Practical with creative touches
3	Dipping Toes	Exploring cautiously
4	Wild Adventure	Bold, risky, unconventional
5	Tripping	Questionable viability

Red Flags (+score): rewrite from scratch, buzzwords (blockchain, AI-powered, ML-based), experimental/unstable, breaking change, custom protocol Green Flags (-score): standard approach, minimal change, backward compatible, existing library, well-documented

Architectural Impact (1-5)

Always ask: "Is there a simpler way?" before scoring.

Score	Label	Description
1	Surgical	Isolated fix, 1-2 files, no new abstractions
2	Localized	Small addition, follows existing patterns exactly
3	Moderate	New component within existing architecture
4	Significant	New subsystem, new patterns, affects multiple modules
5	Transformational	Restructures core, changes paradigms, migration needed

Red Flags (+score): "rewrite", "refactor entire", new framework for existing capability, changes across >5 files, breaking API changes, scope creep Green Flags (-score): single file fix, uses existing utilities, follows established patterns, backward compatible, easily revertible

Critical: If a simple solution exists, architectural changes are wrong. Don't create a "validation framework" when a single if-check suffices.

Actionability (1-5) — Can it be resolved with a PR?

Score	Label	Description
1	Not Actionable	Question, discussion, duplicate, support request
2	Needs Triage	Missing info, unclear scope, needs clarification
3	Needs Investigation	Root cause unknown, requires debugging first
4	Ready to Work	Clear scope, may need some design decisions
5	PR Ready	Solution is clear, just needs implementation

Blockers (-score): questions ("how do I?"), discussions ("thoughts?"), labels (duplicate, wontfix, question), missing repro Ready signals (+score): action titles ("fix:", "add:"), proposed solution, repro steps, good-first-issue label, specific files mentioned

Derived Values

issueType: "bug" | "feature" | "docs" | "other"
suggestedLevel:
  - "beginner": difficulty 1-3, no security/architecture changes
  - "intermediate": difficulty 4-6
  - "advanced": difficulty 7+ OR security implications OR architectural changes

Calculation Formulas

ROI = Importance / Difficulty
AdjustedScore = ROI × TripMultiplier × ArchMultiplier × ActionMultiplier

Tripping Scale Multiplier:

Score	Label	Multiplier
1	Total Sanity	1.00 (no penalty)
2	Grounded w/Flair	0.85
3	Dipping Toes	0.70
4	Wild Adventure	0.55
5	Tripping	0.40

Architectural Impact Multiplier:

Score	Label	Multiplier
1	Surgical	1.00 (no penalty)
2	Localized	0.90
3	Moderate	0.75
4	Significant	0.50
5	Transformational	0.25

Actionability Multiplier:

Score	Label	Multiplier
5	PR Ready	1.00 (no penalty)
4	Ready to Work	0.90
3	Needs Investigation	0.70
2	Needs Triage	0.40
1	Not Actionable	0.10

Step 5: Categorize

• Quick Wins: ROI ≥ 1.5 AND Difficulty ≤ 5 AND Trip ≤ 3 AND Arch ≤ 2 AND Actionability ≥ 4
• Critical Bugs: issueType = "bug" AND Importance ≥ 8
• Tripping Issues: Trip ≥ 4
• Over-Engineered: Arch ≥ 4 (simpler solution likely exists)
• Not Actionable: Actionability ≤ 2

Sort all issues by AdjustedScore descending.

Step 6: Present Results

═══════════════════════════════════════════════════════════════
  ISSUE PRIORITIZATION REPORT
  Repository: {owner/repo}
  Analyzed: {count} issues
  Excluded: {excluded} issues with existing PRs
═══════════════════════════════════════════════════════════════

  Quick Wins: {n} | Critical Bugs: {n} | Tripping: {n} | Over-Engineered: {n} | Not Actionable: {n}

═══════════════════════════════════════════════════════════════
  TOP 10 BY ADJUSTED SCORE
═══════════════════════════════════════════════════════════════

  #123 [Adj: 3.50] ⭐ Quick Win
  Fix typo in README
  ├─ Difficulty: 1/10 | Importance: 4/10 | ROI: 4.00
  ├─ Trip: ✅ Total Sanity (1/5) | Arch: ✅ Surgical (1/5)
  ├─ Act: ✅ PR Ready (5/5) | Level: beginner
  └─ https://github.com/owner/repo/issues/123

═══════════════════════════════════════════════════════════════
  QUICK WINS (High Impact, Low Effort, Sane & Actionable)
═══════════════════════════════════════════════════════════════

  #123: Fix typo in README [Adj: 3.50]
        Difficulty: 1 | Importance: 4 | beginner

═══════════════════════════════════════════════════════════════
  RECOMMENDATIONS BY LEVEL
═══════════════════════════════════════════════════════════════

  BEGINNER (Difficulty 1-3, no security/architecture):
  - #123: Fix typo - Low risk, good first contribution

  INTERMEDIATE (Difficulty 4-6):
  - #456: Add validation - Medium complexity, clear scope

  ADVANCED (Difficulty 7-10 or security/architecture):
  - #789: Refactor auth - Architectural knowledge needed

═══════════════════════════════════════════════════════════════
  CRITICAL BUGS (Importance ≥ 8)
═══════════════════════════════════════════════════════════════

  #111 [Adj: 1.67] 🔴 Critical
  App crashes on startup with large datasets
  ├─ Difficulty: 6/10 | Importance: 9/10 | ROI: 1.50
  ├─ Trip: ✅ (2/5) | Arch: ✅ (2/5) | Act: ⚠️ (3/5)
  └─ https://github.com/owner/repo/issues/111

═══════════════════════════════════════════════════════════════
  TRIPPING ISSUES (Trip ≥ 4 — Review Carefully)
═══════════════════════════════════════════════════════════════

  #999 [Trip: 🚨 5/5 — Tripping]
  Rewrite entire backend in Rust with blockchain storage
  ├─ Red Flags: "rewrite from scratch", "blockchain"
  ├─ Adjusted Score: 0.12 (heavily penalized)
  └─ Consider: Is this complexity really needed?

═══════════════════════════════════════════════════════════════
  OVER-ENGINEERED (Arch ≥ 4 — Simpler Solution Likely Exists)
═══════════════════════════════════════════════════════════════

  #777 [Arch: 🏗️ 5/5 — Transformational]
  Add form validation
  ├─ Proposed: New validation framework with schema definitions
  ├─ Simpler Alternative: Single validation function, 20 lines
  └─ Ask: Why create a framework for one form?

  💡 TIP: Maintainers often reject PRs that change architecture
     unnecessarily. Always start with the simplest fix.

═══════════════════════════════════════════════════════════════
  NOT ACTIONABLE (Actionability ≤ 2)
═══════════════════════════════════════════════════════════════

  - #222: "How do I deploy to Kubernetes?" (Act: 1/5 — question)
  - #333: Duplicate of #111 (Act: 1/5 — duplicate)

═══════════════════════════════════════════════════════════════
  EXCLUDED — EXISTING PRs
═══════════════════════════════════════════════════════════════

  #123: Login crashes on empty password
        └─ 🔗 PR #456: "Fix login validation" (explicit: fixes #123)

  Detection: 🔗 Explicit link | 📎 Referenced | 🔍 Similar title | 💡 Semantic match

═══════════════════════════════════════════════════════════════
  SCALE LEGEND
═══════════════════════════════════════════════════════════════

  Trip (Solution Sanity):        Arch (Structural Impact):
  ✅ 1-2 = Sane                  ✅ 1-2 = Minimal change
  ⚠️  3  = Cautious              ⚠️  3  = Moderate
  🚨 4-5 = Risky                 🏗️ 4-5 = Over-engineered

  Actionability:
  ✅ 4-5 = Ready for PR
  ⚠️  3  = Needs Investigation
  ❌ 1-2 = Not Actionable

  AdjustedScore = ROI × TripMult × ArchMult × ActionMult
  Higher = Better (prioritize first)

  🎯 SIMPLICITY PRINCIPLE: If a 10-line fix exists,
     a 200-line refactor is wrong.

  Mode: SKILL (read-only) — analyzes only, never modifies.
═══════════════════════════════════════════════════════════════

Options

• --json: Raw JSON output
• --markdown / --md: Markdown table output
• --quick-wins: Show only quick wins
• --level beginner|intermediate|advanced: Filter by contributor level
• --limit N: Number of issues to analyze (default: 30)
• --include-with-prs: Skip PR filtering, include all issues

LLM Deep Analysis (Optional)

For higher-quality scoring, use an LLM to analyze each issue individually. For each issue, prompt the model with the issue details and scoring criteria, requesting structured JSON output:

{
  "number": 123,
  "difficulty": 5,
  "difficultyReasoning": "base 5; has repro (-1); unknown cause (+3) = 7",
  "importance": 7,
  "importanceReasoning": "broken functionality affecting users",
  "tripScore": 2,
  "tripLabel": "Grounded with Flair",
  "tripRedFlags": [],
  "tripGreenFlags": ["minimal change", "standard approach"],
  "archScore": 2,
  "archLabel": "Localized",
  "archRedFlags": [],
  "archGreenFlags": 
   
   
   
   
   
   
   
   
   

Truncate issue bodies longer than 2000 characters before sending to the model.

When to use LLM Deep Analysis:

• Complex repositories with nuanced issues
• When accuracy matters more than speed
• For repositories you're unfamiliar with

Tradeoffs: Slower (~2-5s per issue) but more accurate. 1 API call per issue.

Integration: For each issue, call the LLM with the analysis prompt, parse the JSON response, and merge into results before Step 5 (Categorize).