issue-prioritizer

Prioritize GitHub issues by ROI, solution sanity, and architectural impact. Use when triaging or ranking issues to identify quick wins, over-engineered proposals, and actionable bugs. Don't use when managing forks (use fork-manager) or general GitHub queries (use github). 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.

## When to use
- Triaging or ranking issues in a repository
- Identifying quick wins for contributors
- Filtering out non-actionable items (questions, duplicates)
- Detecting over-engineered proposals
- Matching issues to contributor skill levels

## When NOT to use
- Managing forks or syncing with upstream → use `fork-manager` instead
- General GitHub CLI queries (PR status, CI runs) → use `github` instead
- Reviewing code changes before publishing → use `pr-review` instead

## 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

**Basic fetch (most recent):**
```bash
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.

**Targeted fetch with `--topic`:**

When the user specifies `--topic <keyword>` (e.g. `--topic telegram`, `--topic agents`), use GitHub search to find issues matching that topic instead of just fetching the most recent:

```bash
# Search by topic keywords in title and body
gh issue list --repo {owner/repo} --state open --limit {limit} --search "{topic} in:title,body" --json number,title,body,labels,createdAt,comments,url
```

Multiple topics can be combined: `--topic "telegram agents"` searches for issues containing either term.

**Targeted fetch with `--search`:**

When the user specifies `--search <query>`, pass it directly as a GitHub search query for full control:

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

Examples:
- `--search "telegram in:title"` — only title matches
- `--search "label:bug telegram"` — bugs mentioning telegram
- `--search "label:bug,enhancement telegram agents"` — bugs or enhancements about telegram/agents
- `--search "comments:>5 telegram"` — active discussions about telegram

**Label-based fetch with `--label`:**

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

All fetch modes can be combined: `--topic telegram --label bug --limit 50` fetches up to 50 open bugs about telegram.

**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 (if using --topic/--search, suggest broadening the query)
- 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.

```bash
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 pen