plannotator-compound

複合式計畫分析

您正在對使用者的 Plannotator 計畫存檔進行全面的研究分析。目標：從被拒絕的計畫中提取模式，將其歸納為可行的洞察，並產出精美的 HTML 儀表板報告。

這是一個多階段的流程。每個階段必須完全完成後才能進入下一階段。研究誠信至關重要——每個檔案都必須讀取，不得跳過。

資料來源選擇

在開始分析之前，先確定可用的資料來源。

1. Plannotator 模式（首選） — 確定 Plannotator 資料目錄：如果設定了 $PLANNOTATOR_DATA_DIR 則使用該變數，否則使用 ~/.plannotator。檢查該目錄下的 plans/ 子目錄。如果存在且包含 *-denied.md 檔案，則使用此模式。以下整個工作流程都是針對 Plannotator 資料設計的。

2. Claude Code 回退模式 — 如果 Plannotator 存檔不存在或不包含任何被拒絕的計畫，請檢查 ~/.claude/projects/。如果存在，請在繼續之前閱讀 references/claude-code-fallback.md。該參考文件說明了如何使用附帶的解析器 scripts/extract_exit_plan_mode_outcomes.py 從 Claude Code JSONL 轉錄中提取拒絕原因。以下每個階段都有一個簡短的說明，指出在回退模式下需要更改的內容——參考文件中有詳細說明。

3. 兩者都不可用 — 詢問使用者他們的 Plannotator 計畫目錄或 Claude Code 專案目錄。不要猜測。

階段 0：定位計畫並檢查先前的報告

使用上方「資料來源選擇」中選擇的模式。

Plannotator 模式： 確認計畫目錄包含 *-denied.md 檔案。如果不存在，請在停止之前回退到 Claude Code 模式。

Claude Code 回退模式： 根據回退參考文件執行附帶的解析器，以建立拒絕原因資料集。如有需要，建立 /tmp/compound-planning/。

無論哪種模式，都繼續執行下方的「先前報告偵測」。

先前報告偵測

定位計畫目錄後，檢查是否存在現有報告：

ls ${PLANNOTATOR_DATA_DIR:-~/.plannotator}/plans/compound-planning-report*.html

報告遵循版本化命名規則：

• 第一份報告：compound-planning-report.html
• 後續報告：compound-planning-report-v2.html、compound-planning-report-v3.html，依此類推。

如果存在一份或多份報告，請確定最新的一份（版本號最高）。使用 stat 取得其檔案系統修改日期（macOS：stat -f %Sm -t %Y-%m-%d，Linux：stat -c %y | cut -d' ' -f1）。此日期即為截止日期。

向使用者提供選擇：

「我找到了一份先前的報告（compound-planning-report-v{N}.html），最後更新於 {CUTOFF_DATE}。我可以：

1. 增量 — 僅分析 {CUTOFF_DATE} 之後的檔案，節省 token 並建立在先前的發現之上
2. 完整 — 從頭開始重新分析整個存檔

您偏好哪一種？」

在繼續之前等待使用者的回應。

如果是增量： 將後續所有階段限制為僅處理日期在截止日期之後的檔案。新的報告版本將在其標題敘述中註明涵蓋從 {CUTOFF_DATE} 到現在的期間，並引用先前的報告以了解更早的發現。庫存（階段 1）仍應計算所有檔案的總體統計資料，但需清楚區分「自上次報告以來新增」的計數。

如果是完整： 正常處理所有檔案，但輸出檔案名稱仍使用下一個版本號。

如果沒有先前的報告： 正常進行。輸出檔案名稱將是 compound-planning-report.html（第一份報告無版本後綴）。

階段 1：庫存

計算並報告資料集。始終計算所有檔案以獲得總體統計資料，無論是增量還是完整執行：

- *-approved.md 檔案（計數）
- *-denied.md 檔案（計數）
- 日期範圍（檔案名稱中找到的最早到最晚日期）
- 涵蓋的總天數
- 修訂率：denied / (approved + denied) — 這是儀表板第 1 節中使用的「X% 的計畫在編碼前被修訂」統計資料

注意： 完全忽略 *.annotations.md 檔案。被拒絕的檔案已包含完整的計畫文字以及所有審查者的回饋（附加在 --- 分隔符號之後）。註釋檔案是此內容的多餘子集——讀取兩者會重複計算回饋。

如果是增量模式： 在總計數之後，分別報告僅截止日期之後的檔案計數：

自 {CUTOFF_DATE} 以來新增：
- *-denied.md 檔案：X（共 Y 個）
- 新日期範圍：{CUTOFF_DATE} 至 {LATEST_DATE}
- 新增涵蓋天數：N

如果自截止日期以來新增的被拒絕檔案少於 3 個，請警告使用者：

「自上次報告以來只有 {N} 個新的被拒絕計畫。增量分析可能內容不足。您要繼續還是切換到完整分析？」

同時對所有 *-approved.md 檔案執行 wc -l，以取得每個已批准計畫的平均行數。這可以告訴使用者他們的計畫是保持輕量還是隨著時間膨脹。您不需要讀取已批准計畫的內容——只需行數。如果可能，按時間段（例如每月）細分，以顯示計畫大小是否發生變化。

日期以 YYYY-MM-DD 格式出現在檔案名稱中，有時作為前綴（2026-01-07-name-approved.md），有時嵌入在中間（name-2026-03-15-approved.md）。從所有檔案名稱中提取日期。

告訴使用者您發現了什麼，並且您正在開始提取。

Claude Code 回退模式： 上述的 Plannotator 庫存欄位不適用。請改為遵循 references/claude-code-fallback.md 中的庫存說明——報告由解析器組合的拒絕原因資料集。

階段 2：映射——並行提取

這是最耗時的階段。您必須讀取範圍內的每個 *-denied.md 檔案。不要跳過檔案。不要過早總結。

範圍內 指的是：如果執行完整分析，則為所有被拒絕的檔案；如果執行增量分析，則僅為截止日期之後的被拒絕檔案。在增量模式下，僅處理其嵌入的 YYYY-MM-DD 日期嚴格在截止日期之後的檔案。

Claude Code 回退模式： 解析器輸出是乾淨的來源資料集。請閱讀回退參考文件，了解針對 JSON 部分檔案的提取提示和批次處理策略。除非解析器失敗或使用者要求審計級驗證，否則不要回到原始的 .jsonl 日誌。

重要： 僅讀取 *-denied.md 檔案。不要讀取已批准的計畫、註釋檔案或差異檔案。每個被拒絕的檔案都包含完整的計畫文字，後接 --- 分隔符號和審查者的回饋——分析所需的一切都在一個檔案中。

批次處理策略

所有提取代理應使用 model: "haiku"——它們執行的是直接的檔案讀取和結構化提取，而非推理。Haiku 對此類工作更快且更便宜。

方法取決於資料集大小：

小型資料集（≤ 10 個檔案）： 直接在主代理中讀取所有檔案——無需子代理。只需依序讀取它們，然後進入階段 3。

小型資料集（11-30 個檔案）： 啟動 2-3 個並行的 Haiku 代理，大致平均分配檔案。

中型資料集（31-80 個檔案）： 啟動 4-6 個並行的 Haiku 代理（每個約 10-15 個檔案）。按檔案類型和/或時間段分割。

大型資料集（80+ 個檔案）： 啟動所需數量的並行 Haiku 代理，使每個批次保持在 10-15 個檔案左右。按資料中的自然時間邊界（月、季或任何能產生平衡批次的群組）分割。如果某個時間段佔主導地位（例如，最近一個月的檔案數量是其他時間段的 3 倍），則將該時間段拆分為多個批次。

使用 Agent 工具並設定 run_in_background: true 和 model: "haiku" 來並行啟動所有提取代理。

輸出檔案

每個提取代理必須將其結果寫入一個乾淨的輸出檔案，而不是依賴代理任務輸出（其中包含交錯的 JSONL 框架日誌，難以解析）。指示每個代理寫入：

/tmp/compound-planning/extraction-{batch-name}.md

在啟動代理之前建立 /tmp/compound-planning/ 目錄。階段 3 中的歸納代理將直接讀取這些乾淨的檔案。

提取提示

每個代理收到以下指令（調整時間段、檔案清單和輸出路徑）：

您正在從被拒絕的計畫檔案中提取結構化資料，以進行模式分析。

目錄：[PLANS DIRECTORY]
要讀取的檔案：[特定 *-denied.md 檔案清單]
輸出：將您的完整結果寫入 [OUTPUT FILE PATH]

每個被拒絕的檔案包含兩個部分，由 --- 行分隔：
1. 計畫文字（在 --- 之上）
2. 審查者的回饋和註釋（在 --- 之下）

讀取清單中的每個檔案。對於每個檔案，提取：
- 計畫名稱/主題（來自 --- 之上的計畫文字）
- 給出的拒絕原因或回饋（來自 --- 之下——捕捉實際使用的詞語）
- 具體要求更改的內容
- 回饋類型（讓內容決定類別——不要強行套用預定義類型。常見類型包括：範圍問題、方法分歧、資訊缺失、流程要求、品質問題、UX/設計問題、命名爭議、澄清請求、測試/程序性拒絕——但使用者的實際模式可能不同）
- 審查者使用的任何特定短語或重複性語言
- 如果存在個別註釋（帶有引用文字和審查者評論的編號回饋項目）
- 日期（從檔案名稱中提取）

不要跳過任何檔案。每個檔案一個條目。

每個條目的格式為：
**[filename]**
- 日期：...
- 主題：...
- 拒絕原因：...
- 回饋類型：...
- 具體要求：...
- 值得注意的短語：...
- 註釋：[數量，附每個的簡要摘要]
---

處理完所有檔案後，將完整結果寫入 [OUTPUT FILE PATH]。在檔案末尾說明總檔案數。

代理執行期間

追蹤完成進度。每個代理完成時，記錄其處理的檔案數量。驗證總數是否與階段 1 的庫存相符。如果任何代理的計數不足，請標記並考慮為缺失的檔案重新啟動。

如果代理超時（大型批次可能發生——128 個檔案的批次可能需要 8 分鐘以上），則僅針對未處理的檔案重新啟動。檢查輸出檔案以了解它在超時前處理到哪裡。

階段 3：歸納——模式分析

當所有提取代理都完成後（或對於小型資料集，所有檔案都已讀取），繼續進行歸納。歸納代理應使用 model: "sonnet"——此階段需要真正的分析推理，而不僅僅是檔案讀取。

歸納策略

方法取決於產生了多少個提取檔案：

標準（≤ 20 個提取檔案）： 啟動一個 Sonnet 代理來讀取所有提取檔案並產生完整分析。這涵蓋了大多數資料集。

大型（21+ 個提取檔案）： 使用兩階段歸納：

1. 階段 1——部分歸納： 將提取檔案分成 4-6 個一組。啟動並行的 Sonnet 代理，每個讀取一組並產生部分分析，包含以下列出的相同章節。每個寫入 /tmp/compound-planning/partial-reduce-{N}.md。

2. 階段 2——最終歸納： 一個 Sonnet 代理讀取所有部分歸納檔案，並將其綜合為最終的全面分析。此代理合併分類、合併計數、去重模式，並協調部分之間任何衝突的分類。

Claude Code 回退模式： 歸納階段相同。唯一的上游差異是提取檔案來自標準化的拒絕原因 JSON，而非 Plannotator markdown 檔案。

歸納提示

為每個歸納代理提供以下提示（針對單階段與多階段調整檔案路徑）：

您是一位資料科學家，正在對使用者的被拒絕計畫存檔進行 map-reduce 分析的歸納階段。

讀取 [FILE PATHS] 的所有提取檔案

這些檔案包含來自每個被拒絕計畫檔案的結構化提取。每個提取包括計畫主題、拒絕回饋、註釋和審查者語言。您的工作：匯總所有內容，找出模式，聚類成分類，並產生全面分析。

要詳盡。使用真實計數。引用資料中的真實短語。這是研究——不要含糊其辭，不要捏造。

將您的完整結果寫入 [OUTPUT FILE PATH]。

產生以下章節：
[... 章節列於下方 ...]

歸納代理的工作是讓資料說話。不要強加預先定義的框架——發現實際存在的東西。分析必須產生：

1. 拒絕原因分類

將每個拒絕歸類為從資料中浮現的有限類型集合。計算出現次數。顯示百分比。為每種類型包含真實的範例引用。目標是 8-15 個類別——足夠具體，又易於瀏覽。讓使用者的實際回饋決定類別是什麼。

2. 頂級回饋模式（按頻率排序）

最常見的 5-10 個模式。每個模式包括：審查者 consistently 要求的內容、來自不同檔案的 3 個以上範例引用，以及該模式是否隨時間變化。

3. 重複出現的短語

審查者反覆使用的確切短語，附計數及其含義。這些是審查者的詞彙——他們對關心的事物的簡稱。

4. 審查者重視的內容（隱含偏好）

從模式中推導——這個特定的人最關心什麼？品質？速度？敘事？架構？流程？簡潔性？按證據強度排序。此部分應感覺像是審查者標準的人格側寫。

5. 代理 consistently 做錯的事

反面——哪些 recurring 的錯誤會觸發拒絕？代理應該停止為這位審查者做哪些事？

6. 結構性要求

審查者 consistently 要求的計畫結構是什麼？必需的章節、順序、格式偏好、預期的詳細程度。

7. 隨時間的演變

回饋模式在時間跨度內如何變化。按資料中存在的自然時間邊界分組（短時間跨度按週，較長時間跨度按月）。期望是否成熟了？是否出現了新模式？什麼改變了？如果資料集跨度少於一個月，請註明演變分析有限，但仍需尋找從早期到晚期檔案的任何進展。

8. 可行的提示指令

最重要的輸出。基於所有模式：可以嵌入規劃提示中的具體編號指令，以防止最常見的拒絕原因。將這些寫成代理可以遵循的實際指示。要針對此使用者的模式具體化——像「寫好計畫」這樣的通用建議是無用的。每個指令都應追溯到一個真實的、頻繁的拒絕模式。

編寫指令後，計算它們能解決的拒絕百分比（計算指令涵蓋的類別中的拒絕數量與總拒絕數量的比值）。報告此百分比——每個使用者都會不同。

階段 4：產生 HTML 儀表板

建立一個獨立的 HTML 檔案作為最終交付物。將其儲存到使用者的計畫目錄，並使用版本化的檔案名稱：

• 第一份報告：compound-planning-report.html
• 第二份報告：compound-planning-report-v2.html
• 第三份報告：compound-planning-report-v3.html
• 依此類推。

版本號在階段 0 中根據找到的現有報告確定。

如果是增量報告，標題應指明分析期間（例如「2026 年 3 月 15 日 – 3 月 31 日」），並包含副標題註明「增量分析——請參閱 v{N-1} 了解更早的發現」。第 1 節的敘述應將發現框架為自上次報告以來的新內容或變化，而非完整情況。標題中的總體統計資料（檔案計數、修訂率）仍應反映完整存檔以提供背景。

閱讀 assets/report-template.html 中的範本，僅用於設計語言。範本包含來自先前分析的範例資料——忽略範本中的所有資料值、引用和百分比。僅使用其視覺設計：顏色、字體、間距、元件樣式和佈局模式。

設計語言（來自範本）

• 調色板： 淺色模式，暖色米白（#FDFCFB），文字使用石板色系，琥珀色用於強調/重點，翡翠色用於正面，玫瑰色用於負面，靛藍色用於操作元素
• 字體： Playfair Display（襯線字體，用於敘事標題），Inter（無襯線字體，用於正文/資料），JetBrains Mono（等寬字體，用於程式碼/短語）——Google Fonts CDN
• 佈局： 單欄，最大寬度 1024px，慷慨的垂直空白（主要章節之間 128px），編輯/敘事優先的美學
• 基調： 冷靜、反思、權威。像個人回顧日記，而非監控儀表板。

頁面框架（頁首 + 頁尾）

在 7 個章節之前，頁面包含：

• 頁首： 左側報告標題（Playfair Display，約 36px），下方是專案名稱 + 日期範圍的淺色元文字。右側：等寬字體的檔案計數（例如「223 次拒絕 · 71 天」）。與內容由底部邊框分隔。在第 1 節之前有慷慨的底部內邊距。

• 頁尾： 第 7 節之後。頂部邊框，居中斜體 Playfair Display 標語，總結語料庫（例如「來自 Plannotator 存檔的 X 個被拒絕計畫的分析。」）。

儀表板章節順序（7 個章節）

報告遵循以下確切的章節順序。每個章節建立在上一章節的基礎上——流程從「發生了什麼」到「為什麼」再到「該怎麼做」：

1. 資料中的故事 — 一段編輯敘事段落（Playfair Display 襯線字體，約 26px），以散文形式講述標題發現。不是項目符號——是一段真實的段落，讀起來像文章的開頭。旁邊是一個 KPI 側邊欄，包含 3 個關鍵指標（最高拒絕百分比、總體修訂率以及發現的不同拒絕類別數量）。在敘事中最引人注目的數字上使用琥珀色內聯高亮。

2. 計畫被拒絕的原因 — 分類作為排名清單。每一行：排名數字（等寬字體）、類別標籤、一條細的 4px 進度條（頂部項目為 amber-500，其餘為 slate-300）、百分比（等寬字體），以及對於頂部條目，在標籤下方有一個真實的斜體引用。顯示前 10 個類別或資料支援的任意數量（至少 5 個）。

3. 期望如何演變 — 每個自然時間段一張卡片。每張卡片包含：襯線字體的時間段名稱、彩色大寫的主題短語（每個時間段不同顏色以顯示進展）、一段描述段落，以及底部的統計行（例如「X 次拒絕 · Y 個敘事請求」）。如果資料跨度少於 3 個不同的時間段，則使用 2 張卡片，甚至一張帶有內部進展說明的卡片。

4. 什麼有效 vs 什麼無效 — 兩張並排的卡片。左側：綠色調（emerald-50/50 背景，emerald-100 邊框），列出對此審查者成功的計畫特質。右側：紅色調（rose-50/50 背景，rose-100 邊框），列出代理一直做錯的事。兩者均來自歸納分析。使用帶有小彩色點的項目符號。每張卡片 5-8 個項目。

5. 可行的輸出 — 診斷的成果。以 Playfair Display 敘事句開頭，說明推導出多少條提示指令以及它們估計能解決的拒絕百分比（使用階段 3 中計算的實際百分比，而非通用數字）。然後是前 3 個最具影響力的改進，作為編號項目，每個帶有琥珀色數字、粗體標題和一行描述。此章節連接分析和後續的完整提示。

6. 您最常用的短語 — 晶片網格（行動裝置 2 欄，桌面 3 欄）。每個晶片：左側等寬字體引用的短語，右側頻率計數。白色背景，slate-200 邊框，rounded-12px。顯示 9-12 個最常出現的短語。這些應是審查者的實際詞語——他們的語言指紋。

7. 糾正性提示 — 深色面板（slate-900 背景，白色文字，rounded-3xl，shadow-xl）。以 Playfair 介紹句開頭，說明指令。然後是一個深色程式碼區塊（slate-800/80 背景，amber-200 等寬字體文字），包含階段 3 中完整的編號提示指令。包含一個可用的複製到剪貼簿按鈕（包含 JS）。在程式碼區塊下方：一個漸層光暈卡片（靛藍到紫色模糊光暈，後面是白色卡片），附帶結尾訊息，說明這些指令是個人化的——來自使用者自己的回饋、自己的語言、自己的標準。

適應規則

• 如果使用者資料少於 3 個月，將演變章節減少為更少的卡片
• 如果大多數被拒絕的檔案缺少 --- 下方的回饋（僅有拒絕而無註釋），請在敘事中註明——分析將較薄弱
• Claude Code 回退模式： 明確標記報告來源為 Claude Code ExitPlanMode 拒絕原因。不要捏造僅 Plannotator 才有的欄位，例如註釋計數或已批准計畫的行數。請參閱回退參考文件以了解 KPI 替代方案和頁尾/來源說明。
• 如果出現少於 5 個拒絕類別，將分類和模式章節合併為一個
• 如果資料集非常小（< 20 個檔案），敘事應承認樣本量有限，並將發現框架為初步結果
• 提示指令的數量因使用者而異——可能是 8 條或 20 條。不要強制設定為 17 條。讓資料決定數量。
• 第 5 節中的前 3 個可行項目必須是涵蓋最大拒絕份額的 3 個，而不是聽起來最令人印象深刻的 3 個

關鍵規則

1. 每個數字必須來自真實分析——不得捏造資料
2. 每個引用必須是真實檔案中的真實引用
3. 分類百分比必須根據真實計數計算
4. 提示指令必須追溯到實際的拒絕模式
5. 提示區塊上的複製按鈕必須有效（包含 JS）

產生後，在使用者的瀏覽器中開啟該檔案。

階段 5：摘要

告訴使用者：

• 分析了多少個被拒絕的檔案
• 如果是增量：自上次報告以來新增了多少個
• 發現的前 3 個拒絕模式
• 提示指令估計能解決的拒絕百分比
• 單一最有影響力的提示改進
• 報告儲存位置（包括版本號）
• 如果是增量：提醒使用者更早的發現位於先前的報告中

Claude Code 回退模式： 根據回退參考文件調整摘要——報告分析的人類拒絕原因數量和掃描的總 ExitPlanMode 嘗試次數，而非 Plannotator 檔案計數。

階段 6：改進鉤子

呈現摘要後，詢問使用者是否要啟用改進鉤子——這會將報告第 7 節中的糾正性提示指令寫入一個檔案，Plannotator 的 EnterPlanMode 鉤子可以自動將其注入到每個未來的規劃會話中。

「您要啟用改進鉤子嗎？這會將糾正性提示指令儲存到一個檔案中，該檔案會自動注入到所有未來的規劃會話中——這樣 Claude 在撰寫任何計畫之前就會看到您的回饋模式。」

如果是：

鉤子檔案位於：

${PLANNOTATOR_DATA_DIR:-~/.plannotator}/hooks/compound/enterplanmode-improve-hook.txt

如果資料目錄中不存在 hooks/compound/ 目錄，請建立它。

檔案內容應為階段 3 中的糾正性提示指令——與 HTML 報告第 7 節中出現的相同編號清單。將其寫為純文字，每行一條指令，前面加上編號。無 HTML、無 markdown 圍欄、無前言——僅指令本身。鉤子系統會將此檔案的內容原樣注入到規劃上下文中。

如果檔案已存在：

讀取現有檔案，並向使用者提供選擇：

「改進鉤子已存在於先前的分析中。我可以：

1. 取代 — 用新指令覆寫（舊指令將消失）
2. 合併 — 結合兩者，去重疊的指令，並保留每個指令的最佳版本
3. 保留現有 — 保持當前鉤子不變，跳過此步驟

您偏好哪一種？」

• 取代： 用新指令覆寫檔案。
• 合併： 讀取現有指令，與新指令比較，並產生合併集。移除重複項（即使措辭不同但意圖相同）。當兩條指令涵蓋相同模式時，保留更具體或更可行的版本。重新編號最終清單。將合併結果寫入檔案。向使用者顯示更改內容（新增 N 條新指令，移除 N 條冗餘指令，保留 N 條現有指令）。
• 保留現有： 不執行任何操作，繼續。

如果否： 完全跳過此階段。

重要注意事項

• 資料來源優先順序： Plannotator 是首選路徑。Claude Code 日誌分析是為沒有 Plannotator 存檔的使用者提供的次要路徑。
• 研究誠信： 每個檔案都必須讀取。此分析的價值來自於完整性。抽樣或跳過會削弱發現。
• 僅真實資料： 絕不捏造引用、百分比或模式。如果資料未顯示明確模式，請誠實說明，而不是發明一個。
• 讓資料主導： 分類、模式和指令應從檔案中的實際內容浮現。不同的使用者將有完全不同的拒絕模式。建立行動應用程式的使用者與建立 API 的使用者會有不同的回饋。不要假設模式會是什麼。
• 代理並行化： 對於大型資料集，最大化並行代理以減少實際時間。瓶頸是最大的批次——將其拆分。
• 結構化提取格式： 要求提取代理返回具有一致分隔符號的結構化文字，以便歸納代理能夠可靠地解析。
• 報告是成品： HTML 儀表板是使用者保留的內容。它應該美觀、誠實且有用。每個章節都應感覺像是專門為他們撰寫的，因為確實如此。