コーパウンド（Compound）は何をしますか？

最近解決した問題やリリースした機能をドキュメント化して、プロジェクトの知識を蓄積します。文書化された各解決策は、将来の計画立案や実装を迅速にします。エージェントは /research と /write-a-prd の実行中に docs/solutions/ を参照するため、今日学んだ教訓が明日の失敗を防ぎます。

作業中に計画や見積もりに驚きがあった場合、それらも記録してください。McConnell スタイルのキャリブレーションは、実際の作業が将来の見積もりにフィードバックされる場合にのみ機能します。

呼び出し位置

これはプライマリーパイプラインスキルであり、知識の蓄積ループを閉じます。デフォルトの配信パスの末尾付近で、/pre-merge が PR を作成した後に実行されます。

デフォルト — マージ前に PR に教訓をキャプチャする。 耐久性のある教訓が PR 作成時点ですでにわかっている場合、オープンな PR ブランチで /compound を実行し、docs/solutions/ のエントリが、その教訓をもたらしたコードと同じ PR に乗ってレビューされ、アトミックにマージされるようにします。これにより /compound は /pre-merge と /closeout の間に配置され、一度 /pre-merge を経由して戻ります。

… → /pre-merge → /compound（教訓が存在する場合、PR内で実行） → /pre-merge（再実行：コーパウンドコミットがポストスタンプの差分となるため、再スタンプ） → /closeout（マージ＋後処理） → クリーンアップ

戻りの区間は飾りではありません。ブランチにコミットすると、/pre-merge のフェーズ4 が書き込んだスタンプをヘッドが追い越すため、再実行なしではエントリはコードと一緒にマージされますが誰にも読まれません——これは、インPRデフォルトが避けるために選んだ唯一の事態です。フェーズ5はその引き継ぎを明示しています。これが存在する理由です。

フォールバック — マージ後にキャプチャする。 統合時の驚き、QAの発見、リリース後に初めて確認された動作など、マージ中またはマージ後にしか明らかにならない教訓もあります。そのような場合は、/closeout がマージを実行した後で /compound を実行します。これがフォールバックパスであり、デフォルトではありません。

どちらの場合も、/compound がマージやワークツリーの後処理を実行することはありません。それは /closeout の役割です。また、レビュー通貨スタンプを書き込むこともありません。これは /pre-merge だけの役割です。PR内でキャプチャするとは、オープンな PR ブランチにコミットし、それをカバーするレビューのために引き継ぐことを意味します。マージすることではありません。

単純な編集や、テストやリンタールール、コードコメントなどの高忠実度の成果物で表現できる教訓には使用しないでください。「使用すべきでない場合」のガードは、インPRとポストマージの両方で適用されます。ほとんどのPRは耐久性のある教訓を持たず、すべてのPRに docs/solutions/ エントリを入れる習慣はありません。

なぜこれが存在するのか

このステップがなければ、AI支援による従来のエンジニアリングと変わりません。ワークフローの最初の3ステップ（計画、作業、レビュー）は機能を生み出します。この4番目のステップは、機能を毎回より良く構築するシステムを生み出します。

使用すべき場合

機能のPRが準備でき、耐久性のある教訓があった場合——マージ前にPRにキャプチャする（ハッピーパス）
リリース後、マージ中またはマージ後にのみ教訓が明らかになった場合（ポストマージフォールバック）
トリッキーなバグを修正し、根本原因が自明でなかった場合
QAサイクルで、もっと早く発見できたはずの問題が明らかになった場合
重要なトレードオフを伴うアーキテクチャ上の決定を行った場合
再利用すべきパターンを発見した場合

使用すべきでない場合

些細な修正の場合（タイポ修正、簡単な設定変更）
解決策が公式ライブラリのドキュメントで十分に文書化されている場合
教訓がプロジェクト固有だが、そのコードを間もなく非推奨にする場合
事前に形作られた計画をそのまま実行した場合（驚き、手直し、非自明な判断なし）。Issueの本文とPRの説明がその記録をすでに保持しています。再利用可能な教訓のない docs/solutions/ エントリは、将来の読者にスキミングを強いることになります
迷った場合 — IssueとPRはGitHubに残るため、スキップしてもコストはかかりません。低価値の教訓をキャプチャすると、将来の計画立案者が docs/solutions/ を参照するたびに注意を奪われます

実行フロー

フェーズ1：キャプチャする内容を特定する

インPRデフォルトパスでは、レビュー対象の作業はオープンなPRブランチです。そのため、以下のコマンドはそれを直接読み取ります——マージ前のブランチとベースとなるブランチとの git log と git diff です。ポストマージフォールバックパスでは、マージされた機能の履歴をまだ参照できるセッションで実行します。——/closeout がブランチを削除しベースをプルした後では、その差分は空になり、代わりに gh pr diff <n> を使用してPRの差分を読む必要があります。いずれの場合も、最近の作業をレビューします。

まずベースを解決します。main をハードコードしないでください——このリポジトリ自体が prod を使用しており、名前は参照ではありません。ワークツリーワークフローでは誰もベースブランチをチェックアウトしないため、ローカルブランチはチェックアウト時の状態で固定され、origin/<base> は進み続けます。sidecar.sh base-ref を使用してください。ベースを推測しないでください。

SC="<このスキルのディレクトリ>/references/sidecar.sh"
BASE_REF="$(bash "$SC" base-ref)" || { echo "base-ref 失敗: ベースを推測しません" >&2; exit 1; }
git log --oneline "$BASE_REF..HEAD"
git diff --stat "$BASE_REF...HEAD"

確認する項目：

Gitログ — どのコミットが行われましたか？何が変更されましたか？ベース相対で確認します。-20 ではありません：固定数は、それより短いブランチではベース自身の履歴を「レビュー対象の作業」として読み取ってしまいます。ここでの2ドットは正しい——これらはこのブランチにありベースにはないコミットです（git diff が3ドットなのはその逆の理由で、ベース側の作業を差し引くのではなくマージベースからの差分を取ります）。ポストマージフォールバックパスではブランチが存在しないため、代わりに gh pr diff <n> を使用します。
Issueスレッド — 元の問題は何でしたか？何が議論されましたか？
差分 — どのファイルが変更されましたか？どのようなパターンが現れましたか？

ユーザーに尋ねます：「この機能で最も重要な学びや最もトリッキーだった部分は何ですか？」彼らの回答が、キャプチャすべき最も価値の高い教訓を明らかにすることがよくあります。

書き始める前に、教訓を適切なレベルで分類します：

イベント — 一度限りのインシデントまたは目に見える障害
パターン — 機能、バグ、引き継ぎなどで繰り返し発生したこと
構造 — コードベース、ワークフロー、インセンティブ、意思決定プロセスにおいてパターンを生み出し続ける反復条件

裏付けとなる証拠に基づいてサポートできる最上位のレベルを優先します。教訓が構造的なものである場合、その結果を生み出したフィードバックループ、欠如しているフィードバック、または遅延効果に名前を付けます。

次に進む前に、4つの質問に答えます：

これは本当に新しいものですか？ 公式ライブラリのドキュメントと、フェーズ4の重複検索がカバーするストアを確認します。教訓がすでに他の場所で十分に文書化されている場合は、スキップするか、既存のソースにリンクします。
これは3ヶ月後も正確ですか？ 教訓が依存関係のバージョンや一時的な回避策に強く結びついている場合は、そのことをメモします——これは以下の volatility 分類に影響します。
これはソースに近い場所でキャプチャできますか？ 振る舞いの不変条件はテストとして表現する方が良いです。規約はリンタールールとして表現する方が良いです。「なぜ」の説明は、コードコメントとして決定と共に配置する方が良いです——現在の「なぜ」、つまり読者が現在のコードを理解するために必要な理由に限定されます。その発見に至ったインシデントはコミットメッセージとPR本文に属します。歴史を再構築する読者はそこを探します。/execute のステップ3は、コメントが書かれた時点でのルーティングを述べており、この質問はその遡及的なチェックです。教訓がより高忠実度の成果物でキャプチャできる場合、散文を書く代わりにそうします。これは教訓を伝えることに関するものです——フェーズ4のクラスタリングチェックは、メカニズムが次のインスタンスをキャッチすべきかという異なる質問をしており、たとえ教訓自体が散文を必要としたとしても、再発にはメカニズムが必要になる可能性があります。
プロセスは修正されましたか？（バグ修正のコーパウンドのみ）修正は是正（欠陥を除去）でしたか、それとも回避策（障害を抑制）でしたか？コードベースの他の場所で構造的に類似したパターンが見つかり、対処されましたか？この欠陥クラスがコードベースに再び入り込むのを防ぐプロセス変更は何ですか——より強力なテスト、リンタールール、アサーション、計画チェックリスト項目、または chrislacey89/skills に提出されたIssue（以下の パックに対する報告 を参照）？答えが「何もない」場合、この欠陥を生み出したメカニズムはまだアクティブです。

パックに対する報告 — 5番目のメカニズム

このサブセクションはバグ修正に限定されません。 上記Q4は（見出しがそう述べています）バグ修正に限定されていますが、Q4とフェーズ4の「メカニズムへの昇格」ルールの両方が以下のルールを参照しており、フェーズ4はバグ修正に限定されていません。このメカニズムが存在するきっかけとなったインシデントは機能のコーパウンドでした。自身のインシデントが取らなかったパスからのみ到達可能な手順は、一段階下の修正中の欠陥そのものです。そのため、ルールはここで一度宣言され、両方のフェーズがそれを参照します。

5番目の名前は、難易度ではなく所有権によって範囲が決まります。 最初の4つはこのコードベースの成果物です。5番目が存在するのは、いくつかの予防的変更がそうではないからです——それらは chrislacey89/skills 内のスキルの散文、ゲート、引き継ぎ、または契約テストへの変更であり、下流の成果物はまったく伝達できません。それだけが5番目の名前が適格となる場合です。最初の4つが難しい、高コスト、またはここでは不明確だからといって適格になるわけではありません。それが chrislacey89/skills#257 が意図的に未解決のままにしたコンプライアンス出口であり、「作れなかった」という結論は、エントリ内で4つのうちどれが最も近く、何がそれを妨げたかを名前を挙げることで、これまで通り解決されます。

報告者ゲート（DO-CONFIRM — 何かを外部に書き出す前に確認）

報告とは、現在いるリポジトリからパブリックなリポジトリに言葉を移動することです。 これはリスト内の他のすべてのメカニズムとは異なる行為です。テスト、リンタールール、アサーション、チェックリスト項目はすべてそのまま残ります。そのため、ボディを作成する前に、現在のリポジトリの所有者が報告を許可されているか確認します。

git remote get-url origin | sed -E 's#(git@[^:]+:|https://[^/]+/)([^/]+)/.*#\2#'

それを以下の許可リストと比較します。許可リストがゲート全体です——リストにない所有者は許可されません。認識できない所有者も含みます。 これを「知っている作業の所有者をブロックする」という拒否リストに反転しないでください。先週オンボーディングされたクライアント組織はまだ誰のリストにも載っていません。そのため、拒否リストは最も機密性の低いリポジトリを許可することになります。不明な場合は失敗に閉じてください。

chrislacey89

そのフェンスの周りのマーカーは重要です。このサブセクションには複数のフェンスブロックが含まれているため、「リストは以下のコードブロックです」は機械的に読み取るものにとってあいまいです。間違って推測した読み手は散文を抽出し、すべての所有者がチェックに失敗することになります。位置ではなくマーカーを一致させてください。

所有者をそのリストに追加するのは、意図的でレビューされた編集としてのみ行います——1行、オフライン、grep可能です。あなたがコントリビュートするパブリックリポジトリは、名前を付ければ適格になります。単にパブリックであるというだけでは適格になりません。可視性は可変のリモートプロパティであり、パブリックフォークはプライベートな親を隠すことができ、そして——ここで重要な理由は——報告されるのは作業に関するナラティブであり、リポジトリのコードではありません。パブリックソースとそれを取り巻く機密性の高いエンゲージメントは一般的な組み合わせであり、「Xを構築中にYでこれに遭遇した」という表現は、すべての行が誰でも読める場合でも関係性を漏洩させます。

所有者が許可リストにない場合、5番目の名前は利用できません。 このメカニズム以前の動作にフォールバックします。エントリの「予防 → プロセスレベル」スロットに処方箋を記録し、/improve-pipeline を推奨し、人間がそれを伝達するのを待ちます。教訓は失われません。自動的に伝達されないだけです。

作成と報告

所有権ガードと報告者ゲートの両方を通過した場合、報告がメカニズムとなり、/compound がそれを行います——このリポジトリに届く処方箋は成果物であり、誰かにそれを伝えるよう推奨する文ではありません。まず重複を確認し、新しいIssueを作成するのではなく、既存のIssueにコメントします。バックログへの新しい外部チャネルは、再表明で埋まらない場合にのみ価値があります。

gh issue list -R chrislacey89/skills --state all --search "<パイプライン領域> <障害モードキーワード>"
gh issue create -R chrislacey89/skills --title "[improve-pipeline] <パイプライン領域> — <処方箋>" --body-file <ファイル>

--title と --body* は必須であり、スタイルではありません。gh issue create にこれらのオプションがない場合、非インタラクティブランナーではエラーで終了します。これは、このメカニズムが耐えることを意図しているすべてのAFKパスに当てはまります。

本文は匿名化して記述し、それをマナーではなく契約の一部として扱います。 上記のゲートは報告してもよいかを決定します。これは何を越えるかを決定します。インシデントの対象ではなく形状を説明します：

名前を付ける：変更対象のパックファイル、それを見逃したパイプラインステップ、そして代わりに何をすべきだったか。
名前を付けない：下流リポジトリ、その所有者、そのクライアント、そのパス、その識別子、そのIssue番号やPR番号。特徴づけます——「下流のTypeScript Web/ページ分析リポジトリ」——chrislacey89/skills#266 が行った方法で、これが実例です：それは Triggering repo: anonymized を開き、ソースが意図的に識別子を削除されたことを記録しています。
このエントリのパスを証拠として引用しないでください。 docs/solutions/… パスは、読者がアクセスできない可能性のあるリポジトリからのファイル名であり、読者には何も証明せず、他の全員に作業を特定させます。代わりに、推論を伝えてください。エントリは元の場所に残ります。

パックファイルと障害形状が、ここで提案を実行可能にするものです。匿名化ルールが削除するものはすべて、それが元々来たリポジトリでのみ読める詳細です。

短く保ちます。これは提案のスタブであり、完成された提案ではありません。/improve-pipeline がそれを発展させるものであり、このフェーズの後半にある /improve-pipeline の推奨は依然として有効です。推奨しますが、呼び出しません。エントリ内でIssue番号を引用します。 引用されていない報告は、再び散文になります。エントリは #N を名前として挙げるか、5番目の名前が使用されなかったことを示します。

Rabbit Hole レビュー。

…

[翻訳のため省略]

コーパウンド（Compound）