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

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。

1. 若 ticket 來自 verify-AC [VERIFICATION_FAIL]，走 AC-FAIL scoped path。
2. 否則判斷 fast path；明顯單檔小修可 inline analysis，其他走 Explorer full path。
3. 產出 Root Cause / Impact / Proposed Fix。
4. 向 RD 呈現分析並 hard stop；使用者確認前不得寫 JIRA 或 handoff。
5. 使用者修正時，最多 re-analyze 兩輪；仍不清楚則升級為人工 code confirmation。
6. 確認後，先 materialize final RCA comment artifact，再跑 workspace-language-policy.md

/ external write gate blocking validation；通過後才將 [ROOT_CAUSE] / [IMPACT] / [PROPOSED_FIX] 寫成 JIRA comment。

1. 處理 handbook observations。
2. 回報下一步：預設 /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：

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.