/triage

name: triage
license: MIT
description: >-
  GitHub issue and PR investigator. Pulls open issues/PRs, classifies them, searches
  the codebase for root cause or reviews contributed code, proposes fixes with file:line
  references, and optionally implements fixes. Use for investigating GitHub issues and
  reviewing PRs; do NOT use for general code review unrelated to GitHub issues.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - triage
  - open issues
  - unlabeled issues
  - review pr
  - review prs
  - investigate issue
effort: high
last-updated: 2026-03-24

Triage — GitHub Issue & PR Investigator

When to Use

**Don't use when:** fixing a specific already-diagnosed issue (use /marshal); monitoring a single PR's CI (use /pr-watch); reviewing code quality outside of GitHub issues (use /review).

• `/triage` — triage all open, unlabeled issues
• `/triage 10` — investigate issue #10 specifically
• `/triage pr 13` — review PR #13
• `/triage prs` — review all open PRs
• `/triage --batch` — pull all open issues, classify, investigate, report
• `/triage --stale` — find issues older than 14 days with no activity
• After the `issue-monitor` SessionStart hook reports new issues

Codex PR review integration

For Codex-visible PRs, decide whether to use native `@codex review`, local Citadel triage, or both:

node scripts/codex-pr-review.js plan --repo <owner/repo> --pr <number> --risk <low|medium|high|local-only> --write

Use native `@codex review` when the diff is GitHub-visible and the main need is a focused P0/P1 review. Use local Citadel triage when the answer depends on unpushed files, local generated artifacts, or hands-on edits. Use both for large or risky PRs.

After Codex posts a GitHub review, fetch and ingest the review comments before deciding merge readiness:

node scripts/codex-review-fetch.js --repo <owner/repo> --pr <number> --write

Use `--file <review-comments.json>` with the same script when working from exported/offline review data.

Treat ingested P0/P1 findings as blockers until local verification confirms they are fixed or not applicable.

Inputs

| Input | Source | Required | |-------|--------|----------| | Issue/PR number | Argument (e.g., `/triage 10`, `/triage pr 13`) | No — omit to triage all open | | Mode | `pr` prefix for PRs | No — defaults to issues | | Repo | Auto-detected from git remote | Yes (auto) | | gh CLI | `"/c/Program Files/GitHub CLI/gh.exe"` on Windows, `gh` elsewhere | Yes (auto) |

Execution Protocol

Phase 0 — Environment Setup

1. Detect repo from `git remote get-url origin`, extract `owner/repo` 2. Verify `gh` auth status 3. Set `$GH`: Windows → `"/c/Program Files/GitHub CLI/gh.exe"`, other → `gh`

Phase 1 — Issue Intake

**Single issue** (`/triage 10`):

$GH issue view <number> --repo <owner/repo> --json number,title,body,labels,state,comments,createdAt,updatedAt,author,assignees

**Batch** (`/triage` or `--batch`):

$GH issue list --repo <owner/repo> --state open --json number,title,labels,createdAt,updatedAt --limit 50

Filter to untriaged: issues with no labels, or missing priority/type label.

**Stale** (`--stale`):

$GH issue list --repo <owner/repo> --state open --json number,title,labels,createdAt,updatedAt --limit 100

Filter to issues with no activity in 14+ days.

**Single PR** (`/triage pr 13`):

$GH pr view <number> --repo <owner/repo> --json number,title,body,author,state,files,commits,comments,createdAt,headRefName,baseRefName,mergeable,reviewDecision
$GH pr diff <number> --repo <owner/repo>

**All PRs** (`/triage prs`):

$GH pr list --repo <owner/repo> --state open --json number,title,author,createdAt,labels --limit 50

Phase 1b — PR Review Protocol

PR Classification

| Type | Signal | |------|--------| | `bugfix` | Fixes a reported issue, closes #N | | `feature` | Adds new functionality | | `refactor` | Restructures without changing behavior | | `docs` | Documentation only | | `infra` | CI/CD, build, packaging, installer |

PR Review Checklist

1. Read the full diff — not just the PR description. 2. Check for regressions against closed issues and recent commits. 3. Check for conflicts with in-flight work (same files as open PRs). 4. Verify the approach: correct solution, not overly complex. 5. Check cross-platform: Unix assumptions, Windows path handling. 6. Check conventions against existing project patterns. 7. Check for scope creep beyond the PR title.

PR Resolution

Write a per-PR resolution block (full template: docs/TRIAGE.md#pr-resolution-template) with:

• Author, type, files changed count, mergeable status
• What it does (1-3 sentences)
• Review findings, each with a file:line reference
• Issues found, split into **Critical** (blocks merge) and **Non-critical** (nice to fix, not blocking)
• Recommendation checkbox: Approve / Request changes (with the specific changes needed) / Close (with reason)

PR Actions

**IMPORTANT:** All PR actions are external. Show the user the exact comment text and get approval before posting.

Phase 2 — Classification

**Type** (exactly one): | Type | Signal | |------|--------| | `bug` | Error messages, "doesn't work", stack traces, regression | | `feature` | "Would be nice", "add support for" | | `question` | "How do I", "is it possible" | | `docs` | README/documentation issues | | `infra` | CI/CD, build, packaging, dependencies |

**Severity** (bugs only): | Severity | Criteria | |----------|----------| | `critical` | Blocks installation or core functionality for all users | | `high` | Breaks a major feature or affects many users | | `medium` | Breaks a minor feature or has a workaround | | `low` | Cosmetic, edge case, or easy workaround |

**Affected Component:**

• Citadel hooks / skills / agents
• `.claude/harness.json` — project configuration
• `.planning/` — planning/campaign system
• `docs/` — documentation
• Root files — project setup

Phase 3 — Investigati