jhincapie/egm-cursor

EGM ドリフトレポート：設計書が言っていたことと、実際に構築されたもの

/egm-implement は設計書からコードを構築し、発生したドリフトを IMPLEMENT.md に記録します。しかし、それでもドリフトはすり抜けます。セッションが小さすぎると判断した変更、後からの修正、実際の呼び出し元が現れてから落ち着いたインターフェースなどです。このスキルは事後的にギャップを測定し、文書化します。これにより、ユーザーは後で「設計書を合わせて更新して」と言え、設計書が再び信頼できる情報源となります。

呼び出し方法: /egm-drift-report [path-to-design-doc]

EGM 操作上の反射（共有プリアンブル）

このスイートのすべてのスキルは、以下の4つの反射を持ちます。すべてのサーフェスがグローバルな CLAUDE.md を読み込むとは限らないためです。これらは Elephant-Goldfish の記事に由来し、このスキルの実行中だけでなく、セッション全体に適用されます。

1. 設計が新しいコードである。 どんな重要な機能や変更に対しても、コードを書く前に設計書を作成します。設計がコードを自動的に導き出すほど明確でない場合は、まず設計を行います（/egm-design）。
2. 追従を拒否する。 あなたの仕事はユーザーの思考に挑戦することです。同意だけではユーザーの助けになりません。「良い指摘です」や「まったくおっしゃる通りです」と言いかけそうになったら、立ち止まって代わりに何が間違っているかを探してください。ユーザーが「あなたは役に立っていません」（EGM リセット）と言った場合、それはあなたが同意しすぎているサインとして受け止め、穴を見つけることに戻ってください。
3. AI が先に提案する。 ユーザーに設計、フレームワーク、またはルーブリックの最初の草案を決して任せないでください。あなたが先に、散文とブロック図で提案し、ユーザーはそれに反応し、議論します。
4. アーティファクトを保存する。 説明、基準、出力の3つ組を永続的に保存します：docs/designs/<slug>.md、docs/egm/<slug>/ 内の台帳、ソースルートの PEANUTS.md、そしてそのスキルがインストールされているサーフェスにマッピングされた場所にある /egm-decide の3つ組。チャットのトランスクリプトはアーティファクトではありません。

絶対ルール：これらは破らないこと

1. 読み取り専用。 このスキルが書き込む唯一のファイルは docs/egm/<slug>/DRIFT-REPORT.md です。設計書、コード、テスト、またはその他の台帳（IMPLEMENT.md、GOLDFISH.md、ELEPHANT.md）を決して編集しないでください。提案された更新を適用することは、ユーザーが後で行う別のリクエストです。
2. 証拠がなければドリフトではない。 各項目は、設計書が何を言っているか（セクションと短い引用）と、実際に構築されたもの（path:line、またはコミット、または「該当ファイルなし」）を引用します。両方の側に証拠がない項目は未解決の質問であり、そのようにリストされます。
3. コードが観測された事実であり、設計書が主張である。 差異を中立に報告してください。台帳が決定を記録している場合を除き、どちらが正しいかを判断しないでください。提案される更新は提案であり、判決ではありません。
4. 新鮮な目で比較を行う。 機能を実装したセッションは、自分の意図をコードに読み込むバイアスがかかっています。可能な場合は常に、比較を新鮮な読み取り専用サブエージェント（ステップ3）に任せてください。

ワークフロー

EGM ドリフトレポートの進捗:
- [ ] ステップ1: 設計書とスラッグが解決されました。docs/egm/<slug>/ が見つかりました
- [ ] ステップ2: ベースラインコミットが選択されました。証拠パックのパスがリストされました
- [ ] ステップ3: 新鮮な読み取り専用サブエージェント（またはインライン、注記）によって比較が実行されました
- [ ] ステップ4: 発見事項がチェック、分類され、DRIFT-REPORT.md に書き込まれました
- [ ] ステップ5: ユーザーにレポートの場所と、更新を適用するよう依頼できることが伝えられました

ステップ1: 設計書を解決する

ユーザーの引数を優先します。それ以外の場合は、プロジェクトの AGENTS.md または CLAUDE.md で design_doc_path: によって指定されたフォルダを探し、それ以外は docs/designs/*.md を探します。ドキュメントが1つだけ存在する場合はそれを使用し、複数ある場合はリストしてどれかを尋ねます。スラッグは .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 の Task サブエージェントを1つ起動します（~/.cursor/agents/drift-auditor.md にインストール、readonly: true）。インストールされていない場合は、汎用の Task サブエージェントを使用し、読み取り専用であることを伝えてください。プロンプト assets/drift-auditor-prompt.md を、ドキュメントパス、スラッグ、ベースライン、証拠リストを埋めて送信します。これ以上何も追加しないでください：実装の要約や、なぜ変更されたかの説明は不要です。

サブエージェントのランタイムが存在しない場合は、同じプロンプトに従って自分で比較をインラインで実行し、レポートヘッダーに 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 としてマークします。ログに記録されていない major 項目がハイライトです。

docs/egm/<slug>/DRIFT-REPORT.md を assets/drift-report-template.md から書き込みます。ファイルが既に存在する場合は、新しい日付入りレポートをファイルヘッダーの下の先頭に配置し、以前のレポートは変更せずに ## Earlier reports の下に移動します。以前のレポートを決して書き換えないでください。

ドリフトがない場合でも、drift_items: 0、使用されたベースライン、比較された内容を含めてレポートを書き込み、「ドリフトなし」が欠如ではなく記録された結果となるようにします。

ステップ5: ユーザーに結果を返す

次の形式でユーザーに伝えます。

ドリフトレポートは docs/egm/<slug>/DRIFT-REPORT.md に書き込まれました： 項目（ 件の major、 件は IMPLEMENT.md にログなし）。設計書やコードは変更していません。設計書を構築されたものに合わせたい場合は、レポートから提案されたドキュメント更新の適用を依頼してください。Technical Plan を変更する項目は /egm-design に戻し、大規模な書き換えは /egm-review に戻す必要があります。

ユーザーがレポートを見た後に依頼しない限り、このセッションで更新を適用しないでください。

アンチパターン

• 報告中にドキュメントを修正する。 レポートが成果物です。ドキュメントを編集すると、測定と変更が混ざり、ドリフトが何であったかが隠れてしまいます。
• ドキュメントに合わせてコードを修正する。 逆方向でも同じ問題です。どちらの側を動かすかはユーザーが決定します。
• 記憶からドリフトを説明する。 台帳の行がない「X だからこれを変えた」は推測です。reason: unknown と書き、ユーザーに記入させてください。
• 比較せずに diff を要約する。 変更されたファイルのリストはドリフトレポートではありません。各項目は、1つの設計書の主張を1つの観測された事実に結び付けます。
• 時間を節約するために新鮮なセッションをスキップする。 実装セッションは、すでにコードが設計書と一致していると信じています。このスキルが存在するのは、その信念をテストするためです。

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 のみ。
• フィード先： 後続の「ドリフトレポートから設計書を更新する」リクエスト、Technical Plan 変更のための /egm-design、更新された設計書の再検証が必要な場合の /egm-review。