ddd.xreview

ddd.xreview — Cross Review

派多個獨立模型平行審查文件、規格一致性、實作與安全性，交叉比對 findings，由 coordinator 驗證 Critical/Important 再呈給使用者。主流程聚焦在「蒐集各方觀點 → 驗證 → 決策」，執行細節交給 orchestrator script。

嚴格禁令

• 禁止自動修改程式碼：review 產出建議，不直接改 code。修改必須由使用者確認後才執行
• 禁止省略任一 reviewer 的意見：即使結論相似，仍須完整呈現各方觀點
• 禁止以 main agent self-review 取代 cross review：所有 reviewer 都失敗時直接告知使用者，不自己頂上

執行步驟

1. 確認 Review 範圍

• Sprint 文件：當前 sprint 的 spec.md 路徑（若有已核可的 tasks.md 也一併提供）。
• Review Lens：依變更範圍判斷本次啟用哪些 lens。
  1. 只有文件變更 → Docs Lens
  2. 文件 + 實作變更 → Docs Lens、Spec Lens、Code Lens、Security Lens
  3. 只有實作變更且有 spec 或已確認 task source → Spec Lens、Code Lens、Security Lens
  4. 只有實作變更但無 spec 或已確認 task source → Code Lens、Security Lens，並標記無法驗證規格一致性
• Lens 摘要（詳細 checklist 由 ddd-reviewer agent definition 自帶）：
  • Docs：規格自洽、可測性、edge case、scope、決策紀錄
  • Spec：規格符合度、任務完成度、scope drift、測試對應、SSOT 同步
  • Code：correctness、資料安全、failure mode、相容性、DRY 風險、可觀測性
  • Security：auth、trust boundary、injection、secrets、data exposure、abuse、supply chain
• 變更範圍——依優先順序判斷，勿硬套 main：
  1. 使用者明確指定 → 直接採用（如「review changes from dev」→ git diff dev...HEAD）
  2. 使用者未指定 → 自動偵測上游：先查 tracking branch（git rev-parse --abbrev-ref @{upstream}），無則依序找 dev、main、master。偵測後用 Question Tool 確認：
     • 有未提交變更 → 確認要 review uncommitted 還是整個 branch diff
     • 在 feature branch 且無未提交變更 → 確認 git diff <upstream>...HEAD
     • 在 main/dev 上且無未提交變更 → 詢問要 review 什麼

各 reviewer 會自己讀檔案與跑 git，不需把完整內容塞進 prompt。

2. 組 Prompt 暫存檔

Reviewer prompt 只傳遞本次啟用的 lens 名稱；詳細 checklist 由 ddd-reviewer agent definition 自帶。

review_prompt_file=$(mktemp /tmp/xreview-XXXXXX.md) && cat > "$review_prompt_file" << 'XREVIEW_EOF'
請依照 ddd-reviewer 角色定義執行獨立 DDD review。

審查範圍：
- Sprint 規格：<spec.md 路徑>
- 任務來源：<spec.md Milestones；若有已核可 tasks.md 則填其路徑>
- 變更：請執行 `<git diff 指令>` 取得
- 本次啟用 lens：<Docs Lens / Spec Lens / Code Lens / Security Lens>

請依啟用的 lens 與 ddd-reviewer 角色定義審查。先讀取 sprint 文件理解目標、驗收條件與任務來源；任務來源預設為 spec.md Milestones，只有已核可的 tasks.md 才取代它（legacy tasks.md 僅供歷史參考，不作完成度判定）。最後檢視文件與程式碼變更。
XREVIEW_EOF
echo "$review_prompt_file"

審查方法論由各 reviewer 的 ddd-reviewer agent definition 自帶。

3. 派 Orchestrator

公開入口維持 skill-local script：scripts/xreview-orchestrator.sh。此檔案是 shared agent-runner.sh 的 symlink entrypoint；runner 會依 invocation basename 進入 xreview mode。Coordinator 不需也不應直接呼叫 shared runner 實體路徑。

Claude Code（Monitor 可用）：

Monitor({
  command: "bash ~/.claude/skills/ddd.xreview/scripts/xreview-orchestrator.sh $review_prompt_file; rc=$?; rm -f $review_prompt_file; exit $rc",
  timeout_ms: 3600000,
  persistent: false,
  description: "xreview 平行派 N 個 reviewer"
})

其他 host（Gemini / Codex / OpenCode，走 blocking mode）：

XREVIEW_MODE=blocking bash <skill-dir>/scripts/xreview-orchestrator.sh "$review_prompt_file"; rc=$?; rm -f "$review_prompt_file"; exit "$rc"

模型覆蓋、短名等用法見 references/cli-reference.md。

4. 收集並讀取結果

orchestrator 輸出 RETURN <spec> <log> <final> 和 FAIL <spec> ... 事件，以 ALL_DONE 收尾。Coordinator 必須先讀取各 RETURN 的 <final-path>，確認 reviewer report 內容後才進入整合；空檔標失敗。

事件格式與邊界案例見 references/orchestrator-internals.md。

5. 整合、驗證、回報

5.1 閱讀 reviewer reports

收到 RETURN 後，逐一讀取每份 <final-path>：

1. 確認 report 是否完整、可讀、且有明確 findings / 無 findings 結論
2. 標記失敗、空報告、格式不完整的 reviewer
3. 保留每位 reviewer 的原始觀點，後續整合時不得省略

5.2 組對照表

# Cross Review 報告

## Reviewer 組成
| Reviewer | 模型 | 狀態 |
|----------|------|------|
| claude | claude-opus-4-7 | ✅ 完成 |
| opencode | gpt-5.x | ✅ 完成 |
| gemini | gemini-3-pro-preview | ❌ 失敗（timeout） |

## 各 Reviewer 評估
<每個有效 reviewer 一個 section，完整呈現 review 結果>

## 交叉比對
| 問題 | claude | opencode | gemini | 共識 |
|------|--------|----------|--------|------|
| <問題摘要> | Critical/Important/未提及 | ... | ... | 一致/分歧 |

## 共識問題
<最值得優先處理>

## 分歧點
<意見不同之處>

## 共識優點
<多方都認可的設計>

5.3 Coordinator 驗證 Critical / Important findings

彙整完成後、回報給使用者前，coordinator 先自行驗證中～高嚴重度的 findings：

1. 從報告篩 Critical / Important findings
2. 逐一讀 finding 引用的程式碼確認問題是否真實存在
3. 標記每個 finding：
   • ✅ 確認：問題存在，附上修正建議與優先度
   • ⚠️ 存疑：無法確認或情境不明，保留給使用者判斷
   • ❌ False Positive：問題不存在或 reviewer 誤讀，說明理由

原則：驗證時讀實際程式碼，不靠 reviewer 描述；共識不等於正確，共識問題仍須驗證；低嚴重度直接帶過。

5.4 Decision Brief Gate

使用 Question Tool 前，必須先輸出足以讓使用者直接決策的 Decision Brief。不得只列 issue 標題或一句話摘要。

Decision Brief 至少包含：

1. Review 範圍、啟用 lens、reviewer 成功 / 失敗狀態
2. 每個待決策 issue 的 ID、嚴重度、提出者、驗證結果；ID 採 Issue #N 循序編號，與第 6 節 Question Tool 的 header 同一套編號
3. 證據：檔案路徑、行號、必要程式碼片段
4. 影響：不修會造成什麼風險
5. Coordinator 建議：建議優先處理順序、建議修法、可跳過項目與理由
6. ❌ False Positive 項目：每項一行帶過（finding 與駁回理由），不列入待決策

若一則訊息放不下，先分段輸出完整 Decision Brief，再提問。

5.5 Question Tool Gate

Question Tool 只收集決策，不補背景。每題必須引用 Decision Brief 中的 issue ID，且不可在 Question Tool 中首次揭露關鍵資訊。

Question Tool 的 preview 欄位僅在 host 支援時使用（例如 Claude Code）。若 host 不支援，程式碼片段必須放在 Decision Brief。

6. 逐條決策

對步驟 5.3 標記為 ✅ 確認 或 ⚠️ 存疑 的每個 issue，在 Decision Brief 已完整輸出後，用 Question Tool 逐條詢問使用者修正方向。

批次策略：Question Tool 每次最多 4 題，盡量一次問完。issues 超過 4 個時分批，每批一次 Question Tool call。

每個 issue 一題，格式：

• header："Issue #N"
• question：一句話詢問修正方向，引用 Decision Brief issue ID
• preview（規則見 5.5）：問題程式碼片段（含檔案路徑與行號）
• options：根據 reviewer 意見與 coordinator 驗證結果，列出具體可行的修法方案（各方案在 description 簡述怎麼改），加上「不修，跳過」。使用者可透過自動附加的 Other 給自訂指示

收集完所有決策後，彙整要修正的 issues 與對應方向，一次派 ddd-developer 執行。

修正完成並驗收後，由 coordinator 在當前 sprint 的 works.md 追加紀錄，不需要獨立開檔（works.md 整體格式見 /ddd.work）：

### xreview 修正

- **[finding 摘要]**：<修了什麼> → <測試結果>
- **[finding 摘要]**：<修了什麼> → <測試結果>

產出

• Cross Review 對照報告（對話中呈現）
• 使用者確認後的程式碼修正（由 ddd-developer 執行）
• 更新後的 works.md（xreview 修正紀錄）

結束條件

使用者確認 review 結果，修正完成（或決定不修正）。

進一步閱讀

• references/cli-reference.md — 模型覆蓋、短名、部署前提
• references/orchestrator-internals.md — 事件語意、timeout、content-layer 失敗、config
• references/cli-adapters.md — 各 CLI 的安裝、認證、JSON 抽取機制