Issue Triage

Issue Triage (issue-triage v1.0)

版本: 1.0.0 | 角色: issue 接收方核对 十步循环角色: B.2 实施阶段 — 接收 issue 后的前置核对步骤，防止在过期信息或未复现 bug 上开起新的 cycle 机械化: Step 0 由 scripts/triage.py (stdlib-only Python) 产出 JSON snapshot，AI 读 snapshot 进行 Step 6 复现 + verdict 综合。

快速开始

我应该使用这个 Skill 吗？

使用场景:

• 收到 issue 后，在起新 OpenSpec / branch 之前
• 确认 bug 是否在当前版本可复现
• 查看是否已有 in-flight PR 或本地分支处理同一问题
• 需要留 audit trail (verdict comment) 的 issue 核对

不使用场景:

• 已完成 triage、正在起修复 cycle → 直接 /phase-a-planner
• 只是看 issue 列表 / 查进度 → /state-scanner
• 向 Aria 维护团队报告问题 → /aria-report (方向相反，见 §与 aria-report 的关系)

核心功能

步骤定义 (SOT): 6 步流程的完整定义（每步目的、检查项、输出字段、失败模式）见 standards/conventions/issue-triage.md §Steps。本文档不复制步骤定义，仅描述 Skill 调用契约。

配置 (config-loader)

执行前读取 .aria/config.json，缺失则使用默认值。参见 config-loader。

执行流程

Step 0: 机械执行 triage.py (硬约束)

不可协商: Steps 1-5 所有字段由 scripts/triage.py 机械采集，AI 不得跳过、不得逐字段手工 Bash 替代、不得在失败时"降级"到手工采集。

执行命令:

python3 "${CLAUDE_PLUGIN_ROOT:-aria}/skills/issue-triage/scripts/triage.py" \
  --issue "<owner>/<repo>#N" \
  --output .aria/triage-report.json

退出码契约:

退出码评估顺序：先 30 (hard fail) → 再 10 (partial) → 否则 0。

Stage 1: 读取 Snapshot

triage.py exit 0/10 后：

1. 读取 .aria/triage-report.json
2. 验证 schema_version 字段存在（缺失 → abort，"report 格式异常，请重跑 /issue-triage"）
3. 展示 Steps 1-5 摘要（版本差、cited paths、likely_fix_candidates、in-flight 命中）
4. 若 exit 10：对每个 collection_status: error 的步骤展示 warning

Stage 2: Step 6 复现 (三模式)

根据 .aria/config.json 中 issue_triage.step6_mode 或用户参数决定模式：

每个复现 case 必须填结构化 schema（case schema 定义见 standards/conventions/issue-triage.md §Step 6）。即使 verdict=not-reproducible，也需 ≥1 case 记录缺失原因；match: null 表示未能执行。

Stage 3: Verdict 计算

1. 基于 repro.cases[] 和 Steps 1-5 数据，按 standards/conventions/issue-triage.md §Verdict dictionary 选择 verdict
2. 填写正交字段：
   • severity: 基于影响面（commit blast radius / hit_rate / data corruption 风险）由 AI 判断
   • recommended_action: 基于 verdict + severity 推断
   • deviation_note: 仅 partial-repro verdict 必填，描述与 issue 描述的实质偏离
3. 将 verdict + 正交字段写入 .aria/triage-report.json

Stage 4: 合成 triage-comment.md

生成 .aria/triage-comment.md 草稿，准备 POST 到 issue。模板结构见 §输出格式。

输出格式

triage-comment.md 模板

## Triage Report

**Verdict**: `{verdict}` | **Severity**: `{severity}` | **Recommended Action**: `{recommended_action}`

---

### Version

| Field | Value |
|-------|-------|
| Reported | `{version.reported}` |
| Current | `{version.current}` |
| Gap | {version.gap} |

{版本差注释，如 "issue 报告版本与当前版本相同，非 outdated report" 或 "版本已更新 N 个版本，建议先确认是否已修"}

### Code Path

{code.cited_paths[] 中每个路径的存在状态 + 描述是否与代码一致}

### Git History

{git_history.likely_fix_candidates[] 列表；若空则 "No recent commits matched on cited files"}

### In-flight

| Category | Matches |
|----------|---------|
| Remote PRs | {inflight.remote_prs[] summary or "none"} |
| Local branches | {inflight.local_branches[] summary or "none"} |
| Worktrees | {inflight.worktrees[] summary or "none"} |

### Reproduction

**Mode**: `{repro.exit_mode}` | **Hit rate**: `{repro.hit_rate}`

{repro.cases[] 每个 case 的 input / expected / actual / match 简报}

{partial-repro 时额外显示 deviation_note}

### Verdict Rationale

{2-3 句综合推理：为什么是该 verdict，关键证据来自哪个步骤}

---

*Generated by `/issue-triage` v{triage_tool_version} — Ref: {issue_ref}*

输入参数

使用示例

示例 1: 单仓库 issue（裸编号）— Aria #101

用户: "/issue-triage 101"
Step 0: triage.py --issue "10CG/Aria#101" --output .aria/triage-report.json → exit 0
Stage 1: version gap=0, cited paths 存在, likely_fix_candidates=[], in-flight remote_prs=1
Stage 2: auto 复现 → hit_rate=2/4 (2/4 主因 + 1/4 次生 + 1/4 不复现)
Stage 3: verdict=partial-repro, deviation_note="自报 4/4，实测 2/4 主因命中，与描述偏离"
Stage 4: 生成 .aria/triage-comment.md (准备 POST 到 #101)

示例 2: 跨仓库 issue，已修复

用户: "/issue-triage 10CG/SilkNode#42"
Step 0: triage.py --issue "10CG/SilkNode#42" → exit 0
Stage 1: Step 2 → VERSION current=v2.3.1, reported=v2.1.0 (gap=+2 minor)
         Step 4 → likely_fix_candidates=[{sha:"abc123", message:"fix: resolve SilkNode#42"}]
Stage 3: verdict=fixed-in-X, recommended_action=close

示例 3: pause 模式（需要用户提供数据）

用户: "/issue-triage 87 --mode pause"
Stage 2: exit_mode=pause
输出: "Step 6 复现需要：1. 测试用 Forgejo token  2. 触发 bug 的 config.json
      请补充后继续。"
(用户补充) → resume → Stage 3 → Stage 4

跨平台命令规范

错误处理

检查清单

使用前

• FORGEJO_TOKEN 已配置（或 .aria/config.json 有 forgejo 配置）
• issue 引用格式正确（101 / 10CG/Aria#101 / URL）
• 了解 6 步 SOP 含义：standards/conventions/issue-triage.md §Steps

使用后

• triage.py exit 0/10（非 30）
• .aria/triage-report.json 存在且 schema_version 字段存在
• Verdict 已选择（非空）
• partial-repro 时 deviation_note 已填写
• .aria/triage-comment.md 已生成，准备 POST 到 issue
• 如 verdict=confirmed 或 partial-repro，根据 recommended_action 决定是否起新 OpenSpec cycle

与 aria-report 的关系

这两个 Skill 名字相近，但方向相反，互不冲突：

不重叠: aria-report 的输出（一个新 issue）正好是 issue-triage 的输入（一个待 triage 的 issue）。aria-report → issue tracker → issue-triage 是完整链路。

相关文档

• standards/conventions/issue-triage.md — 6 步 SOP + Verdict 字典 + Exception 模板 (SOT)
• references/triage-report-schema.md — triage-report.json schema (source-of-truth)
• scripts/triage.py — 机械化 collector 入口
• state-scanner SKILL.md — scan.py pattern 参考
• aria-report SKILL.md — Inbound issue 报告（反向边界）
• 触发 issue: Forgejo Aria #101
• Canonical case study: issuecomment-5972

最后更新: 2026-05-13 Skill 版本: 1.0.0 维护者: 10CG Lab