fix-pr

/fix-pr は、プルリクエストで意図されたワークフローの結果を復元します。最も早い因果的な失敗を特定し、その原因を分類して、長期的に有効な最小限の修正を適用し、修正後のコミットですべての必須チェックを検証します。

ローカル作業と永続的な記録

ファイルシステムプロトコルと python3 <skill-dir>/scripts/p2p_filesystem.py --repo <root> resolve .p2p/work/<slug>/contract.md を使用してパスを解決します。置き換え前に履歴を保持するには、 save .p2p/work/<slug>/contract.md <report-name> --from <file> を使ってレポートを保存します。

正規の .p2p/work/<slug>/contract.md が適用される場合は、保存済みの候補とレポートを .p2p/work/<slug>/ から確認します。診断、修正結果、安全性を確認した証拠、および正確な変更前後の候補識別情報を .p2p/work/<slug>/ci-repair.md に保存し、プロトコルの 保持ルールに従って以前の記録を維持します。使い捨てのログは .p2p/tmp/ に置き、引き継ぎを行う前に必要な証拠を保持します。シークレットはマスキングし、Git に含めるのに適さない証拠には プロトコルの永続参照とチェックサムの記録を使用します。ローカルでレポートを保存しただけでは、Git への権限は付与されません。以下に示す明示的な /fix-pr の呼び出し権限は、これとは別のものです。候補を変更した場合は、新たなレビューと証明が必要です。過去の判定を書き換えてはいけません。

呼び出し

リポジトリの対象を1つ指定します。

• /fix-pr #123
• /fix-pr https://github.com/acme/project/pull/123
• /fix-pr <workflow-run-url>

対象から可能な場合は、プルリクエストまたはワークフロー実行に関連するワークフローを推定します。

ガードレール

編集する前に、ブランチとワークツリーを確認します。現在のブランチとコミットが対象の PR ヘッドまたはワークフローのコミットを特定しており、ワークツリーに無関係な変更がない場合に限り、続行します。対象を特定できない場合、認証情報または権限が利用できない場合、あるいはブランチの状態から修正内容を明確に判断できない場合は、NOT FIXED で停止します。

対象を絞った修正のみをコミットし、対象の PR ヘッドブランチにのみプッシュし、強制プッシュは決して行いません。

診断と検証は、対象の正確なコミット SHA に紐付けます。修正中に PR が変更された場合は、黙って新しいコミットを追うのではなく、停止して対象を再確定します。

フォークからの PR、またはそれ以外の信頼できない PR については、シークレットの公開、特権付きワークフロー実行の承認、権限の拡大、分離の弱体化を行いません。必須の検証に利用できる安全な実行経路がない場合は、NOT FIXED で停止します。

失敗が発生した検証の境界を維持します。

• 必須のジョブ、テスト、アサーション、リンティング／型チェック、カバレッジしきい値、CI マトリックスの項目、失敗条件をすべて維持します。誤りのあるチェックまたは古くなったチェックを置き換える場合は、「禁止される修正」に定める証拠ルールに従います。
• ワークフローのみを修正する場合も、同じ失敗条件で同じ品質チェックが実行されるようにします。
• リポジトリに適切な接点がある場合、製品またはテストの欠陥には、対象を絞った回帰テストを追加または強化します。実装の計算をコピーするのではなく、独立した動作アサーションを使用します。
• 修正は失敗の範囲に限定します。再実行は証拠であり、修正ではありません。

ワークフロー

1. 意図された操作を確定する

失敗したワークフローが、マージ前に PR ブランチを検証することや、特定のコミットで必須チェックを実行することなど、何を保証する想定だったのかを判断します。その保証に基づいて成功を定義します。

修正対象の動作が受け入れ条件プロトコル およびリンク先のチケットと受け入れ条件によって定義されている場合は、それらを読みます。リビジョン、要件 ID、約束された結果、境界、合意済みの接点、独立したオラクルを維持します。その契約が利用できない、または曖昧な場合は、不足している要件を推測しなくても正しさが成り立つ修正に限り、続行します。 不足点を報告します。CI の失敗は、チケットの約束を変更する根拠にはなりません。

2. 編集前に診断する

ワークフローの実行、失敗したジョブとステップ、ログ、ワークフロー YAML、関連する変更、および対象 PR のブランチ保護またはルールセットで必須とされているチェックを確認します。 最初に、最も早い時点で発生した根本原因となる失敗を調べ、次に並行ジョブで独立して発生している失敗を確認します。ワークフロー、ジョブ、ステップ、コマンド、および確認されたエラーを記録します。

単位時間あたりに得られる証拠、コンテキストのコスト、計算コストを考慮し、ローカルでの再現、GitHub Actions の実行をプッシュしての確認、またはその両方を選びます。原因を素早く切り分けられる場合はローカルチェックを使います。環境固有の問題である場合や、ローカルでの再現にコストがかかる場合は、信頼性の高いリモートワークフローを優先します。既存のアーティファクトや対象を絞った静的検査で疑問が解消できる場合はそれらを使い、同等の実行を重複させないでください。

変更を加える前に、主な原因を分類します。

• PRODUCT：ブランチのコード、テスト対象、または生成された出力が誤っています。
• WORKFLOW：GitHub Actions の設定、権限、またはジョブの接続が誤っています。
• EXTERNAL：依存関係、ランナー、認証情報、またはサービスが利用できません。

EXTERNAL の場合、利用できない機能を補うためにプロダクトコードやワークフローコードを変更してはいけません。外部の問題を解決するのは、その対応が許可されており、独立して検証可能な場合に限ります。それ以外の場合は NOT FIXED を返します。

不安定さは、確信度を左右する要素として扱います。関連する変更を加えずに再実行した場合は、非決定性の原因が分かるまで NOT FIXED — WORKFLOW GREEN — FLAKE NOT RESOLVED で終了します。

3. 修正して検証する

失敗を引き起こした箇所を所有するレイヤーで、完全な修正を最小限の範囲で適用します。Forbidden repairs の証拠ルールに従い、必須チェックとその失敗時の動作を維持してください。プロダクトやテストの不具合については、成功を宣言する前に、対象を絞ったリグレッションの証拠を追加または強化します。

プロダクトやテストの修正を、影響を受ける要件と観測可能な結果に対応付けます。代替となる証拠と、それが同じ約束を引き続き検証できる理由を記録します。この CI 修正を完全な実装や検証に拡大せず、無関係な受け入れ上の不足は明示したままにします。

ローカルかリモートかを問わず、最も安価で高いシグナルを得られる検証から実行します。より効率よく証拠を得られる場合は、信頼性の高い GitHub ワークフローを主な検証として使います。ローカルでより広範なチェックを実行するのは、それによって得られる追加の証拠がコストに見合う場合に限ります。 元の失敗したジョブだけでなく、対象 PR のブランチ保護またはルールセットで報告されている必須チェックをすべて検証します。ワークフロー実行を対象とする場合、関連する PR があればそれを使います。関連する PR がない場合は、実行に含まれるすべてのチェックを検証し、ブランチ保護の要件を確認できなかったことを明記します。 必須チェックは、修正後の正確な SHA に対して成功した場合に限り、検証済みとして数えます。保留中、キュー待ち、キャンセル済み、タイムアウト、スキップ、未実行、または古い結果は、検証の成功ではありません。環境に待機手段がある場合はそれを使います。ポーリング間隔、待機時間の上限、修正試行回数の上限を独自に設定してはいけません。 待機手段がない場合は、実行 URL とともに NOT FIXED — VERIFICATION PENDING を返します。原因が不明確な場合、必須機能が利用できない場合、修正によって品質が低下する場合、または修正によって説明のつかない品質低下が生じた場合は、作業を中止します。修正済みコミットがプッシュされており、必須のシグナルがすべて引き続き測定可能であることを確認します。

禁止される修正

必須の品質シグナルを測定可能な状態に保ちます。テストの削除やスキップ、lint ルールの無効化、カバレッジの引き下げ、チェックの任意化、失敗の握りつぶし、無条件の continue-on-error の追加、根拠のない再試行、またはワークフローステップのコメントアウトをしてはいけません。チェックを変更できるのは、元の契約と証拠によって、そのチェックが誤っている、または古くなっていると証明される場合に限ります。置き換え後は、同じ約束に対して、より強く妥当な証拠を提供する必要があります。その理由と影響を受ける要件 ID を記録します。チェックの変更は、約束自体を変更する根拠にはなりません。

ワークフローを再設計したり、無関係なコードを整理したり、解決されていない失敗をグリーンの再実行で覆い隠したりしてはいけません。

完了

次のいずれかの結果を返してください。

• FIXED：原因が特定され、恒久的な修正と対象を絞った検証に合格し、必須の品質シグナルが維持または強化され、修正コミットがプッシュされ、対象に必要なすべてのチェックが成功している。
• NOT FIXED：失敗が未解決である、必須の機能を利用できない、ワークツリーが安全でない、修正によって品質が損なわれる、または原因不明の再実行で成功しただけである。

FIXED はワークフローが修復されたことを意味します。チケットのすべての要件が 証明済み であることを意味するものではありません。

いずれの結果の場合も、意図した操作、失敗の分類、最初に発生した原因エラー、変更したファイル、実施した検証、必須チェックの状況、および NOT FIXED の場合は未解決の理由を報告してください。修正後の SHA、影響を受ける要件 ID、置き換えられたエビデンス、および未解消の受け入れギャップを含めてください。契約のリビジョンが保存されている場合は記録してください。候補に変更が加わると、以前の証明は古い候補に紐付いたままになります。製品の動作、受け入れエビデンス、または関連するテストに変更がある場合、受け入れ前にすべての要件について新たに /prove を実行する必要があります。CI の成功によって証明を更新することはできません。古くなった証明とレビュー結果を特定し、それらの手順が依頼されている、または必要な場合は、/prove とリポジトリのレビュー手順に引き継いでください。

/fix-pr の呼び出しは、対象の PR またはワークフロー実行について、範囲を限定した調査、編集、コミット、プッシュ、およびワークフローの再実行を許可します。強制プッシュ、対象ブランチ外への変更、または検証を弱める回避策は許可されません。

最後に Next steps: と、該当するアクションを順番に並べた番号付きリスト（1.、2.、...）を記載し、各項目を番号で参照できるようにしてください。FIXED の場合は、該当する呼び出しを使って古くなったレポートを更新してください。両方が一致する場合は、保存済みレポートの参照情報とともに /merge-readiness <PR URL> を提示してください。

/prove <saved contract>; candidate <repaired SHA>
/review-implementation <repaired candidate> against <comparison base>

NOT FIXED の場合は、ワークフローに記載されている失敗したチェックの正確なコマンドと、観測された失敗内容を提示するか、不足している具体的な入力または人による判断を明記してください。受け入れやマージの権限があると主張しないでください。