reproduce-and-fix-issues

問題の再現と修正

ソーススレッドに信頼できるトリアージマーカーが付くまで待ちます。対象アプリの実際の UI を通じて、症状を正確に再現します。既存の修正がある場合は、それを検証します。再現を確認してから、範囲を限定して修正を試みます。

自動化によって提供された外部の Benny 設定を読み込みます。設定、必須アクション、コントロールアダプター、または完了済みの機能マップが欠けている場合は、安全側に倒して処理を中止します。

安全上の厳守事項

• 作業を始める前に、ソースチャンネルとルートスレッドの座標を固定します。
• ソースチャンネルにルートメッセージを投稿してはいけません。
• ソーススレッドに投稿する前に、必ずソースの親メッセージを事前確認します。
• Slack への投稿を行えるのはコーディネーターのみです。
• 委任された分析ワーカーは読み取り専用とし、調査結果またはメディアに関するメモを返します。
• 修正フェーズのコードワーカーが編集できるのは、その実行環境で Slack 認証情報とすべての Slack 書き込みアクションが確実に除外されている場合に限ります。それ以外の場合は、コーディネーターが編集します。
• すべての子プロンプトで、SendSlackMessage、PostToSlack、chat.postMessage、その他すべての Slack 書き込みを明示的に禁止します。
• 子に Slack トークン、投稿手順、投稿用のソース座標、または外部に報告する許可を与えてはいけません。
• Slack への書き込みアクセスが必要な子は起動してはいけません。
• ユーティリティボットは証拠の情報源です。担当者が明示的に修正を委任しない限り、修正の責任を負いません。
• 識別に使う正確な症状を、実際の UI 操作を通じて 2 回確認します。
• 状態の確認は観察内容の裏付けとして使用できます。症状を注入したり強制したりしてはいけません。
• 再現が確認できなければ、修正を作成してはいけません。
• 既存のプルリクエストまたはコミットがある場合は、実行を検証モードに切り替えます。それらに重ねて修正を作成してはいけません。
• github.com のプルリクエストリンクを使用します。
• キャプチャ、録画、ログ、トークンをソース管理に含めてはいけません。
• 委任された分析には、pstack の principle-guard-the-context-window を使用します。
• 再現、修正、検証を通じて、pstack の principle-sequence-verifiable-units、principle-fix-root-causes、principle-prove-it-works を適用します。

1. ソースの座標を固定する

作業リストを作成したり、作業を委任したりする前に、次の手順を行います。

1. トリガーチャンネルが設定済みのソースチャンネルと一致することを確認します。
2. trigger.thread_ts が存在する場合は SOURCE_THREAD_TS に設定します。存在しない場合は trigger.ts を使用します。
3. SOURCE_THREAD_TS が空でないことを確認します。
4. SOURCE_CHANNEL_ID と SOURCE_THREAD_TS を変更不可の値として保存します。
5. ソーススレッドを読み込み、ルートがそれらの座標と完全に一致することを確認します。
6. ソースのパーマリンクを取得します。

これらの値を返信のタイムスタンプ、運用上のタイムスタンプ、またはステータスメッセージのタイムスタンプに置き換えてはいけません。

ソースチャンネルに投稿する前に、必ず次の手順を行います。

1. 変更不可の座標を使ってスレッドを読み込みます。
2. 親メッセージが存在し、削除されておらず、引き続きソースチャンネルに属していることを確認します。
3. channel=SOURCE_CHANNEL_ID と thread_ts=SOURCE_THREAD_TS のみを指定して送信します。
4. スレッドを再度読み込み、新しいメッセージが返信であることを確認します。

いずれかの確認に失敗した場合は、何も投稿しません。ルートまたはフォールバックチャンネルに再試行してはいけません。

2. トリアージの条件が満たされるまで待つ

設定された判定時間の間、ソーススレッドを監視します。待機中は何も投稿しません。

次の条件をすべて満たす場合のみ、判定結果を受け入れます。

• 投稿者が slack.triage_identity_user_id と一致する。
• SOURCE_THREAD_TS の下の返信である。
• 設定済みのマーカーがちょうど 1 つ含まれている。

公開マーカーの形式：

[benny:bug]
[benny:bug] tracker=https://tracker.example/issue/123
[benny:performance]
[benny:performance] tracker=https://tracker.example/issue/123
[benny:other]

bug または performance の場合のみ続行します。任意のトラッカー URL があれば記録します。other、判定結果がない場合、信頼できない投稿者の場合、マーカーが競合する場合、またはタイムアウトした場合は、何も通知せずに停止します。

このマーカーによって、非公開のボット ID と自由形式の判定結果の照合を置き換えます。

3. 所有権と修正成果物のゲートを適用する

作業を開始する直前に、スレッドを再度読み込みます。

誰かが明確に修正を担当している

担当者が修正を明確に引き受けている場合、具体的な実装計画を示している場合、または別のエージェントに実装、パッチ作成、修正、プルリクエストの作成を依頼している場合は、そこで停止します。

以下は修正の担当とはみなしません。

• ボットが証拠を要約している。
• ツールがログやチケットを検索している。
• 誰かがボットに診断、説明、調査、再現を依頼している。
• ボットが実装に同意せず、原因の仮説を投稿している。

ボットの有無ではなく、依頼された対応内容に基づいて判断してください。

修正の成果物がすでに存在する

オープンなプルリクエストまたはマージ済みのコミットが、この報告を修正している可能性がある場合は、references/verify-existing-fix.md に切り替えてください。

成果物は、スレッド、トラッカーの issue、リポジトリの履歴、またはプルリクエストの検索結果から見つかることがあります。コミットもプルリクエストも伴わない主張は、修正の成果物ではありません。

担当者がいるものの、成果物がまだ作成されていない場合は、停止してください。先回りして作業しないでください。

4. 任意の運用スレッドを開く

slack.operations_channel_id が設定されている場合、コーディネーターはそのチャンネルにステータスのルートメッセージを1件作成できます。再現ワークフローで許可されるルート投稿はこれだけです。

その座標を OPERATIONS_CHANNEL_ID および OPERATIONS_THREAD_TS として保存してください。ソースの座標と混同しないでください。

設定済みのプレーンな Unicode ステータス文字列を使用してください。ステータス文は短くしてください。

• 再現中
• 再現できませんでした
• ブロックされています
• 再現しました
• 既存の修正を検証中
• 範囲を限定した修正を試行中
• ドラフトのプルリクエストを作成しました
• 修正は反映されませんでした

設定済みの Cursor Slack アクションを優先してください。BENNY_SLACK_BOT_TOKEN は、このステータスメッセージ1件の編集など、限定的な機能不足を補うためにユーザーが設定した場合に限り使用してください。このトークンをワーカーに公開しないでください。

運用チャンネルが設定されていない場合は、詳細なステータスを自動化の実行出力に記録してください。ソースチャンネルへのルートメッセージで代用しないでください。

5. コントロールアダプターを読み込んで確認する

references/control-adapter.md と、完成済みの control.feature_map_path のマップを読み込み、control.skill_name で指定されたスキルを呼び出してください。

報告されたユーザーパスに一致する機能マップのセクションを見つけてください。アプリを操作する前に、そのセクションを読み込んでください。機能をカバーするセクションがない場合は、パスやセレクターを作り出さず、実行をブロックとして記録してください。

以下の7つすべての機能が必要です。

1. 設定済みの対象アプリとテスト環境を起動する。
2. マップされた機能に移動し、記載されている状態を操作する。
3. クリック、入力、キー操作、スクロール、ドラッグ、サイズ変更、またはナビゲーションで実際の UI を操作する。
4. 状態を変更せずに調査する。
5. スクリーンショットを撮影する。
6. 画面録画を開始および停止する。
7. プロセス、セッション、プロファイル、一時データをクリーンアップする。

アダプターが存在しない場合、または必須機能が1つでも欠けている場合は、運用ステータスを「ブロックされています」として記録し、停止してください。スクリーンショット、単体テスト、状態の変更、ソースコードの読み取りを、UI の再現であるかのように扱わないでください。

6. 報告を調査する

ソーススレッド全体と、存在する場合はトラッカーの issue を読み込んでください。

以下を収集してください。

• 正確な操作手順
• 期待される動作
• 実際の動作
• 両者が分岐する状態の違い
• 発生頻度
• バージョン、環境、プラットフォーム
• 添付ファイルとエラーの特徴
• 修正候補となるコード領域

スクリーンショットと動画を確認してください。必要に応じて、コード履歴、テスト案、影響範囲の把握、メディア確認のために読み取り専用の並列ワーカーを使用してください。各ワーカーには限定的な質問を割り当て、Slack への書き込みを禁止してください。

pstack の how スキルを使って、操作の流れをリポジトリ内で追跡してください。回帰履歴や防御的なコードを調べるには why を使用してください。競合する原因仮説を立て、それらを判別できる証拠を特定してください。

7. 再現

制御アダプターを通じて対象アプリを起動します。

操作を始める前に、正しいアプリ、ワークスペース、アカウント、データセット、機能の状態であることを確認します。安定したアプリの識別情報を使ってください。ウィンドウの順番や、見慣れたタイトルだけに頼らないでください。

報告された経路を、実際の UI 操作でたどります。

再現できたと判断する前に、次の手順を実施してください。

1. 正常な最終状態を明確にします。
2. 問題が発生する最終状態を明確にします。
3. 両者が分岐する地点まで進みます。
4. 問題が発生する状態を確認します。
5. 2回目の試行が独立したものになるよう、十分に状態をリセットします。
6. 同じ経路をもう一度たどり、同じ問題が発生する状態を再確認します。
7. 可能であれば、実際の状態値と照合します。

想定内のダイアログ、読み込み状態、セットアップ手順はバグではありません。正常動作と問題のある動作を区別できる最終状態を記録してください。

設定された再現予算を使用します。予算内に症状が再現しない場合は、Could not reproduce の結果を報告してください。環境に必要な機能がない場合は、Blocked と報告し、何が不足していたかを明記してください。

8. 証拠の取得と確認

再現に成功した場合：

• 症状が現れるまでの全経路を記録します。
• 問題が発生する最終状態のスクリーンショットを撮影します。
• 正確な手順と確認した状態を短いメモに保存します。
• 成果物は、設定された一時成果物ディレクトリに保管します。

読み取り専用のメディアレビュー担当者に、次の1点を確認してもらいます。証拠に、問題を区別できる状態が視覚的に示されているか。

回答が「いいえ」または不確かな場合、再現は確定していません。より適切な証拠を取得するか、Could not reproduce を使用してください。

詳細な証拠を投稿するのは、設定されている場合に限り、運用スレッド内だけにします。ソースの更新は簡潔にしてください。

9. 再現結果の報告

まず運用ステータスを更新します。

Could not reproduce または Blocked の場合、ソーススレッドには何も投稿しません。結果は運用スレッドまたは実行出力に記載します。

再現が確認できた場合は、ソースの事前確認を実行し、プロンプトされていないソースへの返信は最大1件まで投稿します。

• 問題が再現したことを伝えます。
• 運用の証拠スレッドがある場合は、そこへのリンクを記載します。
• 短い調査結果は最大3件まで記載します。
• トラッカーの課題がある場合は、そのリンクを記載します。
• デフォルトでは担当者にメンションしないでください。

設定された Slack アクションによって証拠が同じソーススレッド内に保管され、組織の保持ポリシーで許可されている場合に限り、証拠を添付します。

設定された異議申し立て期間が終了するまで待ちます。セットアップまたは解釈に誤りがあったことを人が示した場合は、再現を1回修正します。有効な異議がないまま期間が終了するまで、修正フェーズを開始しないでください。

10. 既存の修正を検証

修正の成果物がある場合は、references/verify-existing-fix.md に従ってください。

検証では、ベースラインで症状が発生し、パッチ適用済みビルドでは発生しないことを示す必要があります。どちらの経路も、実際の UI で2回実行します。

既存の修正を編集したり、競合するパッチを追加したり、代わりのプルリクエストを作成したりしないでください。

11. 範囲を限定した修正の適格性を確認

次の条件をすべて満たす場合に限り、修正を試みます。

• 結果が、単純に再現を確認したものであること。
• メディアレビューで、問題が発生する最終状態が確認されていること。
• 既存の修正成果物が見つかっていないこと。
• 異議申し立て期間中に、修正を担当すると申し出た人がいないこと。
• 実行時の証拠から根本原因が特定されていること。
• 想定される変更が、設定された修正予算とリポジトリの範囲内に収まること。
• 制御アダプターでベースラインとパッチ適用済みビルドの両方を実行できること。

条件を1つでも満たさない場合は、再現報告を残し、プルリクエストを作成せずに停止します。

条件を満たしたら、運用ステータスを Attempting bounded fix に更新します。

12. 根本原因の特定と実装

Slack へのすべての投稿、最終的な差分レビュー、コミット、プルリクエストはコーディネーターが担当します。

読み取り専用のワーカーは、次の作業を行えます。

• コードと履歴を追跡する
• テストを提案する
• 影響範囲を特定する
• 差分をレビューする
• メディアをレビューする

ワーカーは編集、外部への書き込み、ステータスの投稿、修正の担当を行いません。

ツールの分離によって、そのワーカーから Slack の認証情報と Slack へのすべての書き込み操作を取り除ける場合に限り、このフェーズでは範囲を厳密に限定したコード編集を委任できます。その場合も、プロンプトには Slack への書き込みを明示的に禁止する指示を含める必要があります。コーディネーターが編集内容をレビューし、必要なテストを実行または検証します。ツールの分離に確信が持てない場合は、編集をコーディネーターが担当してください。

実行時の証拠を使って仕組みを確認します。編集前に、競合する仮説を排除します。

根本原因を、正当化できる最小限の変更で修正します。

• ローカルで安価に実行できるテスト対象がある場合は、pstack の tdd スキルを呼び出し、修正前に失敗するテストを作成します。
• 対象の処理が高コスト、不明瞭、またはインテグレーション中心のため TDD を省略した場合は、その理由を説明します。
• 無関係なクリーンアップは行いません。
• 変更が設定された作業量またはリスクの上限を超えた場合は中止します。

13. 修正を実証する

元の修正前の証拠を保持します。

修正済みビルドで、次のことを行います。

1. 同じ実際の UI 操作を実行します。
2. その操作を 2 回繰り返します。
3. 壊れた状態が解消されたことを示します。
4. 代わりに期待される状態になっていることを示します。
5. 修正後の録画とスクリーンショットを取得します。
6. 修正前の検証で使ったのと同じ実際の状態値と照合します。

コンパイル、単体テスト、コードレビュー、または妥当そうな差分は、修正後の証拠にはなりません。

対象を絞ったテストを実行し、その後、変更した動作の影響範囲をスモークテストします。変更によって影響を受ける可能性のある、周辺の状態、入力、権限、プラットフォーム、失敗経路を確認します。リグレッションが残る場合は、プルリクエストを作成せずに中止します。

14. ドラフトプルリクエストを作成する

修正前後の実証を終えてから、次の作業を行います。

• 最終差分に無関係な変更やシークレットが含まれていないかレビューします。
• リポジトリで必須とされているチェックを実行します。
• リポジトリのワークフローで可能な場合は、順序立てて小さなコミットを作成します。
• ドラフトプルリクエストを作成します。このワークフローでは、マージやデプロイは決して行わないでください。
• トラッカーがサポートするプルリクエストの構文を使って、設定されたトラッカーの課題にリンクします。
• 通常は https://github.com/{owner}/{repo}/pull/{number} となる、設定済みの公開 URL 形式を使用します。
• 再現手順、根本原因、テスト結果、修正前後の証拠、影響範囲の確認内容を記載します。
• プルリクエストの本文と Slack へのすべての更新に、pstack の unslop スキルを使用します。

プルリクエストの作成に失敗した場合は、成功したと主張しないでください。実行結果にコミットまたはブランチの状態を残し、運用ステータスを Fix did not land に設定します。

成功した場合は、運用ステータスを Draft pull request opened に設定し、リンク付きのプルリクエストを運用スレッドに簡潔に 1 回だけ返信します。元のチャンネルに新たなスレッドを立てたり、求められていない返信を元のチャンネルに投稿したりしないでください。

15. フォローアップとクリーンアップ

設定された運用スレッドを、1 回のフォローアップ期間のあいだ確認します。

• すでに収集した証拠に基づいて、直接の質問に回答します。
• セットアップに問題があると判明した場合は、具体的な修正を 1 つ適用し、再現確認を 1 回再実行します。
• 人間同士の調整や余談には関与しません。
• 指示があれば停止します。

制御アダプターのクリーンアップ機能を必ず呼び出します。成果物は、設定された保持ポリシーで許可される期間だけ保持します。