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.
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.
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:
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 — Investigation
3a. Parse the Report
Extract: error messages, environment, reproduction steps, expected vs actual behavior, workarounds.
3b. Search the Codebase
Grep for exact error messages / error codes
Read files named in the issue
Find functions named in stack traces
Search for the bug class or anti-pattern
git log --oneline -20 -- <affected-files> for recent changes
Cross-reference similar issues
3c. Root Cause Analysis
For bugs:
What breaks — the specific code path
Why it breaks — root cause, not symptom
When introduced — git blame / log
Who is affected — scope
The fix — file:line references
For features/questions:
Already possible? Search existing functionality.
Where would it go? Which component/layer.
Effort: trivial / small / medium / large
Blockers: dependencies, architecture constraints
3d. Reproduce (when possible)
Set up conditions, run the failing command, confirm error matches, verify proposed fix resolves it.
Phase 4 — Resolution Plan
Write a per-issue resolution plan (full template: docs/TRIAGE.md#issue-resolution-plan-template) with:
Type, severity, component, reproducible (yes / no / not-attempted)
Root cause: 1-3 sentences explaining WHY
Affected code: <file>:<line> entries with what is wrong at each
Proposed fix: specific code changes with file:line references
Impact: who is affected, whether a workaround exists, whether it is a breaking change
Recommended action checkbox: Fix in next release / Needs more info from reporter / Won't fix (with reason) / Duplicate of #N
Phase 5 — Action
Auto-fix when: root cause clear and verified, fix contained to 1-3 files, no breaking changes, no architectural decisions needed.
Steps:
Branch: fix/issue-<number>-<slug>
Implement fix
Run typecheck/build
Commit: fix: <description> (closes #<number>)
Push and open PR linking the issue
Comment on the issue with the PR link
Comment with findings when fix needs discussion or user input: post root cause analysis, proposed fix, and questions.
Label only for questions/docs/features: add type + priority labels, optionally point to existing docs.
Phase 6 — Report
Output a Triage Summary table with columns # | Title | Type | Severity | Action | Status, one row per triaged item (example: docs/TRIAGE.md#triage-summary-example).
Label Taxonomy
Apply via $GH issue edit <number> --add-label "<label>":
---PR READY---
PR #<N>: <url>
To watch this PR automatically:
Local → /pr-watch <N>
Cloud → open in Claude Code web or mobile, toggle "Auto fix" ON
---
Contextual Gates
Disclosure: "Triaging GitHub issues and PRs. Read-only — no changes made without showing you first."
Reversibility: green — investigation is read-only; any GitHub actions (labels, comments, PRs) shown to user for approval before posting
Trust gates:
Any: view triage report; all external actions require explicit approval
Quality Gates
Every issue has a classification (type + severity for bugs)
Every bug has root cause with file:line references
Every auto-fix passes typecheck and build
Every PR links to the issue it fixes
Every issue has at least a label or comment
No issue comment is generic or substanceless
Fringe Cases
gh not available or not authenticated: Stop and instruct: "Run gh auth login before using /triage."
No open issues or PRs: Report "No open issues found." and exit cleanly.
Empty/unparseable issue body: Classify as needs-info, comment requesting reproduction steps.
.planning/ missing: /triage reads from GitHub, not local state. Skip .planning/ writes if missing.
Anti-Patterns — Do NOT
Post generic comments without substance
Propose fixes without reading the actual code
Label without investigating
Auto-fix when root cause is unclear
Close issues without explanation
Guess at fixes — verify by reading code and running checks
---HANDOFF---
- Triaged N issues: X bugs, Y features, Z questions
- Auto-fixed: <list of issue numbers with PR links>
- Needs attention: <list of issues requiring human decision>
- New labels applied: <count>
- Reversibility: green — investigation read-only; auto-fix PRs can be closed/reverted if unwanted
---
