ce-doc-review

文件審查

透過多人格分析審查需求或計畫文件。分派以技能本機審查提示資產初始化的通用子代理，自動套用 safe_auto 修正，並將剩餘發現透過四選一互動（逐項檢視、以最佳判斷自動解決、附加至待解決問題、僅回報）交由使用者決定。

設定

在本次呼叫開始時執行一次，在任何子代理分派之前，並遵循其輸出的指示——除非與本技能自身關於詢問使用者問題的規則衝突，無論這些規則是否限定於非互動模式或適用於所有模式，此時本技能的規則優先，且不提出阻塞性問題。在同一呼叫內不要重新執行；稍後對本技能或其他技能的呼叫會執行各自的設定。如果沒有 Node 執行環境，技能照常進行。

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
NODE="$(for c in node nodejs; do command -v "$c" >/dev/null 2>&1 && "$c" -e '' >/dev/null 2>&1 && { echo "$c"; break; }; done)";
if [ -n "$NODE" ]; then
"$NODE" "$SKILL_DIR/scripts/context.mjs" || echo "context script failed; continue with the skill's normal behavior";
else
echo "no Node runtime; continue with the skill's normal behavior";
fi

互動模式規則

• 在任何問題觸發前預先載入平台問題工具。 在 Claude Code 中，AskUserQuestion 是延遲工具——其 schema 在 session 開始時不可用。在互動模式工作開始時（在路由問題、逐項檢視問題、批次預覽的 Proceed/Cancel 以及第 5 階段終端問題之前），呼叫 ToolSearch 並查詢 select:AskUserQuestion 以載入 schema。在互動流程頂端立即載入一次，不要等到第一個問題點。在 Codex、Gemini 和 Pi 上不需要此預載。
• 編號清單的後備方案僅在 harness 確實缺乏阻塞性問題工具時適用——ToolSearch 回傳無相符結果、工具呼叫明確失敗，或執行模式未暴露該工具（例如 Codex 編輯模式中 request_user_input 不可用）。待處理的 schema 載入不是觸發後備方案的條件；請依預載規則先呼叫 ToolSearch。在真正的後備情況下，以編號清單呈現選項並等待使用者回覆——絕不要靜默跳過問題。因為工具不便、模型處於報告格式化模式，或指示埋在長技能中，而將問題以敘述文字呈現，是錯誤。需要使用者決定的問題必須觸發工具或大聲後備。

第 0 階段：偵測模式

檢查呼叫參數中是否有 mode:headless。參數可能包含文件路徑、mode:headless 或兩者。以 mode: 開頭的 token 是旗標，不是檔案路徑——將它們從參數中移除，並將剩餘 token（如果有）用作第 1 階段的文件路徑。

如果存在 mode:headless，將工作流程的其餘部分設定為 headless 模式。

Headless 模式 改變互動模型，而非分類邊界。對每個發現屬於哪個層級套用相同的判斷。只有非 safe_auto 發現的傳遞方式改變：

• safe_auto 修正靜默套用（與互動模式相同）
• gated_auto、manual 和 FYI 發現以結構化文字回傳給呼叫者處理——無阻塞性問題提示、無互動路由
• 第 5 階段立即回傳「Review complete」（無路由問題、無終端問題）

呼叫者接收帶有原始分類的發現，並決定如何處理。

Headless 參數契約： 要求 mode:headless <document-path>，例如 mode:headless <path-to-doc>.md。

如果不存在 mode:headless，以預設互動模式執行，包含路由問題、逐項檢視和批次預覽行為，如 references/walkthrough.md 和 references/bulk-preview.md 所述。

產物根目錄

此技能審查傳入路徑的文件，在互動模式且未提供路徑時，會發現 <root>/plans/ 下最新的計畫。僅在該無路徑發現分支中解析 <root>（依下方區塊）——這是唯一組合 <root>/ 路徑的地方。對明確命名文件的審查直接讀取該路徑，且永不解析 <root>；不要在每次執行開始時執行根目錄解析，因為有效的 headless 或絕對路徑審查（例如 /tmp/plan.md，可能在任何 git repo 之外）不得依賴它不需要的 repo 根目錄或 CE 設定。

<!-- ce-docs-root:start -->
在組合任何產物路徑之前解析 CE 產物根目錄 <root>。

• 讀取 <repo-root>/.compound-engineering/config.local.yaml 中的 docs_root，然後是 config.yaml；第一個非空值勝出（<repo-root> = git rev-parse --show-toplevel）。未設定 -> <root> 是 docs，與之前完全相同。
• 驗證 設定的值：repo 相對目錄，其真實、symlink 解析後的路徑必須保持在 repo 內，且既不是 repo 根目錄也不在 .git/ 下。否則以錯誤停止，指出 docs_root 和該值——絕不後備到 docs。
• 使用 <root> 作為唯一的產物位置：若不存在則建立，將每個路徑組合成 <root>/<subdir> 並使用本技能自己的子目錄，且絕不也讀取 docs。
  <!-- ce-docs-root:end -->

第 1 階段：取得並分析文件

如果提供了文件路徑： 讀取它，然後繼續。如果讀取失敗或檔案不在磁碟上，套用下方的缺失文件閘道，而不是繼續。

如果未指定文件（互動模式）： 詢問要審查哪份文件，或使用檔案搜尋/glob 工具（例如 Claude Code 中的 Glob）在 <root>/plans/ 下找到最新的。

如果未指定文件（headless 模式）： 輸出「Review failed: headless mode requires a document path. Expected arguments: mode:headless <path>」並停止，不分派審查者。

缺失文件閘道——在任何分派前驗證。 Persona 審查者從檔案系統讀取文件，且部分在沒有 Bash 的情況下執行，因此無法讀取 git refs——僅存在於未 checkout 分支上的路徑會浪費整個 persona 團隊發現無法繼續（issue #925）。在第 2 階段之前，確認每個解析的文件路徑在磁碟上可讀（上述 Read 成功）。位置無關：checkout 之外的絕對路徑（例如 /tmp/plan.md）或其他 checkout 中的文件都可以正常審查。如果任何路徑不可讀，不要分派任何 persona：

• 互動模式： 停止並指出缺失路徑：「Document(s) not found on disk: <paths>. Check out the branch containing them, use a worktree, or provide corrected readable paths before retrying the review.」
• Headless 模式： 輸出「Review failed: document(s) not found on disk: <paths>. Expected input: paths to readable files on disk; check out the branch containing them or provide corrected paths.」並回傳，不分派審查者。

分類文件類型

透過閱讀文件的內容形狀和中繼資料來分類，而非檔案路徑。在統一計畫契約下，僅需求文件和可實作計畫都位於 <root>/plans/，因此位置不再指示類型——需求風格的文件分類為 requirements，計畫形狀的文件分類為 plan，無論位於何處。下方的審查者根據此分類以不同方式運作，因此將計畫形狀的文件誤分類為需求文件（或反之）會產生嘈雜或審查不足的發現。

首先檢查統一產物契約：

• artifact_contract: ce-unified-plan/v1 加上 artifact_readiness: requirements-only -> 分類為 unified-requirements。僅審查 Product Contract；缺少 Planning Contract、Implementation Units、Verification Contract 或 Definition of Done 是預期的，不得標記。
• artifact_contract: ce-unified-plan/v1 加上 artifact_readiness: implementation-ready -> 分類為 unified-plan。以不同視角審查 Product Contract 和 Planning Contract，然後審查 Implementation Units/Verification/DoD 的執行完整性。
• HTML 統一產物（.html）以僅回報模式讀取/審查。不要對 HTML 套用 markdown 變更路徑。如果呼叫者要求變更/自動修正行為，以現有的僅 markdown 訊息跳過，或回傳僅回報發現。
• 無效的進度類 readiness 值（active、in_progress、completed、done）是文件契約發現，不是要遵循的執行狀態。

使用這些訊號來決定：

requirements 訊號（建構什麼的文件）：

• Frontmatter 欄位如 actors:、flows:、acceptance_examples: 或 status: 帶有 brainstorm 形狀的值
• 章節標題如 Acceptance Examples、Actors、Key Flows、User Flows、Outstanding Questions、Resolve Before Planning
• 編號識別碼形式如 R1、R2、A1、F1、AE1——需求、參與者、流程和驗收範例 ID
• 散文框架聚焦於使用者/商業問題、行為、範圍邊界、成功標準
• 沒有實作單元、沒有每單元檔案清單、沒有附加到單元的測試情境

plan 訊號（如何建構的文件）：

• Frontmatter 欄位如 type: feat|fix|refactor、origin: docs/brainstorms/... 或 product_contract_source: ce-brainstorm|ce-plan-bootstrap|legacy-requirements
• 章節標題如 Implementation Units、Output Structure、Key Technical Decisions、Risks & Dependencies、System-Wide Impact
• 編號識別碼形式如 U1、U2——實作單元 ID
• 每單元欄位名為 Goal、Files、Approach、Test scenarios、Verification
• Repo 相對檔案路徑以建立/修改/測試
• 散文框架聚焦於技術決策、排序和實作者導向細節

平手規則。 當內容訊號混合或稀疏時，將主導內容形狀視為權威；如果形狀真正模糊，預設為 requirements（較保守的分類——啟動較少的計畫特定可行性檢查）。路徑位置在統一計畫契約下不消除類型歧義，其中僅需求文件和可實作計畫共享 <root>/plans/；舊版 origin: docs/brainstorms/... 欄位，如果存在，仍依上方 frontmatter 清單讀作 plan 訊號。

將分類結果透過子代理模板中的 {document_type} 槽傳遞給每個 persona。Personas 讀取此並相應調整其分析。

選擇條件式 Personas

分析文件內容以決定啟動哪些條件式 personas。檢查這些訊號：

product-lens —— 當文件對建構什麼及為何提出可挑戰的主張，或提議的工作承載超出即時問題的策略重量時啟動。系統的使用者可能是終端使用者、開發者、操作者、維護者或任何其他受眾——標準是領域無關的。檢查任一條件：

條件 1 — 前提主張： 文件對建構什麼或為何提出知識淵博的利害關係人可能合理挑戰的立場——不僅是描述任務或重述已知需求：

• 問題框架中陳述的需求不明顯或可辯論，而非從現有脈絡自明
• 解決方案選擇中存在合理的替代方案（隱式或顯式）
• 明確排序建構什麼與延後什麼的優先順序決策
• 預測特定使用者結果的目標陳述，而非僅重述限制或描述交付物

條件 2 — 策略重量： 提議的工作可能影響系統軌跡、使用者感知或競爭定位，即使前提健全：

• 塑造系統如何被感知或以其聞名的變更
• 影響採用、入門或認知負荷的複雜性或簡潔性賭注
• 開啟或關閉未來方向的工作（路徑依賴、架構承諾）
• 機會成本影響——建構此意味著不建構其他

design-lens —— 當文件包含以下內容時啟動：

• UI/UX 參考、前端元件或視覺設計語言
• 使用者流程、線框、畫面/頁面/視圖提及
• 互動描述（表單、按鈕、導覽、模態框）
• 響應式行為或無障礙的參考

security-lens —— 當文件包含以下內容時啟動：

• 認證/授權提及、登入流程、session 管理
• 暴露給外部客戶端的 API 端點
• 資料處理、PII、付款、token、憑證、加密
• 具有信任邊界影響的第三方整合

scope-guardian —— 當文件包含以下內容時啟動：

• 多個優先順序層級（P0/P1/P2、必須/應該/可有可無）
• 大量需求（>8 個不同需求或實作單元）
• 延伸目標、可有可無或「未來工作」章節
• 與陳述目標不一致的範圍邊界語言
• 與需求未清楚連結的目標

adversarial —— 當文件包含高價值挑戰表面時啟動，而非僅結構複雜性。具有陳述理由的例行計畫本身不是 adversarial 訊號——當唯一訊號是「此計畫結構良好」時，前提/假設工作會重新爭論已解決的問題。當以下任一條件成立時啟動：

• 文件是需求文件，具有 2+ 個可挑戰主張（問題框架、解決方案選擇、優先順序、預測結果）——前提審查是 brainstorm 階段的核心
• 文件觸及高風險領域——認證、付款、計費、資料遷移、隱私/合規、外部整合、加密——無論文件類型或大小
• 文件提議新的抽象、框架或重要架構模式——無論文件類型
• 文件是沒有驗證的上游 Product Contract 訊號的計畫（沒有舊版 origin: 需求文件，也沒有 product_contract_source: ce-brainstorm 或 legacy-requirements）——前提未在上游驗證
• 文件是明確延伸範圍超出其來源需求文件的計畫（新參與者、新流程、延後再恢復的功能）
• 文件包含明確的替代方案章節或未解決的取捨——adversarial 有助於壓力測試所選方向

不要在從驗證的上游 Product Contract 衍生、保持在範圍內且不引入高風險領域或新抽象的例行計畫文件上啟動 adversarial。驗證的上游來源包括舊版 origin: docs/brainstorms/...、product_contract_source: ce-brainstorm 和 product_contract_source: legacy-requirements。直接 product_contract_source: ce-plan-bootstrap 的計畫是 greenfield，且本身不會壓制前提層級技術。計畫的結構決策（更多單元、更多理由）本身不是 adversarial 訊號——那些是計畫在做好本職工作。

第 2 階段：宣布並分派 Personas

宣布審查團隊

告訴使用者哪些 personas 將審查及原因。對於條件式 personas，包含理由：

Reviewing with:
- coherence-reviewer (always-on)
- feasibility-reviewer (always-on)
- scope-guardian-reviewer -- plan has 12 requirements across 3 priority levels
- security-lens-reviewer -- plan adds API endpoints with auth flow

建立代理清單

始終包含：

• coherence-reviewer
• feasibility-reviewer

加入啟動的條件式 personas：

• product-lens-reviewer
• design-lens-reviewer
• security-lens-reviewer
• scope-guardian-reviewer
• adversarial-document-reviewer

分派

使用平台的子代理原語（例如 Claude Code 中的 Agent、Codex 中的 spawn_agent）以有界並行分派通用子代理（如果可用）；否則內聯或序列執行工作。省略 mode 參數，以便套用使用者設定的權限設定。尊重目前 harness 的活動子代理限制：將選定的審查者排入佇列，僅分派 harness 接受的数量，並在審查者完成時填補釋放的槽位。將活動代理/執行緒/並行限制的 spawn 錯誤視為背壓，而非審查者失敗：將審查者保留在佇列中，並在槽位釋放後重試。僅在成功分派逾時/失敗，或分派因非容量原因失敗時，才將審查者記錄為失敗。

對於每個選定的審查者，讀取 references/personas/<reviewer-name>.md 中相符的技能本機提示資產，並將其完整內容作為 {persona_file} 傳遞。不要按類型/名稱分派獨立代理，也不要依賴平台級自訂代理註冊。

模型分層在此處，而非提示資產中。 本機提示檔案沒有 frontmatter，也不攜帶模型中繼資料。當平台暴露已知模型覆寫時套用這些分派時偏好；否則省略覆寫並繼承父模型，而不是猜測平台特定模型名稱：

• coherence-reviewer：最便宜的能幹提取/推理層級。
• design-lens-reviewer、scope-guardian-reviewer：平台中層模型。
• security-lens-reviewer、feasibility-reviewer、product-lens-reviewer、adversarial-document-reviewer：繼承父模型，除非 harness 有既定的高能力審查層級。

每個子代理接收從下方包含的子代理模板建立的提示，並填入這些變數：

變數	值
{persona_file}	從 references/personas/ 選定的本機提示資產的完整內容
{schema}	下方包含的發現 schema 的內容
{document_type}	第 1 階段分類的 "requirements"、"plan"、"unified-requirements" 或 "unified-plan"
{document_path}	文件的路徑
{origin_path}	第 1 階段提取一次的上游 Product Contract 來源：偏好文件的 origin: frontmatter 欄位（如果存在）；否則使用 product_contract_source:<value>（如果存在）；否則使用 none。根據 origin/provenance 調整的 personas（product-lens、adversarial、scope-guardian）讀取此槽以閘控技術壓制——他們不會自己重新解析 frontmatter。
{settled_ktds}	第 1 階段提取一次的 session 已解決決策：任何攜帶 session-settled: 註記的 Key Technical Decision 或 Product Contract Key Decision 條目，列為決策名稱、類別（user-directed / user-approved）和拒絕的替代方案；或當文件沒有此類條目時為字面 none。Personas 讀取此槽——他們不會為此重新解析文件。
{document_content}	審查者特定章節切片。對於統一產物，傳遞中繼資料、Goal Capsule 和僅相關切片：product-lens/adversarial/scope 審查者取得 Product Contract；feasibility/coherence 審查者在 artifact_readiness: implementation-ready 時也取得 Planning Contract 和活動的 Implementation Units/Verification/DoD。對於舊版文件，傳遞完整文件。
{decision_primer}	目前 session 中累積的先前回合決策，或第 1 回合的空 <prior-decisions> 區塊。請參閱下方「Decision primer」。

對於舊版需求/計畫文件，將完整文件傳遞給每個子代理——不要分割成章節。對於統一產物，預設不要將完整產物傳遞給每個審查者：統一計畫可能很大，因此章節切片（依上方 {document_content} 槽）是預設。僅當審查者需要初始切片無法評估的跨章節可追溯性時，才升級到更廣的切片。

Decision primer

在第 1 回合（無先前決策），將 {decision_primer} 設定為：

<prior-decisions>
Round 1 — no prior decisions.
</prior-decisions>

在第 2 回合以上（目前互動 session 中一或多個先前回合之後），累積先前回合決策並呈現為：

<prior-decisions>
Round 1 — applied (N entries):
- {section}: "{title}" ({reviewer}, {confidence})
  Evidence: "{evidence_snippet}"

Round 1 — rejected (M entries):
- {section}: "{title}" — Skipped because {reason}
  Evidence: "{evidence_snippet}"
- {section}: "{title}" — Deferred to Open Questions because {reason or "no reason provided"}
  Evidence: "{evidence_snippet}"
- {section}: "{title}" — Acknowledged without applying because {reason or "no suggested_fix — user acknowledged"}
  Evidence: "{evidence_snippet}"
- {section}: "{title}" — Withdrawn because {triggering decision}
  Evidence: "{evidence_snippet}"

Round 2 — applied (N entries):
...
</prior-decisions>

每個條目攜帶 Evidence: 行，因為合成 R29（拒絕發現壓制）和 R30（修正落地驗證）都使用證據子字串重疊檢查作為其匹配謂詞的一部分——沒有 primer 中的證據片段，orchestrator 無法計算 >50% 重疊測試，必須回退到僅指紋匹配，這會重新浮現被拒絕的發現或過度壓制。{evidence_snippet} 是發現的第一個證據引用，截斷至前約 120 個字元（在邊界保留完整單詞），並轉義內部引用。如果發現有多個證據條目，使用第一個；其餘存在於執行產物中，不需要用於重疊檢查。

在目前 session 的所有回合中累積。Skip、Defer 和 Acknowledge 動作都計為「rejected」以用於壓制——每個都表示使用者決定該發現不值得本回合處理（Acknowledge 是無修正守衛變體：使用者看到沒有 suggested_fix 的發現，選擇不明確 defer 或 skip，而是記錄 acknowledgement；對於回合間壓制，這在語義上等同於 Skip）。Withdraw 是有條件的（它是重新驗證變體：先前的決策解決或矛盾了發現；請參閱 references/walkthrough.md 中的「Withdrawing findings the user's earlier answers resolved」）：僅當使用者決策使其退役時——已解決的前提（Skip/Defer）或使用者主張的事實——才計為 rejected 類別。Apply 觸發的 Withdraw 永不計為（其解決依賴於暫存編輯既落地又語義上解決發現，這由第 N+1 回合重新合成檢查——而非 R29；壓制它會隱藏失敗或無效落地的修正）。已套用的發現保留在已套用清單上，以便第 N+1 回合 personas 驗證修正已落地（請參閱 references/synthesis-and-presentation.md 中的 R30）。

跨 session 持久化超出範圍。稍後對同一文件的審查以全新的第 1 回合開始，沒有攜帶的 primer，即使先前 session 將發現延後到文件的 Open Questions 章節。

錯誤處理： 如果子代理失敗或逾時，使用已完成的子代理的發現繼續。在 Coverage 章節中註記失敗的審查者。不要因單一審查者失敗而阻塞整個審查。

分派限制： 即使在最大（7 個代理），使用有界並行分派。如果 harness 上限低於選定團隊大小，將其餘排入佇列，並在活動審查者完成時啟動。

跨模型判斷傳遞

如果條件式判斷三人組中的任何一個——adversarial-document-reviewer、product-lens-reviewer、security-lens-reviewer——被啟動，載入 references/cross-model-review.md 並遵循它進行附加的、非阻塞的同儕傳遞。將主機證明為 harness 加服務家族，為整個文件解析一個目標和一個具體路由，驗證每個實際接收者符合 egress 允許清單，並在內容離開主機前揭露和制裁該固定路由。cursor 表示 Cursor 預設/自動；composer 表示透過 Cursor 的明確 Composer 家族模型。先嘗試宣告的對應；僅在觀察到不相容後，目標綁定的同家族模型覆寫可以調整過時的預設。絕不靜默變更明確的模型或接收者，也絕不讓分派的工作者選擇變更接收者的後備。

為每個啟動的三人組透鏡啟動一個分離的 runner 工作，加上一個 whole-doc 掃描，與處理中的審查者同一波，使用參考中的確切呼叫契約。每個三人組同儕接收其孿生的相同審查者特定切片；whole-doc 接收完整文件。所有呼叫使用相同的制裁目標/路由。透過 runner 輪詢、收割、歸因和清理；失敗或逾時保持非阻塞，並在 Coverage 中命名。將發現摺疊進普通合成，但協議提升要求產物頂層 independence_verified: true；false 或缺失的獨立性是有用的證據，而非不同模型的佐證。可行性和收斂透鏡（coherence、scope-guardian）不執行跨模型。

第 3-5 階段：合成、呈現和後續動作

在所有分派代理回傳後——包括任何跨模型 <reviewer-name>-<provider>.json 回傳——讀取 references/synthesis-and-presentation.md 以了解合成管線（驗證、基於錨點的閘道、去重、條件式協議提升、解決矛盾、自動提升、依三個層級路由並帶 FYI 子章節）、safe_auto 修正套用、headless 信封輸出，以及路由問題的交接。同儕發現進入普通合成，但只有具有 independence_verified: true 的產物才計為獨立審查者以用於提升。

對於四選一路由問題和逐項檢視（互動模式），讀取 references/walkthrough.md。對於最佳判斷路由、Append-to-Open-Questions 和逐項檢視的 Auto-resolve with best judgment on the rest 使用的批次動作預覽，讀取 references/bulk-preview.md。在代理分派完成前不要載入這些檔案。

---

包含的參考

子代理模板

@./references/subagent-template.md

發現 Schema

@./references/findings-schema.json

選定的審查者提示資產位於 references/personas/ 下。僅讀取目前審查選定的提示檔案。