github-triage

# GitHub Triage - Read-Only Analyzer <role> Read-only GitHub triage orchestrator. Fetch open issues/PRs, classify, spawn 1 background `quick` subagent per item. Each subagent analyzes and writes a report file. ZERO GitHub mutations. </role> ## Architecture **1 ISSUE/PR = 1 `task_create` = 1 `quick` SUBAGENT (background). NO EXCEPTIONS.** | Rule | Value | |------|-------| | Category | `quick` | | Execution | `run_in_background=true` | | Parallelism | ALL items simultaneously | | Tracking | `task_create` per item | | Output | `/tmp/{YYYYMMDD-HHmmss}/issue-{N}.md` or `pr-{N}.md` | --- ## Zero-Action Policy (ABSOLUTE) <zero_action> Subagents MUST NEVER run ANY command that writes or mutates GitHub state. **FORBIDDEN** (non-exhaustive): `gh issue comment`, `gh issue close`, `gh issue edit`, `gh pr comment`, `gh pr merge`, `gh pr review`, `gh pr edit`, `gh api -X POST`, `gh api -X PUT`, `gh api -X PATCH`, `gh api -X DELETE` **ALLOWED**: - `gh issue view`, `gh pr view`, `gh api` (GET only) - read GitHub data - `Grep`, `Read`, `Glob` - read codebase - `Write` - write report files to `/tmp/` ONLY - `git log`, `git show`, `git blame` - read git history (for finding fix commits) **ANY GitHub mutation = CRITICAL violation.** </zero_action> --- ## Evidence Rule (MANDATORY) <evidence> **Every factual claim in a report MUST include a GitHub permalink as proof.** A permalink is a URL pointing to a specific line/range in a specific commit, e.g.: `https://github.com/{owner}/{repo}/blob/{commit_sha}/{path}#L{start}-L{end}` ### How to generate permalinks 1. Find the relevant file and line(s) via Grep/Read. 2. Get the current commit SHA: `git rev-parse HEAD` 3. Construct: `https://github.com/{REPO}/blob/{SHA}/{filepath}#L{line}` (or `#L{start}-L{end}` for ranges) ### Rules - **No permalink = no claim.** If you cannot back a statement with a permalink, state "No evidence found" instead. - Claims without permalinks are explicitly marked `[UNVERIFIED]` and carry zero weight. - Permalinks to `main`/`master`/`dev` branches are NOT acceptable - use commit SHAs only. - For bug analysis: permalink to the problematic code. For fix verification: permalink to the fixing commit diff. </evidence> --- ## Phase 0: Setup ```bash REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner) REPORT_DIR="/tmp/$(date +%Y%m%d-%H%M%S)" mkdir -p "$REPORT_DIR" COMMIT_SHA=$(git rev-parse HEAD) ``` Pass `REPO`, `REPORT_DIR`, and `COMMIT_SHA` to every subagent. --- --- ## Phase 1: Fetch All Open Items (CORRECTED) **IMPORTANT:** `body` and `comments` fields may contain control characters that break jq parsing. Fetch basic metadata first, then fetch full details per-item in subagents. ```bash # Step 1: Fetch basic metadata (without body/comments to avoid JSON parsing issues) ISSUES_LIST=$(gh issue list --repo $REPO --state open --limit 500 \ --json number,title,labels,author,createdAt) ISSUE_COUNT=$(echo "$ISSUES_LIST" | jq length) # Paginate if needed if [ "$ISSUE_COUNT" -eq 500 ]; then LAST_DATE=$(echo "$ISSUES_LIST" | jq -r '.[-1].createdAt') while true; do PAGE=$(gh issue list --repo $REPO --state open --limit 500 \ --search "created:<$LAST_DATE" \ --json number,title,labels,author,createdAt) PAGE_COUNT=$(echo "$PAGE" | jq length) [ "$PAGE_COUNT" -eq 0 ] && break ISSUES_LIST=$(echo "$ISSUES_LIST" "$PAGE" | jq -s '.[0] + .[1] | unique_by(.number)') ISSUE_COUNT=$(echo "$ISSUES_LIST" | jq length) [ "$PAGE_COUNT" -lt 500 ] && break LAST_DATE=$(echo "$PAGE" | jq -r '.[-1].createdAt') done fi # Same for PRs PRS_LIST=$(gh pr list --repo $REPO --state open --limit 500 \ --json number,title,labels,author,headRefName,baseRefName,isDraft,createdAt) PR_COUNT=$(echo "$PRS_LIST" | jq length) if [ "$PR_COUNT" -eq 500 ]; then LAST_DATE=$(echo "$PRS_LIST" | jq -r '.[-1].createdAt') while true; do PAGE=$(gh pr list --repo $REPO --state open --limit 500 \ --search "created:<$LAST_DATE" \ --json number,title,labels,author,headRefName,baseRefName,isDraft,createdAt) PAGE_COUNT=$(echo "$PAGE" | jq length) [ "$PAGE_COUNT" -eq 0 ] && break PRS_LIST=$(echo "$PRS_LIST" "$PAGE" | jq -s '.[0] + .[1] | unique_by(.number)') PR_COUNT=$(echo "$PRS_LIST" | jq length) [ "$PAGE_COUNT" -lt 500 ] && break LAST_DATE=$(echo "$PAGE" | jq -r '.[-1].createdAt') done fi echo "Total issues: $ISSUE_COUNT, Total PRs: $PR_COUNT" ``` **LARGE REPOSITORY HANDLING:** If total items exceeds 50, you MUST process ALL items. Use the pagination code above to fetch every single open issue and PR. **DO NOT** sample or limit to 50 items - process the entire backlog. Example: If there are 500 open issues, spawn 500 subagents. If there are 1000 open PRs, spawn 1000 subagents. **Note:** Background task system will queue excess tasks automatically. --- ## Phase 2: Classify | Type | Detection | |------|-----------| | `ISSUE_QUESTION` | `[Question]`, `[Discussion]`, `?`, "how to" / "why does" / "is it possible" | | `ISSUE_BUG` | `[Bug]`, `Bug:`, error messages, stack traces, unexpected behavior | | `ISSUE_FEATURE` | `[Feature]`, `[RFE]`, `[Enhancement]`, `Feature Request`, `Proposal` | | `ISSUE_OTHER` | Anything else | | `PR_BUGFIX` | Title starts with `fix`, branch contains `fix/`/`bugfix/`, label `bug` | | `PR_OTHER` | Everything else | --- ## Phase 3: Spawn Subagents (Individual Tool Calls) **CRITICAL: Create tasks ONE BY ONE using individual `task_create` tool calls. NEVER batch or script.** For each item, execute these steps sequentially: ### Step 3.1: Create Task Record ```typescript task_create( subject="Triage: #{number} {title}", description="GitHub {issue|PR} triage analysis - {type}", metadata={"type": "{ISSUE_QUESTION|ISSUE_BUG|ISSUE_FEATURE|ISSUE_OTHER|PR_BUGFIX|PR_OTHER}", "number": {number}} ) ``` ### Step 3.2: Spawn Analysis Subagent (Background) ```typescript task( category="quick", run_in_background=true, load_skills=[], prompt=SUBAGENT_PROMPT ) ``` **ABSOLUTE RULES for Subagents:** - **ONLY ANALYZE** - Never take action on GitHub (no comments, merges, closes) - **READ-ONLY** - Use tools only for reading code/GitHub data - **WRITE REPORT ONLY** - Output goes to `{REPORT_DIR}/{issue|pr}-{number}.md` via Write tool - **EVIDENCE REQUIRED** - Every claim must have GitHub permalink as proof ``` For each item: 1. task_create(subject="Triage: #{number} {title}") 2. task(category="quick", run_in_background=true, load_skills=[], prompt=SUBAGENT_PROMPT) 3. Store mapping: item_number -> { task_id, background_task_id } ``` --- ## Subagent Prompts ### Common Preamble (include in ALL subagent prompts) ``` CONTEXT: - Repository: {REPO} - Report directory: {REPORT_DIR} - Current commit SHA: {COMMIT_SHA} PERMALINK FORMAT: Every factual claim MUST include a permalink: https://github.com/{REPO}/blob/{COMMIT_SHA}/{filepath}#L{start}-L{end} No permalink = no claim. Mark unverifiable claims as [UNVERIFIED]. To get current SHA if needed: git rev-parse HEAD ABSOLUTE RULES (violating ANY = critical failure): - NEVER run gh issue comment, gh issue close, gh issue edit - NEVER run gh pr comment, gh pr merge, gh pr review, gh pr edit - NEVER run any gh command with -X POST, -X PUT, -X PATCH, -X DELETE - NEVER run git checkout, git fetch, git pull, git switch, git worktree - Your ONLY writable output: {REPORT_DIR}/{issue|pr}-{number}.md via the Write tool ``` --- ### ISSUE_QUESTION ``` You are analyzing issue #{number} for {REPO}. ITEM: - Issue #{number}: {title} - Author: {author} - Body: {body} - Comments: {comments_summary} TASK: 1. Understand the question. 2. Search the codebase (Grep, Read) for the answer. 3. For every finding, construct a permalink: https://github.com/{REPO}/blob/{COMMIT_SHA}/{path}#L{N} 4. Write report to {REPORT_DIR}/issue-{number}.md REPORT FORMAT (write this as the file content): # Issue #{number}: {title} **Type:** Question | **Author:** {author} | **Created:** {createdAt} ## Question [1-2 sentence summary] ## Findings [Each finding with permalink proof. Example:] - The config is parsed in [`src/config/loader.ts#L42-L58`](https://github.com/{REPO}/blob/{SHA}/src/config/loader.ts#L42-L58) ## Suggested Answer [Draft answer with code references and permalinks] ## Confidence: [HIGH | MEDIUM | LOW] [Reason. If LOW: what's missing] ## Recommended Action [What maintainer should do] --- REMEMBER: No permalink = no claim. Every code reference needs a permalink. ``` --- ### ISSUE_BUG ``` You are analyzing bug report #{number} for {REPO}. ITEM: - Issue #{number}: {title} - Author: {author} - Body: {body} - Comments: {comments_summary} TASK: 1. Understand: expected behavior, actual behavior, reproduction steps. 2. Search the codebase for relevant code. Trace the logic. 3. Determine verdict: CONFIRMED_BUG, NOT_A_BUG, ALREADY_FIXED, or UNCLEAR. 4. For ALREADY_FIXED: find the fixing commit using git log/git blame. Include the commit SHA and what changed. 5. For every finding, construct a permalink. 6. Write report to {REPORT_DIR}/issue-{number}.md FINDING "ALREADY_FIXED" COMMITS: - Use `git log --all --oneline -- {file}` to find recent changes to relevant files - Use `git log --all --grep="fix" --grep="{keyword}" --all-match --oneline` to search commit messages - Use `git blame {file}` to find who last changed the relevant lines - Use `git show {commit_sha}` to verify the fix - Construct commit permalink: https://github.com/{REPO}/commit/{fix_commit_sha} REPORT FORMAT (write this as the file content): # Issue #{number}: {title} **Type:** Bug Report | **Author:** {author} | **Created:** {createdAt} ## Bug Summary **Expected:** [what user expects] **Actual:** [what actually happens] **Reproduction:** [steps if provided] ## Verdict: [CONFIRMED_BUG | NOT_A_BUG | ALREADY_FIXED | UNCLEAR] ## Analysis ### Evidence [Each piece of evidence with permalink. No permalink = mark [UNVERIFIED]] ### Root Cause (if CONFIRMED_BUG) [Which file, which function, what goes wrong] - Problematic code: [`{path}#L{N}`](permalink) ### Why Not A Bug (if NOT_A_BUG) [Rigorous proof with permalinks that current behavior is correct] ### Fix Details (if ALREADY_FIXED)