Bug Triage

---
name: bug-triage
description: >
  Bug diagnostic skill: root cause analysis and RD confirmation for Bug tickets.
  Use when the user wants to triage, analyze, or diagnose a Bug ticket — before planning starts.
  Trigger: '修 bug', 'fix bug', '分析 bug', 'triage bug', 'bug 分析', '修這張 bug',
  'help me fix', '幫我修正', '開始修正', '修正這張', 'fix this ticket' (when issue type is Bug),
  'debug', '找 bug', '為什麼壞了', 'why is this failing', 'investigate', '查問題',
  '這個怎麼回事', 'root cause', '根因', '排查'.
  NOT for: PR review fixes (use engineering revision mode), already-diagnosed bugs with root cause confirmed (use breakdown → engineering).
  This skill handles DIAGNOSIS only — estimation, test plan, QA challenge, and design doc are delegated to breakdown.
metadata:
  author: Polaris
  version: 2.4.0
---

# Bug Triage — 診斷層

Bug ticket 的診斷入口：讀票、定位 project、找 root cause、讓 RD 確認，最後把已確認分析寫回
JIRA，交給 `breakdown` 派工。

## Contract

`bug-triage` 只做 diagnosis。不估點、不拆 task、不寫 Design Doc、不建 branch、不修 code、
不開 PR。這些分別屬於 `breakdown` 與 `engineering`。

若 ticket 不是 Bug，停止並路由：Story/Task 走 `breakdown` 或 `engineering`，Epic 走
`refinement` 再 `breakdown`。若 JIRA 已有 `[ROOT_CAUSE]`，詢問要重新分析或直接派工。
Bug 的 planning handoff 仍以 confirmed RCA 為前提，但 direct-to-`engineering` 只在已存在
authoritative task work order 時合法；沒有 work order 時，下一步一律是 `/auto-pass {BUG_KEY}`。

## Reference Loading

| Situation | Load |
|---|---|
| Any bug | `bug-triage-entry-flow.md`, `project-mapping.md`, `workspace-config-reader.md` |
| AC verification failure bug | `bug-triage-acfail-flow.md`, `pipeline-handoff.md`, `handoff-artifact.md`, `worktree-dispatch-paths.md` |
| Root cause analysis | `bug-triage-root-cause-flow.md`, `explore-pattern.md`, `repo-handbook.md`, `planning-worktree-isolation.md` as needed |
| Confirmation and JIRA write | `bug-triage-confirm-handoff-flow.md`, `workspace-language-policy.md`, `external-write-gate.md` |

Explorer sub-agent dispatch 必須注入 `sub-agent-roles.md` 的 Completion Envelope。Full path 與
AC-FAIL path 的 raw evidence 寫入 handoff artifact，供 downstream engineering on-demand 讀取。

## Flow

1. Parse ticket key，讀 JIRA ticket，確認 issue type。
2. 依 `project-mapping.md` 與 workspace config 找 project，先讀 company handbook index +
   linked docs，再讀 repo handbook index + linked docs。
3. 若 ticket 來自 verify-AC `[VERIFICATION_FAIL]`，走 AC-FAIL scoped path。
4. 否則判斷 fast path；明顯單檔小修可 inline analysis，其他走 Explorer full path。
5. 產出 Root Cause / Impact / Proposed Fix。
6. 向 RD 呈現分析並 hard stop；使用者確認前不得寫 JIRA 或 handoff。
7. 使用者修正時，最多 re-analyze 兩輪；仍不清楚則升級為人工 code confirmation。
8. 確認後，先 materialize final RCA comment artifact，再跑 `workspace-language-policy.md`
   / external write gate blocking validation；通過後才將 `[ROOT_CAUSE]` / `[IMPACT]` /
   `[PROPOSED_FIX]` 寫成 JIRA comment。
9. 處理 handbook observations。
10. 回報下一步：預設 `/auto-pass {BUG_KEY}`；只有已存在 authoritative task work order 時才可
    提示 `做 {TICKET}`。

## Write Rules

- JIRA diagnostic comment 是 external write，送出前必須通過 `workspace-language-policy.md`
  或 external write gate，且先有 local final-comment artifact。Durable final-comment
  artifact 應寫入 `{source_container}/jira-comments/YYYYMMDD-root-cause.md`；只有真正
  temporary body file 可放在 `/tmp`，且 closeout 前必須刪除。
- 若 final RCA comment artifact 落在 `docs-manager/src/content/docs/specs/**/*.md`，
  必須走 specs-bound emit contract：frontmatter 至少包含 `title`、`description`、
  `draft: true`、`sidebar.hidden: true`，且 producer 對應
  `scripts/lib/evidence-producers.json` 的 bug-triage RCA entry。
- Handbook gap/stale updates 依 `explore-pattern.md`，只寫 workspace-owned handbook source。
- Bug-triage 不使用 blame 或 author attribution 決定誰修；assignee 是運維層，不是診斷輸入。

## Producer-Env Writer Rules (DP-228 T10)

`SKILL.md` 是 **documentation pointer**，不是 executable writer。寫入 specs-bound
artifact（例如 `{source_container}/jira-comments/*root-cause*.md`）的 writer authority
來自 producer-env + `scripts/lib/evidence-producers.json` registry。

寫 RCA comment artifact 前必須 `export POLARIS_SKILL_WRITER=bug-triage`，再呼叫 Claude
`Write` / `Edit` / `MultiEdit`：

```bash
export POLARIS_SKILL_WRITER=bug-triage
# 然後使用 Write tool 寫入 docs-manager/src/content/docs/specs/**/jira-comments/*root-cause*.md
```

- `POLARIS_SKILL_WRITER` 只允許設成 `bug-triage`；`no-direct-evidence-write` hook 會交叉
  比對寫入路徑是否屬於 bug-triage owning_skill entry，不符即 deny。
- 禁止用 Bash heredoc（`cat > specs/...root-cause.md <<'EOF'`）寫 RCA artifact；Bash
  heredoc 不走 hook，繞過 producer-env 認證與 specs-bound emit contract。
- temporary `/tmp` body 不受此規則約束（不屬於 specs-bound surface），但 durable
  artifact 落到 `docs-manager/src/content/docs/specs/**` 一律走 producer-env 路徑。

## Completion

輸出 ticket、root cause confirmed status、JIRA comment status、proposed fix scope、
evidence artifact path（fast path 可為 none）、next command。`next command` 預設是
`/auto-pass {BUG_KEY}`；只有已存在 authoritative task work order 時才是 `做 {TICKET}`。

## Step 11 — L2 Deterministic Check: post-task-feedback-reflection

完成 write flow 後必須呼叫 `scripts/check-feedback-signals.sh`，再執行 Post-Task Reflection。

## Post-Task Reflection (required)

Execute `post-task-reflection-checkpoint.md` before reporting completion.