baekenough/professor-triage

/professor-triage — Codebase-Driven Issue Triage

Purpose

Analyzes GitHub issues directly against the current codebase. For each issue, searches relevant code, assesses impact and blast radius, determines whether the issue has already been resolved, and performs automated triage with priority and size estimation. Produces a cross-analysis report and executes low-risk triage actions automatically.

Usage

/professor-triage                          # Default: --state open (excludes verify-done)
/professor-triage 587 589 590 591 592      # Direct issue numbers
/professor-triage --label codex-release    # Custom label filter
/professor-triage --since 2026-03-20       # Date filter

Workflow

Phase 1: Gather

1. Parse arguments to determine target issues:

   • If issue numbers provided: use those directly
   • If --label provided: gh issue list --label <label> --state <state> --json number
   • Default: gh issue list --state open --json number + exclude issues with verify-done label
   • If --since provided: add --search "created:>YYYY-MM-DD" filter

2. For each issue, fetch full details:

gh issue view NNN --json number,title,body,comments,labels,createdAt

3. For batches >20 issues, prefer gh api graphql for batch fetching to respect GitHub API rate limits (5000/hour authenticated).

4. If filter returns 0 results: if --label was used, check label existence via gh label list. Report if label missing. If default filter, report "No open issues without verify-done label found."

Phase 2: Codebase Analysis

For each issue, perform direct codebase analysis:

2A: Context Extraction — From issue title and body, extract:

• File paths mentioned (regex: backtick-wrapped paths, :\d+ line refs, (L\d+), (lines \d+-\d+))
• Error messages or stack traces
• Keywords (function names, class names, config keys, module names)
• Component areas mentioned (e.g., "auth", "CI", "hooks")

2B: Codebase Search — Delegate to Explore agent(s):

• Search for extracted keywords using Grep across the codebase
• Find related files using Glob patterns derived from keywords
• For explicitly mentioned files, verify existence and read relevant sections
• For error messages, trace to source location
• Map import/dependency relationships for affected files

2C: Impact Assessment — For each relevant file found:

• Read current state of the code
• Check recent changes: git log --since=<issue_created_date> --oneline -- <file>
• Determine if the issue has already been addressed by recent commits
• Assess blast radius (what depends on this code, what does this code depend on)

2D: Structured Finding — Produce per-issue analysis:

| Field | Content | |-------|---------| | Affected files | List with status: exists ✅ / missing ❌ / changed-since-issue ⚠️ | | Architecture impact | Breaking changes, dependency effects, scope of change | | Implementation path | Concrete steps with file:line references from current codebase | | Risk level | P1 (critical/security/breaking) / P2 (moderate/compat) / P3 (nice-to-have) | | Size estimate | XS (<1h) / S (1-3h) / M (3-8h) / L (1-3d) / XL (>3d) | | Already resolved? | Yes / No / Partial — with git evidence (commit hash, PR number) |

Parallelization (R009/R018):

• 1-3 issues → single Explore agent per issue (parallel per R009)
• 4-10 issues → parallel Explore agents, max 4 concurrent (R009)
• 10+ issues or 3+ Explore agents needed → Agent Teams per R018

Delegation: All codebase search delegated to Explore agent(s) with model: haiku. Orchestrator collects and synthesizes results.

Phase 3: Cross-Analyze

R010 note: This is a read-only analytical step — no file writes. Per R010 exception, the orchestrator may perform this directly. For batches >15 issues, delegate to a dedicated cross-analysis agent with model: opus.

Perform deep cross-analysis with full context from all issues:

1. Common patterns — Identify findings that appear across multiple issues (e.g., same file referenced, same recommendation theme)
2. Duplicate/merge candidates — Detect issues tracking the same underlying change:
   • Same release series (e.g., alpha.3/5/6)
   • Same upstream dependency
   • Same affected component
3. Conflicting findings — Where findings disagree across issues, resolve based on:
   • Codebase evidence (Phase 2 results)
   • Specificity (concrete code-level finding > abstract observation)
   • Recency (newer findings > older ones)
4. Priority matrix — Unified priority ranking:
   • P1: Breaking changes, security issues, blocking bugs
   • P2: Documentation gaps, compatibility updates, medium-risk items
   • P3: Nice-to-have improvements, future considerations
5. Action determination — Per-issue decision:
   • Close (Already Resolved): Phase 2 found issue already fixed by recent commits
   • Close (Not Applicable): Issue is irrelevant (internal dependency tag, no impact)
   • Close (Duplicate of #NNN): Superseded by another issue in the batch
   • Open — action required: Real work needed
   • Open — monitoring: Waiting for external trigger (e.g., stable release)
   • New issue needed: Cross-analysis discovered issue not yet tracked

Phase 4: Multi-Perspective Analysis & Output

For each analyzed issue, generate multi-perspective analysis comments and artifacts.

Parallelization (R009):

• Phase 4A + 4B: parallel (independent perspectives)
• Phase 4C: after 4A + 4B complete (synthesis requires both inputs)
• Phase 4D + 4E: parallel (independent outputs, both depend on 4C)
• Phase 4F: after all above (verification gate)

4A: 🏛️ Senior Architect Analysis — Delegate to arch-documenter (model: sonnet) to post GitHub comment:

## 🏛️ Senior Architect Analysis

### 아키텍처 영향
| 컴포넌트 | 영향 | 위험도 |
|----------|------|--------|
| {컴포넌트} | {설명} | {High/Medium/Low} |

### 코드 수준 분석
{Phase 2 코드베이스 분석의 구체적 file:line 참조}

### 전략적 평가
- **실현 가능성**: {근거가 포함된 평가}
- **우선순위 권장**: {P1/P2/P3 및 근거}

### 리스크 및 고려사항
| 리스크 | 가능성 | 완화 방안 |
|--------|--------|----------|
| {리스크} | {High/Medium/Low} | {완화 방안} |

**예상 작업량**: {XS/S/M/L/XL}

---
_🏛️ Senior Architect perspective — `/professor-triage` v2.2.0_

4B: 🤝 Project Colleague Review — Delegate to arch-documenter (model: sonnet) to post GitHub comment:

## 🤝 Project Colleague Review

### 구현 아이디어
{구체적 코드 위치 및 file:line 참조가 포함된 변경 제안}

### 놓치기 쉬운 세부사항
- {이름 충돌, 유효성 검사 우회, 경쟁 조건, 엣지 케이스}

### 권장 다음 단계
1. {구체적 file/function 참조가 포함된 실행 가능한 단계}
2. {실행 가능한 단계}
3. {실행 가능한 단계}

---
_🤝 Project Colleague perspective — `/professor-triage` v2.2.0_

Note: Do NOT include a "First Impressions" (첫인상) section in the Colleague Review — this was explicitly excluded per user feedback.

4C: 🎓 Professor Synthesis — Delegate to arch-documenter (model: opus) to post GitHub comment. This phase requires 4A and 4B results as input:

## 🎓 Professor Synthesis

### 코드베이스 검증
| 주장 (Architect/Colleague) | 검증 | 근거 |
|---------------------------|------|------|
| {주장} | ✅/⚠️/❌ | {file:line 또는 git 근거} |

### 합의 및 이견
| 주제 | Architect | Colleague | 판정 |
|------|-----------|-----------|------|
| {주제} | {입장} | {입장} | {종합 판단} |

### 우선순위 매트릭스
| 차원 | 평가 |
|------|------|
| 긴급성 | {High/Medium/Low} |
| 중요성 | {High/Medium/Low} |
| 규모 | {XS/S/M/L/XL} |
| 권장 순서 | {배치 내 N/M} |

### 누락된 관점
{Architect나 Colleague 모두 제기하지 않은 고려사항}

### 실행 로드맵
| 단계 | 작업 | 파일 | 의존성 |
|------|------|------|--------|
| 1 | {작업} | {파일} | — |
| 2 | {작업} | {파일} | 단계 1 |

### 최종 결론
{확정적 권장 사항이 포함된 2-3문장 종합}

---
_🎓 Professor Synthesis — `/professor-triage` v2.2.0_

4D: Issue Triage Comment (MANDATORY) — Every analyzed issue MUST receive a triage comment. This is not optional — even for issues created in the same session or with existing analysis. Skipping comments breaks the triage audit trail. Delegate to mgr-gitnerd to post on each analyzed issue:

## 🔬 Professor Triage — Codebase Analysis Result

**결정**: {Close (Already Resolved) | Close (Not Applicable) | Close (Duplicate of #NNN) | Open — action required | Open — monitoring}
**근거**: {코드베이스 분석 기반 1-2줄 요약}
**영향 파일**: {N}개 분석 — {N}✅ {N}⚠️ {N}❌
**리스크**: {P1/P2/P3} | **규모**: {XS/S/M/L/XL}
**전체 리포트**: {artifact path}

---
_`/professor-triage` v2.2.0에 의해 현재 코드베이스 대비 분석됨 — 관련 이슈 {N}개_

4E: Artifact Report — Delegate to arch-documenter to write:

Path: .claude/outputs/sessions/YYYY-MM-DD/professor-triage-HHmmss.md

Timestamps use local machine time (consistent with other artifact skills).

Template:

# Professor Triage 리포트 — YYYY-MM-DD

## 분석 대상
| # | 제목 | 라벨 | 생성일 |
|---|------|------|--------|

## 이슈별 분석
### #NNN — title
- **영향 파일**: N개 분석 — N✅ N⚠️ N❌
- **아키텍처 영향**: ...
- **구현 경로**: ...
- **리스크/우선순위**: P1/P2/P3
- **규모**: XS/S/M/L/XL
- **이미 해결됨?**: Yes/No/Partial — 근거
- **권장 조치**: ...

## 교차 분석
### 공통 패턴
### 중복/병합 후보
### 상충 발견사항 해결
### 우선순위 매트릭스

## 다관점 요약
### Architect 주요 사항
### Colleague 주요 사항
### Professor Synthesis 핵심 포인트

## 실행된 조치
| 이슈 | 조치 | 상태 |

## 보류 중인 조치 (확인 필요)

Phase 4F: Comment Verification Gate

Before proceeding to Phase 5, verify ALL analyzed issues received the full set of comments (Architect + Colleague + Professor Synthesis + Triage):

# For each issue NNN in the batch:
gh issue view NNN --json comments --jq '.comments | map(select(.body | contains("Professor Triage"))) | length'
# Must be >= 1 for every issue. If any is 0, go back and post.

# Also verify multi-perspective comments:
gh issue view NNN --json comments --jq '.comments | map(select(.body | contains("Senior Architect"))) | length'
gh issue view NNN --json comments --jq '.comments | map(select(.body | contains("Project Colleague"))) | length'
gh issue view NNN --json comments --jq '.comments | map(select(.body | contains("Professor Synthesis"))) | length'
# All must be >= 1. If any is 0, the corresponding Phase 4A/4B/4C was skipped — go back and post.

Phase 5: Act

Delegate ALL GitHub operations to mgr-gitnerd.

Automatic (low-risk, reversible):

| Condition | Action | |-----------|--------| | Phase 2 found issue already resolved (with commit evidence) | gh issue close --reason "completed" + comment with resolving commit | | Cross-analysis concludes "Not Applicable" / "no action needed" | gh issue close --reason "not planned" | | Cross-analysis detects same-series duplicates | Keep latest, close others + duplicate label | | All analysis complete | Add verify-done label | | Priority assigned | Add P1/P2/P3 label |

Confirmation required (high-risk):

Present to user and wait for approval before executing:

| Condition | Action | Reason | |-----------|--------|--------| | Reopen a closed issue | Propose reopen | Unintended notifications | | New issue creation needed | Present draft title/body | Noise prevention | | Epic/milestone linking | Propose link | Project structure change | | Issue body modification | Present edit draft | Respect original author intent |

Ensure verify-done label exists: If not, create with gh label create "verify-done" --color "0E8A16".

Notes

• Phase 1: Orchestrator fetches issues directly (no agent needed)
• Phase 2: Explore agents with model: haiku for codebase search; orchestrator synthesizes findings
• Phase 3: Orchestrator directly (read-only, R010 exception); opus agent for >15 issues
• Phase 4A/4B: arch-documenter (sonnet) for Architect/Colleague analysis comments (parallel)
• Phase 4C: arch-documenter (opus) for Professor Synthesis comment (requires 4A+4B)
• Phase 4D: mgr-gitnerd for triage comment; Phase 4E: arch-documenter for artifact report (parallel)
• Phase 4F: Verification gate for all 4 comment types
• Phase 5: mgr-gitnerd for all GitHub operations
• No external dependencies (omc_issue_analyzer removed in v2.0.0, multi-perspective analysis restored in v2.1.0)