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

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.

# 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

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)

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:** {createdA