issue-triage

# Issue Triage 3-phase workflow for maintainers: automated audit of all open issues, opt-in deep analysis via parallel agents, and validated triage actions (comments, labels, closures). ## When to Use This Skill | Skill | Usage | Output | |-------|-------|--------| | `/issue-triage` | Sort, analyze, and act on an issue backlog | Triage tables + analysis + executed actions | | `/pr-triage` | Sort, review, and comment on a PR backlog | Triage table + reviews + posted comments | **Triggers**: - Manually: `/issue-triage` or `/issue-triage all` or `/issue-triage 42 57` - Proactively: when >10 open issues without label, or stale issues >30 days detected --- ## Language - Check the argument passed to the skill - If `en` or `english` → tables and summary in English - If `fr`, `french`, or no argument → French (default) - Note: GitHub comments and labels (Phase 3) are ALWAYS in English (international audience) --- ## Configuration Thresholds used throughout the workflow. Edit to match your project: | Parameter | Default | Description | |-----------|---------|-------------| | `staleness_days` | 30 | Days without activity before flagging as stale | | `very_stale_days` | 90 | Days without activity before flagging as very stale | | `jaccard_threshold` | 60% | Minimum Jaccard similarity to flag two issues as duplicates | | `closed_compare_count` | 20 | Number of recent closed issues to compare for duplicate detection | | `open_limit` | 100 | Maximum open issues to fetch and analyze | --- ## Preconditions ```bash git rev-parse --is-inside-work-tree gh auth status ``` If either fails, stop and explain what is missing. --- ## Phase 1: Audit (always executed) ### Data Gathering (parallel commands) ```bash # Repo identity gh repo view --json nameWithOwner -q .nameWithOwner # Open issues (exclude PRs, limit 100) gh issue list --state open --limit 100 \ --json number,title,author,createdAt,updatedAt,labels,body,comments,assignees,milestone # Recent closed issues (for duplicate detection) gh issue list --state closed --limit 20 \ --json number,title,body,labels,stateReason # Open PRs (bodies for cross-reference detection) gh pr list --state open --limit 50 --json number,title,body # Collaborators (to distinguish reporter types) gh api "repos/{owner}/{repo}/collaborators" --jq '.[].login' ``` **Collaborators fallback**: if `gh api .../collaborators` returns 403/404: ```bash # Extract authors from last 10 merged PRs gh pr list --state merged --limit 10 --json author --jq '.[].author.login' | sort -u ``` If still ambiguous, ask via `AskUserQuestion`. **Note**: `comments` field in `gh issue list --json comments` returns the count, not content. For Phase 2, fetch full content separately: `gh issue view {num} --json comments`. ### Analysis Dimensions Run all 6 dimensions for each open issue: #### 1. Categorization Classify each issue by reading `title` + first 200 chars of `body`: | Category | Label | Criteria | |----------|-------|----------| | Bug | `bug` | Describes broken behavior, unexpected output, crash | | Feature Request | `enhancement` | Asks for new functionality | | Question / Support | `question` | User asking how something works | | Documentation | `documentation` | Missing or incorrect docs | | Out of Scope | `wontfix` | Clearly outside project boundaries | | Unclear | `needs-info` | Body empty, too vague to categorize | If body is empty → category is always `Unclear` (never assume). #### 2. Cross-reference to PRs Scan each open PR body for references to the issue number: - Patterns: `fixes #N`, `closes #N`, `resolves #N`, `fix #N`, `close #N` (case-insensitive, `N` = issue number) - Use regex locally on the `body` fields already fetched; do NOT make N additional API calls - If found: flag issue as "PR-linked" with PR number #### 3. Duplicate Detection via Jaccard Similarity **Algorithm (self-contained, no external library)**: For each open issue, compute Jaccard similarity against all other open issues AND the 20 most recent closed issues. ``` Step 1: Normalize title + first 300 chars of body: - Lowercase the full text - Strip category prefixes: "feat:", "fix:", "bug:", "chore:", "docs:", "test:", "refactor:" - Remove punctuation: .,!?;:'"()[]{}-_/\@# Step 2: Tokenize: - Split on whitespace - Remove stop words: the a an is in on to for of and or with this that it can not no be - Remove tokens shorter than 3 characters Step 3: Compute Jaccard: tokens_A = set of tokens from issue A tokens_B = set of tokens from issue B jaccard = |tokens_A ∩ tokens_B| / |tokens_A ∪ tokens_B| Step 4: Flag: - If jaccard >= 0.60: mark as potential duplicate - Report: "Similar to #N (Jaccard: 0.72)" - Keep the OLDER issue as canonical; newer = duplicate candidate ``` Jaccard is computed at runtime using the fetched data; no API calls beyond Phase 1 gather. #### 4. Risk Classification Assign Red / Yellow / Green based on signals in title + body: | Level | Color | Criteria | |-------|-------|----------| | Critical | Red | Security vulnerability, data loss, regression blocking users, crash in production | | Needs Attention | Yellow | Missing validation, performance degradation, breaking change undocumented, Unclear with no response for >7 days | | Normal | Green | Everything else | #### 5. Staleness | Status | Criterion | |--------|-----------| | Active | Updated within 30 days | | Stale | No activity 30–90 days | | Very Stale | No activity >90 days | Use `updatedAt` field. Staleness does NOT depend on comments count; a commented-on issue with old `updatedAt` is still stale. #### 6. Recommendations One recommended action per issue: | Situation | Action | |-----------|--------| | Category = Unclear, body empty | Comment requesting details | | Jaccard >= 0.60 with known issue | Close as duplicate, link original | | Very stale + no assignee | Comment requesting status, suggest close | | Risk = Red | Pin to top of triage, escalate immediately | | Category = OOS | Close with explanation | | PR-linked | No action needed (tracked via PR) | | Normal + labeled | No action needed | ### Output: Triage Tables ``` ## Open Issues ({count}) ### Critical: Immediate Attention (Risk: Red) | # | Title | Category | Reporter | Days Open | Action | |---|-------|----------|----------|-----------|--------| ### PR-Linked (tracked in open PRs) | # | Title | Category | PR | Days Open | |---|-------|----------|----|-----------| ### Active Issues | # | Title | Category | Labels | Reporter | Days | Action | |---|-------|----------|--------|----------|------|--------| ### Duplicate Candidates | # | Title | Similar To | Jaccard | Action | |---|-------|------------|---------|--------| ### Stale Issues | # | Title | Category | Last Activity | Reporter | Action | |---|-------|----------|---------------|----------|--------| ### Summary - Total open: {N} - Critical (Red): {count} - PR-linked: {count} - Duplicate candidates: {count} - Stale (30–90d): {count} - Very stale (>90d): {count} - Unlabeled: {count} - Recommended actions: {comment: N, label: N, close: N} ``` 0 issues → display `No open issues.` and stop. **Protection rules** (apply to all phases): - Never close an issue authored by a collaborator without explicit user confirmation - Never re-label an issue that already has labels (only add missing labels) - If body is empty → always request details before any other action - Never auto-close a Red issue without user confirmation ### Automatic Copy After displaying the triage tables, copy to clipboard using platform-appropriate command: ```bash UNAME=$(uname -s) if [ "$UNAME" = "Darwin" ]; then pbcopy <<'EOF' {full triage tables} EOF elif command -v xclip &>/dev/null; then echo "{full triage tables}" | xclip -selection clipboard elif command -v wl-copy &>/dev/null; then echo "{full triage tables}" | wl-copy elif command -v clip.exe &>/dev/null; then echo "{full triage tables}" | clip.exe fi ``` Confirm: `Triage tables copied to clipboard.` (EN) / `Tableaux copiés dans le presse-papier.` (FR) --- ## Phase 2: Deep Analysis (opt-in) ### Issue Selection **If argument passed**: - `"all"` → all issues with recommended actions - Numbers (`"42 57"`) → only those issues - No argument → propose via `AskUserQuestion` **If no argument**, display: ``` question: "Which issues do you want to analyze in depth?" header: "Deep Analysis" multiSelect: true options: - label: "All ({N} issues with recommended actions)" description: "Launch parallel analysis agents for each actionable issue" - label: "Critical only ({M} Red issues)" description: "Focus on high-risk issues requiring immediate action" - label: "Duplicate candidates ({K} issues)" description: "Verify Jaccard similarity with full body + comments" - label: "Stale only ({J} stale issues)" description: "Decide which stale issues to close vs. revive" - label: "Skip" description: "Stop here, audit only" ``` If "Skip" → end workflow. ### Executing Analysis For each selected issue, launch an analysis agent via **Task tool in parallel**: ``` subagent_type: general model: sonnet prompt: | Analyze GitHub issue #{num}: "{title}" **Metadata**: Category={category}, Risk={risk}, Days open={days}, Labels={labels} **Reporter**: @{author} ({collaborator? "collaborator" : "external"}) **Assignees**: {assignees or "none"} **Body**: {body} **Comments** (fetch via: gh issue view {num} --json comments): {comments[].body, truncate at 5000 chars total} **Duplicate candidates**: {jaccard_results or "none found"} **Linked PRs**: {pr_refs or "none"} Tasks: 1. Verify the category assigned in Phase 1 (correct? suggest alternative if not) 2. If duplicate candidate: confirm or deny similarity with rationale 3. If Unclear/needs-info: identify exactly what information is missing 4. Suggest the most appropriate action with exact text if a comment is needed 5. Estimate effort to fix if it's a Bug or Feature Request (XS/S/M/L/XL) Return structured output: ### Verification ### Duplicate Analysis ### Missing Information ### Recommended Action ### Effort Estimate ``` **Fallback if parallel agents unavailable**: run analysis sequentially, one issue at a time. Notify user: `Running sequential analysis (parallel agents not available).` Fetch full comments via: ```bash gh issue view {num} --json comments --jq '.comments[].body' ``` Aggregate all reports. Display a summary after all analyses complete. --- ## Phase 3: Actions (mandatory validation) ### Draft Generation For each analyzed issue, generate the appropriate action using the template `templates/issue-comment.md`. **3 action types**: | Type | Command | When | |------|---------|------| | Comment | `gh issue comment {num} --body-file -` | Needs info, stale ping, OOS explanation |