bug-triage

Donchitos ｜ 除錯與調查 ｜ 原文 ｜ MIT

重新評估開著的 bug，排優先度、分派 sprint、抓系統性趨勢

---
name: bug-triage
description: "重新評估還開著的 bug：優先度 vs 嚴重度、分派到 sprint、找出系統性趨勢。bug 數量變多時執行。"
argument-hint: "[sprint | full | trend]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash(bash "*/.claude/skills/bug-triage/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow`

**Automation mode**：解析 `modes.automation`（`project.local.yaml` →
`project.yaml` → 預設 `collaborative`）。每一次 `AskUserQuestion` 呼叫和
每一次檔案寫入都要遵守 `.claude/docs/automation-modes.md`
（collaborative 一律詢問 · guided 只問重大事項 · autonomous 記錄後直接往下走；
屬於 `automation_always_ask` 的類別一律要問）。

# Bug Triage

這個 skill 把還開著的 bug backlog 處理成一份排好優先順序、
分派好 sprint 的行動清單。它區分**嚴重度**（影響有多糟？）和
**優先度**（得多緊急修？），偵測系統性趨勢，
並確保沒有任何嚴重 bug 在 sprint 之間被遺漏。

**輸出：** `production/qa/bug-triage-[date].md`

**何時執行：**
- Sprint 開始時：把還開著的 bug 分派到新的 sprint 或 backlog
- `/team-qa` 完成、並且有新 bug 被建檔之後
- bug 數量超過 10 個以上還開著的時候

---

## 1. 解析參數

**模式：**
- `/bug-triage sprint`：針對目前的 sprint 做 triage；把修得了的 bug
  分派到 sprint backlog；其餘延後
- `/bug-triage full`：不管 sprint 範圍，對所有 bug 做完整 triage
- `/bug-triage trend`：只做趨勢分析（不分派）；唯讀報告
- 沒有參數：有目前的 sprint 就跑 sprint 模式，否則跑 full 模式

---

## 2. 載入 Bug Backlog

### Step 2a：找出 bug 檔案

依優先順序 Glob bug 報告：
1. `production/qa/bugs/*.md`：個別的 bug 報告檔（偏好的格式）
2. `production/qa/bugs.md`：單一整合的 bug 紀錄（備用）
3. 任何 `production/qa/qa-plan-*.md` 的 "Bugs Found" 表（最後手段）

如果找不到 bug 檔案：
> "No bug files found in `production/qa/bugs/`. If bugs are tracked in a
> different location, adjust the glob pattern. If no bugs exist yet, there is
> nothing to triage."

停下來並回報。沒有 bug 就不要繼續。Verdict: **COMPLETE** — no bug files in `production/qa/bugs/`; nothing to triage.

**在 `trend` 模式，不要讀完整的 bug 內文。** 趨勢指標（數量、嚴重度
分布、依系統、依日期）光靠標頭欄位就算得出來：
```
Grep pattern="\*\*(Severity|Priority|Status|System|Category|Reported)\*\*" glob="production/qa/bugs/*.md" output_mode="content"
```
（Bug-report 的欄位是粗體，`**Severity**:`、`- **System**:`，所以要比對
`**field**` 這個形式，不是行首的 `Field:`。）
只有 `sprint`/`full` 模式的優先度 vs 嚴重度**重新評估**才需要完整的 bug 內文；
`trend` 是唯讀報告，會跳過它。（唯一需要 story 狀態的
偏差檢查，「bug 開在已完成的 story 上」，不管哪種都是針對性的 story 狀態 grep，不是讀 bug 內文。）

### Step 2b：載入 sprint context

讀 `production/sprints/` 裡最近修改的檔案，了解：
- 目前的 sprint 編號／名稱
- 範圍內的 stories（作為分派的目標）
- Sprint 容量限制（如果有註明）

如果沒有 sprint 檔案：註明 "No sprint plan found — assigning to backlog only."。在 `workflow: minimal`，依設計本來就沒有 sprint，要改說這件事，並把 P1 bug 指為下一批修正，排在 brief 的 build order 裡下一個 story 之前。

### Step 2c：載入嚴重度參考

如果 `.claude/docs/coding-standards.md` 有嚴重度／優先度定義，就讀它。如果沒有，
就用 Step 3 的標準定義。

---

## 3. 分類每個 Bug

每個 bug 都要擷取或推斷：

### Severity（bug 的影響）

| Severity | Definition |
|----------|-----------|
| **S1 — Critical** | Game crashes, data loss, or complete feature failure. Cannot proceed past this point. |
| **S2 — High** | Major feature broken but game is still playable. Significant wrong behaviour. |
| **S3 — Medium** | Feature degraded but a workaround exists. Minor wrong behaviour. |
| **S4 — Low** | Visual glitch, cosmetic issue, typo. No gameplay impact. |

### Priority（修正的緊急程度）

| Priority | Definition |
|----------|-----------|
| **P1 — Fix this sprint** | Blocks QA, blocks release, or is regression from last sprint |
| **P2 — Fix soon** | Should be resolved before the next major milestone |
| **P3 — Backlog** | Would be good to fix, but no active blocking impact |
| **P4 — Won't fix / Deferred** | Accepted risk or out of scope for current product scope |

### 分派

`sprint` 模式下，每個 P1/P2 bug：
- 找出這個修正屬於哪個 story 或 epic
- 檢查目前的 sprint 還有沒有剩餘容量
- 有容量：分派到 sprint（`Sprint: [current]`）
- 容量滿了：標記為 `Priority overflow — consider pulling from sprint`

`full` 模式：所有 P1 分派到目前的 sprint，P2 分到預估的下一個 sprint，
P3 以下放 backlog。

### 偏差檢查

標記暗示**系統性問題**的 bug：
- 同一個 sprint 裡同一個系統有 3 個以上 bug → "Potential design or
  implementation quality issue in [system]"
- 同一個 story 有 2 個以上 S1/S2 bug → "Story may need to be reopened and
  re-reviewed before shipping"
- bug 開在已標記 Complete 的 story 上 → "Regression in completed story —
  story should be re-opened in sprint tracking"

---

## 4. 趨勢分析

分類完所有 bug 之後，產生趨勢指標：

### 數量趨勢
- 還開著的 bug 總數：[N]
- 這個 sprint 新開的：[N]
- 這個 sprint 關閉的：[N]
- 淨變化：[+N / -N]

### 系統熱點
- 哪個系統還開著的 bug 最多？
- 哪個系統的 S1/S2 比例最高？

### 存活時間分析
- 有多少 bug 超過 2 個 sprint 了？
- 有沒有任何 S1/S2 bug 沒分派（sprint = none）？

### Regression 指標
- 有沒有任何 bug 開在先前已完成的 story 上？
- 數量：[N] 個 regression bug（意味著 story 要重開）

---

## 5. 產生 Triage 報告

```markdown
# Bug Triage Report

> **Date**: [date]
> **Mode**: [sprint | full | trend]
> **Generated by**: /bug-triage
> **Open bugs processed**: [N]
> **Sprint in scope**: [sprint name, or "N/A"]

---

## Triage Summary

| Priority | Count | Notes |
|----------|-------|-------|
| P1 — Fix this sprint | [N] | [N] assigned to sprint, [N] overflow |
| P2 — Fix soon | [N] | Scheduled for next sprint |
| P3 — Backlog | [N] | Deferred |
| P4 — Won't fix | [N] | Accepted risk |

**Critical (S1/S2) unfixed count**: [N]

---

## P1 Bugs — Fix This Sprint

| ID | System | Severity | Summary | Assigned to | Story |
|----|--------|----------|---------|-------------|-------|
| BUG-NNNN | [system] | S[1-4] | [one-line description] | [sprint] | [story path] |

---

## P2 Bugs — Fix Soon

| ID | System | Severity | Summary | Target Sprint |
|----|--------|----------|---------|---------------|
| BUG-NNNN | [system] | S[1-4] | [one-line description] | Sprint [N+1] |

---

## P3/P4 Bugs — Backlog / Won't Fix

| ID | System | Severity | Summary | Disposition |
|----|--------|----------|---------|-------------|
| BUG-NNNN | [system] | S4 | [one-line description] | Backlog |

---

## Systemic Issues Flagged

[List any patterns from Step 3 deviation check, or "None identified."]

---

## Trend Analysis

**Volume**: [N] open / [+N] net change this sprint
**Hot spot**: [system with most bugs]
**Regressions**: [N] bugs against completed stories
**Aged bugs (>2 sprints old)**: [N]

[If N aged S1/S2 bugs > 0:]
> ⚠️ [N] high-severity bugs have been open for more than 2 sprints without
> assignment. These represent accepted risk that should be explicitly reviewed.

---

## Recommended Actions

1. [Most urgent action — usually "fix P1 bugs before QA hand-off"]
2. [Second action — usually "investigate [hot spot system] quality"]
3. [Third action — optional improvement]
```

---

## 6. 寫入與把關

在對話裡呈現報告。如果有任何 bug 是 P4 候選，先問
"Are these acceptable as Won't Fix?"，在使用者回答之前，
它的處置維持 `P4 candidate`。然後問：

"May I write this triage report to `production/qa/bug-triage-[date].md`?"

核准後才寫。

寫完之後：
- 如果有任何 S1 bug 沒分派："S1 bugs must be assigned before the sprint
  can be considered healthy. Run `/sprint-status` to see current capacity."
- 如果有 regression bug："Regressions found — consider re-opening the
  affected stories in sprint tracking and running `/smoke-check` to re-gate."
- 如果沒有 P1 bug："No P1 bugs — build is in good shape for QA hand-off."

然後，不管有沒有 P1 bug：Verdict: **COMPLETE** — triage report written.

如果使用者拒絕寫入：Verdict: **BLOCKED** — user declined write.

---

## 協作協定

- **沒有使用者核准，絕對不要關閉 bug 或把它標成 Won't Fix**，
  把它們當成 P4 候選呈現，然後問："Are these acceptable as Won't Fix?"
- **絕對不要自動分派到已滿載的 sprint**：標記溢出，讓
  sprint 負責人決定要拉哪些進來
- **嚴重度是客觀的；優先度是團隊的決定**：嚴重度分類
  當成建議呈現，不是命令
- **趨勢資料只供參考**：不要光憑趨勢發現就擋住工作；
  把它們當成觀察呈現

---
name: bug-triage
description: "Re-evaluate open bugs — priority vs severity, assign to sprints, surface systemic trends. Run when the count grows."
argument-hint: "[sprint | full | trend]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash(bash "*/.claude/skills/bug-triage/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow`

**Automation mode**: Resolve `modes.automation` (`project.local.yaml` →
`project.yaml` → default `collaborative`). Every `AskUserQuestion` call and
every file write follows `.claude/docs/automation-modes.md`
(collaborative asks always · guided major-only · autonomous logs and proceeds;
`automation_always_ask` categories always prompt).

# Bug Triage

This skill processes the open bug backlog into a prioritised, sprint-assigned
action list. It distinguishes between **severity** (how bad is the impact?) and
**priority** (how urgently must we fix it?), detects systemic trends, and
ensures no critical bug is lost between sprints.

**Output:** `production/qa/bug-triage-[date].md`

**When to run:**
- Sprint start — assign open bugs to the new sprint or backlog
- After `/team-qa` completes and new bugs have been filed
- When the bug count crosses 10+ open items

---

## 1. Parse Arguments

**Modes:**
- `/bug-triage sprint` — triage against the current sprint; assign fixable bugs
  to the sprint backlog; defer the rest
- `/bug-triage full` — full triage of all bugs regardless of sprint scope
- `/bug-triage trend` — trend analysis only (no assignment); read-only report
- No argument — run sprint mode if a current sprint exists, else full mode

---

## 2. Load Bug Backlog

### Step 2a — Discover bug files

Glob for bug reports in priority order:
1. `production/qa/bugs/*.md` — individual bug report files (preferred format)
2. `production/qa/bugs.md` — single consolidated bug log (fallback)
3. Any `production/qa/qa-plan-*.md` "Bugs Found" table (last resort)

If no bug files found:
> "No bug files found in `production/qa/bugs/`. If bugs are tracked in a
> different location, adjust the glob pattern. If no bugs exist yet, there is
> nothing to triage."

Stop and report. Do not proceed if no bugs exist. Verdict: **COMPLETE** — no bug files in `production/qa/bugs/`; nothing to triage.

**In `trend` mode, do not read full bug bodies.** Trend metrics (volume, severity
mix, by-system, by-date) are computable from the header fields alone:
```
Grep pattern="\*\*(Severity|Priority|Status|System|Category|Reported)\*\*" glob="production/qa/bugs/*.md" output_mode="content"
```
(Bug-report fields are bolded — `**Severity**:`, `- **System**:` — so match the
`**field**` form, not a bare line-start `Field:`.)
Full bug bodies are needed only for the priority-vs-severity **re-evaluation** in
`sprint`/`full` modes; `trend` is a read-only report and skips it. (The one
deviation check that needs a story's status — "bug filed against a Complete
story" — is a targeted story-status grep either way, not a bug-body read.)

### Step 2b — Load sprint context

Read the most recently modified file in `production/sprints/` to understand:
- Current sprint number / name
- Stories in scope (for assignment target)
- Sprint capacity constraints (if noted)

If no sprint file exists: note "No sprint plan found — assigning to backlog only." At `workflow: minimal` there are no sprints by design — say that instead, and name the P1 bugs as the next fixes, ahead of the next story in the brief's build order.

### Step 2c — Load severity reference

Read `.claude/docs/coding-standards.md` for severity/priority definitions if they
exist. If they do not exist, use the standard definitions in Step 3.

---

## 3. Classify Each Bug

For each bug, extract or infer:

### Severity (impact of the bug)

| Severity | Definition |
|----------|-----------|
| **S1 — Critical** | Game crashes, data loss, or complete feature failure. Cannot proceed past this point. |
| **S2 — High** | Major feature broken but game is still playable. Significant wrong behaviour. |
| **S3 — Medium** | Feature degraded but a workaround exists. Minor wrong behaviour. |
| **S4 — Low** | Visual glitch, cosmetic issue, typo. No gameplay impact. |

### Priority (urgency of the fix)

| Priority | Definition |
|----------|-----------|
| **P1 — Fix this sprint** | Blocks QA, blocks release, or is regression from last sprint |
| **P2 — Fix soon** | Should be resolved before the next major milestone |
| **P3 — Backlog** | Would be good to fix, but no active blocking impact |
| **P4 — Won't fix / Deferred** | Accepted risk or out of scope for current product scope |

### Assignment

For each P1/P2 bug in `sprint` mode:
- Identify which story or epic the fix belongs to
- Check whether the current sprint has remaining capacity
- If capacity exists: assign to sprint (`Sprint: [current]`)
- If capacity is full: flag as `Priority overflow — consider pulling from sprint`

For `full` mode: assign all P1 to current sprint, P2 to next sprint estimate,
P3+ to backlog.

### Deviation check

Flag bugs that suggest **systematic problems**:
- 3+ bugs from the same system in the same sprint → "Potential design or
  implementation quality issue in [system]"
- 2+ S1/S2 bugs in the same story → "Story may need to be reopened and
  re-reviewed before shipping"
- Bug filed against a story marked Complete → "Regression in completed story —
  story should be re-opened in sprint tracking"

---

## 4. Trend Analysis

After classifying all bugs, generate trend metrics:

### Volume trends
- Total open bugs: [N]
- Opened this sprint: [N]
- Closed this sprint: [N]
- Net change: [+N / -N]

### System hot spots
- Which system has the most open bugs?
- Which system has the highest S1/S2 ratio?

### Age analysis
- How many bugs are older than 2 sprints?
- Are any S1/S2 bugs un-assigned (sprint = none)?

### Regression indicator
- Any bugs filed against previously-completed stories?
- Count: [N] regression bugs (story reopened implied)

---

## 5. Generate Triage Report

```markdown
# Bug Triage Report

> **Date**: [date]
> **Mode**: [sprint | full | trend]
> **Generated by**: /bug-triage
> **Open bugs processed**: [N]
> **Sprint in scope**: [sprint name, or "N/A"]

---

## Triage Summary

| Priority | Count | Notes |
|----------|-------|-------|
| P1 — Fix this sprint | [N] | [N] assigned to sprint, [N] overflow |
| P2 — Fix soon | [N] | Scheduled for next sprint |
| P3 — Backlog | [N] | Deferred |
| P4 — Won't fix | [N] | Accepted risk |

**Critical (S1/S2) unfixed count**: [N]

---

## P1 Bugs — Fix This Sprint

| ID | System | Severity | Summary | Assigned to | Story |
|----|--------|----------|---------|-------------|-------|
| BUG-NNNN | [system] | S[1-4] | [one-line description] | [sprint] | [story path] |

---

## P2 Bugs — Fix Soon

| ID | System | Severity | Summary | Target Sprint |
|----|--------|----------|---------|---------------|
| BUG-NNNN | [system] | S[1-4] | [one-line description] | Sprint [N+1] |

---

## P3/P4 Bugs — Backlog / Won't Fix

| ID | System | Severity | Summary | Disposition |
|----|--------|----------|---------|-------------|
| BUG-NNNN | [system] | S4 | [one-line description] | Backlog |

---

## Systemic Issues Flagged

[List any patterns from Step 3 deviation check, or "None identified."]

---

## Trend Analysis

**Volume**: [N] open / [+N] net change this sprint
**Hot spot**: [system with most bugs]
**Regressions**: [N] bugs against completed stories
**Aged bugs (>2 sprints old)**: [N]

[If N aged S1/S2 bugs > 0:]
> ⚠️ [N] high-severity bugs have been open for more than 2 sprints without
> assignment. These represent accepted risk that should be explicitly reviewed.

---

## Recommended Actions

1. [Most urgent action — usually "fix P1 bugs before QA hand-off"]
2. [Second action — usually "investigate [hot spot system] quality"]
3. [Third action — optional improvement]
```

---

## 6. Write and Gate

Present the report in conversation. If any bug is a P4 candidate, first ask
"Are these acceptable as Won't Fix?" and keep its disposition `P4 candidate`
until the user answers. Then ask:

"May I write this triage report to `production/qa/bug-triage-[date].md`?"

Write only after approval.

After writing:
- If any S1 bugs are unassigned: "S1 bugs must be assigned before the sprint
  can be considered healthy. Run `/sprint-status` to see current capacity."
- If regression bugs exist: "Regressions found — consider re-opening the
  affected stories in sprint tracking and running `/smoke-check` to re-gate."
- If no P1 bugs exist: "No P1 bugs — build is in good shape for QA hand-off."

Then, whether or not P1 bugs exist: Verdict: **COMPLETE** — triage report written.

If user declined write: Verdict: **BLOCKED** — user declined write.

---

## Collaborative Protocol

- **Never close or mark bugs Won't Fix without user approval** — surface them
  as P4 candidates and ask: "Are these acceptable as Won't Fix?"
- **Never auto-assign to a sprint at capacity** — flag overflow and let the
  sprint owner decide what to pull
- **Severity is objective; priority is a team decision** — present severity
  classifications as recommendations, not mandates
- **Trend data is informational** — do not block work on trend findings alone;
  surface them as observations