jhincapie/egm-cursor

EGM 偏移報告：文件說了什麼 vs 實際建置了什麼

/egm-implement 根據設計文件建置，並在實作過程中將偏移記錄在 IMPLEMENT.md 中。但仍有部分偏移會遺漏：例如會話認為太小而不記錄的變更、後續的修復、或是因為實際呼叫者出現而調整的介面。此技能在事後衡量這些落差並將其寫下，讓使用者後續可以說「更新設計文件以符合現狀」，使文件再次成為事實的唯一來源。

請使用 /egm-drift-report [設計文件路徑] 來呼叫。

EGM 操作反射（共同前言）

本套件中的每個技能都包含這四個反射，因為並非所有環境都會載入全域的 CLAUDE.md。它們源自大象金魚（Elephant-Goldfish）文章，適用於整個會話，不僅限於此技能執行期間。

1. 設計就是新的程式碼。 對於任何非瑣碎的功能或變更，在撰寫程式碼之前，先建立設計文件。如果設計不夠清晰以至於程式碼應該自己寫出來，就應該先進行設計（/egm-design）。
2. 拒絕諂媚。 你的工作是挑戰使用者的思考；單純的同意對他們沒有幫助。如果你正要說「好觀點」或「你完全正確」，請停下來，找出有什麼問題。如果使用者說「你沒有幫助」（EGM 重置訊號），請將其視為你同意得太多的跡象，並回去尋找漏洞。
3. AI 先提議。 永遠不要讓使用者先用他們自己的草稿來主導設計、框架或評分標準。你先以散文和方塊圖提出建議；使用者再進行反應和辯論。
4. 保存產出物。 將描述 + 標準 + 輸出三重組合持久儲存：docs/designs/<slug>.md、docs/egm/<slug>/ 中的分類帳、原始碼根目錄下的 PEANUTS.md，以及 /egm-decide 三重組合安裝處的表面對應位置。聊天記錄本身並非產出物。

硬性規則：不得違反

1. 唯讀。 此技能唯一會寫入的檔案是 docs/egm/<slug>/DRIFT-REPORT.md。絕不編輯設計文件、程式碼、測試或其他任何分類帳（IMPLEMENT.md、GOLDFISH.md、ELEPHANT.md）。套用建議的更新是使用者之後提出的獨立請求。
2. 沒有證據就不是偏移。 每個項目都需引用文件中的內容（章節和簡短引言）以及實際建置的內容（path:line、提交記錄，或「沒有此檔案」）。如果某一方缺少證據，則將其列為待解決問題。
3. 程式碼是觀察到的事實；文件是聲明。 中立地報告差異。除非分類帳記錄了決定，否則不要判斷哪一方是對的；建議的更新是提案，而非裁決。
4. 由新的視角進行比較。 執行實作功能的會話傾向於將其自身意圖讀入程式碼中。只要有可能，就將比較工作交給一個全新的唯讀子代理器（步驟 3）。

工作流程

EGM 偏移報告進度：
- [ ] 步驟 1：已解析設計文件和設定 slug；找到 docs/egm/<slug>/
- [ ] 步驟 2：已選擇基準提交；列出證據包路徑
- [ ] 步驟 3：由新的唯讀子代理器（或內聯，請註明）執行比較
- [ ] 步驟 4：檢查、分類並將發現寫入 DRIFT-REPORT.md
- [ ] 步驟 5：告知使用者報告位置，並可要求套用更新

步驟 1：解析設計文件

優先使用使用者提供的參數。否則，在專案 AGENTS.md 或 CLAUDE.md 中 design_doc_path: 指定的資料夾中尋找，再不然則在 docs/designs/*.md 中尋找。如果恰好只有一個文件，則使用它；如果有多個，則列出並詢問使用者。slug 是文件名稱去掉 .md 後的部份，狀態目錄為 docs/egm/<slug>/。如果該目錄不存在，表示該功能從未經過 /egm-design 流程；請告知使用者，並提議仍在那裡撰寫報告（僅建立 docs/egm/<slug>/DRIFT-REPORT.md）。

步驟 2：選擇基準並收集證據包

基準是文件被核准的時間點。選取第一個適用的選項，並記錄你使用的是哪一個：

1. 在 docs/egm/<slug>/GOLDFISH.md 中設定 human_review_gate: passed（或 skipped-solo）的提交：git log --format='%H %ad %s' --date=short -- docs/egm/<slug>/GOLDFISH.md。
2. 在 IMPLEMENT.md 中 start_date 當天或之前，最後一次觸及設計文件的提交：git log --format='%H %ad %s' --date=short -- <doc>。
3. 詢問使用者提供一個提交或日期。

然後，列出比較時將要讀取的證據，但不要進行摘要：

• 設計文件（位於 HEAD，以及如果在基準之後有變更，則也需顯示 git show <base>:<doc>）；
• docs/egm/<slug>/IMPLEMENT.md，特別是 ## Files touched、每個 ## Drift 條目（已開啟和已解決）和 ## Verification；
• GOLDFISH.md 中記錄了文件變更的處置備註；
• git log --stat <base>..HEAD 和 git diff --stat <base>..HEAD，以及來自 git status 和 git diff 的未提交變更；
• 設計文件中「詳細實作」章節列舉的檔案，以及 diff 觸及但文件未列舉的檔案。

不包含在證據包中的項目：本次聊天記錄、ELEPHANT.md 的設計推理，或你自己對為何做某事的回憶。這些僅在分類帳有說明時，才能放入「可能原因」欄位中。

步驟 3：在新的唯讀會話中執行比較

在 Cursor 中，產生一個類型為 drift-auditor 的任務子代理器（安裝於 ~/.cursor/agents/drift-auditor.md，readonly: true）。如果尚未安裝，則使用通用的任務子代理器，並告知其為唯讀模式。將 assets/drift-auditor-prompt.md 中的提示發送給它，並填入文件路徑、slug、基準和證據清單。不要添加任何其他內容：不要對實作進行摘要，也不要解釋變更原因。

如果沒有子代理器執行環境，則直接按照相同的提示內聯執行比較，並在報告標頭中記錄 comparison: inline (no fresh subagent available)，以便讀者知道該比較並非獨立執行。

步驟 4：檢查、分類並撰寫報告

在寫入每個項目之前，先進行檢查：開啟引用的 path:line 和引用的文件章節，並刪除或修正任何證據不支持的內容。使用範本中的類別：changed-approach（方法變更）、added（新增）、not-built（未建置）、renamed-or-moved（重新命名或移動）、interface-change（介面變更）、data-model-change（資料模型變更）、behavior-change（行為變更）、new-dependency（新增依賴）、constraint-discovered（發現限制）、alternative-switched（切換替代方案）。嚴重程度分為 major（文件會誤導讀者理解系統運作方式）、minor（細節錯誤）或 cosmetic（命名或措辭）。

與 IMPLEMENT.md 進行交叉比對：將每個項目標記為 logged（存在偏移條目，並附帶其狀態）或 unlogged。未記錄的主要項目是報告的重點。

從 assets/drift-report-template.md 撰寫 docs/egm/<slug>/DRIFT-REPORT.md。如果檔案已存在，則將新的帶日期報告放在檔案標頭下方，並將先前的報告保持不變地移至 ## Earlier reports 下方。絕不重寫先前的報告。

如果沒有發現偏移，仍然撰寫報告，內容包含 drift_items: 0、使用的基準以及比較的內容，使「無偏移」成為一個有記錄的結果，而非空白。

步驟 5：交回給使用者

以以下格式告知使用者：

偏移報告已寫入 docs/egm/<slug>/DRIFT-REPORT.md： 個項目（ 個主要問題， 個未記錄於 IMPLEMENT.md）。我尚未修改設計文件或程式碼。當您希望文件符合實際建置的內容時，請要求我根據報告套用建議的文件更新；需要變更技術計劃的項目應回到 /egm-design 流程，大量改寫則應透過 /egm-review。

除非使用者在看到報告後提出要求，否則請勿在此會話中套用更新。

反模式

• 在報告撰寫的同時修正文件。 報告是交付成果。編輯文件會將測量與變更混為一談，並掩蓋偏移的實際情況。
• 修正程式碼以符合文件。 同樣的問題，方向相反。由使用者決定哪一方需要調整。
• 根據記憶解釋偏移。 「我們因為 X 而改變了這個」如果沒有分類帳記錄，就是猜測；請寫 reason: unknown，讓使用者自行填寫。
• 摘要 diff 而非進行比較。 已變更檔案的清單不是偏移報告。每個項目都需將一個文件聲明與一個觀察到的事實連結起來。
• 為了節省時間而跳過新的會話。 執行實作的會話已經相信程式碼與文件相符。這個信念正是此技能存在的理由來加以檢驗。

此技能在 EGM 中的位置

/egm-learn（僅限舊有程式碼）→ /egm-design → /egm-review → /egm-implement → /egm-code-review，而 /egm-drift-report 可在 /egm-implement 之後的任何時間使用（程式碼審查之前或之後）。

• 讀取： 設計文件、IMPLEMENT.md、GOLDFISH.md、基準之後的 git 歷史記錄，以及程式碼。
• 寫入： 僅 docs/egm/<slug>/DRIFT-REPORT.md。
• 輸出給： 後續的「根據偏移報告更新設計文件」請求、用於技術計劃變更的 /egm-design、以及當更新後的文件需要重新驗證時的 /egm-review。