verify-on-local

PR で変えた画面が動くことを確かめ、その証拠をスクリーンショットと動画で残すスキルです。

動作確認の手順の正本はここです。 共有の環境で確かめるスキル（ /verify-on-dev1 など）も、確認の組み立てから報告の組み立てまではこの手順に従い、環境だけの事情（前提の確かめ方・ログイン・報告の出し先）を足します。

撮り方は references/capture.md が持ちます（どの位置を撮るか、描画の待ち方、2回撮って照合する、副作用のある操作で状態を見る3つの時点、ログインを別の context で済ませる）。撮影の段に来たら開きます。

PR への貼り方は /update-pr-description の references/testing.md が持ちます（画像の並べ方、--attach の挙動、撮り直した後の貼り替え）。

画面へ辿り着く手順（ログイン、強制ログイン、手元で API を動かす条件）はプロジェクトごとに違います。プロジェクト向けの撮影スキルと、そのリポジトリのメモリを先に読みます。

画面の操作のしかたを貯めた場所があれば、操作の前に読みます（環境のスキルの references/ など）。毎回ゼロから操作を探すと、確認のたびに同じ試行錯誤をやり直すことになります。プロダクトは日々変わるので、書いてあるとおりに動かなかったら、動く形を確かめてからその場で直し、項目に添えた確かめた日とコミットも書き換えます。新しく分かった手順も、確認を終える前に足します。

このスキルを呼ぶこと自体が撮影の指示に当たります。--screenshot と --video は要りません。

引数

引数	意味
`<PR 番号または URL>`	対象の PR。複数並べてよい
`<課題キー>`	対象の課題。紐づく PR を課題から引く

引数が PR か課題かで、確かめる問いが変わります。

引数	確かめる問い
PR	その PR の変更で、課題に書かれたとおりに直っているか
課題	その課題をクローズしてよいか。紐づく PR を全部見て、コメントで後から足された範囲・差し戻し・残った項目まで追う

PR が引数でも、課題の本文とコメントは読みます。課題が求めることと照らさないと、PR が直したと言っている範囲の中でしか判定できません。

動かすのは手元の環境です。共有の環境（dev1 など）で確かめるときは、その環境のスキルを使います。

原則（どの環境の確認でも変えない）

原則	なぜ
前提を先に確かめる（載っているか・その経路を通るか）	前提が崩れていると、画面の結果は修正と無関係になる
期待を、操作の前に決める	結果を見てから期待を決めると、何が出ても「期待どおり」になる
効いたときと効かないときの両方を見る	片方だけだと、条件が効かず全部出ている（全部落ちている）状態と区別できない
陽性対照を置く（「起きない」を見るなら、起きうる状態であることを先に見る）	「出ない」「変わらない」は、見えていないだけ・届いていないだけでも起きる
判定は観測で行う（画面の表示・DB の値・ログ）。成功表示を信じない	画面は成功に見えても裏で失敗していることがある
確認していないことを書く	範囲が読み手に伝わらないと、確認済みと受け取られる

原則の土台は pstack の principle-prove-it-works （代わりの指標や自己申告ではなく、実物で確かめる）。上の表は、それを画面の確認へ具体化したもの。

確認の形は変更ごとに違います。 決まった段を順に踏むのではなく、原則を守りながら変更に合わせて組み立てます。今回の確認に当てはまらない段は省いてよい。

進め方

1. 確認の組み立てを決める

PR の差分と課題の受入基準（課題が引数なら、紐づく PR の全部と課題のコメントも）を読み、何が起きれば「修正が効いた」と言えるかを1〜3行で書きます。それが確認観点になります。そのうえで変更の種類から組み立てを選ぶ。複数に当たるなら組み合わせる。

変更の種類	確かめる形	見るもの
参照（検索・一覧・詳細）	条件に合うデータと合わないデータを用意し、画面で出る / 出ないを見る	画面の結果と、適用中の条件の表示
書き込み（登録・更新・削除）	操作の前後で値を比べる。操作した後に、参照する画面で読み戻す	DB の値（前後）・画面の再読み込み
バッチ・非同期の処理	実行の契機（スケジュール・手動実行・イベント）を確かめ、入力のデータを用意して流す	出力（メール・DB・ログ）と実行ログ
画面の無い API	`curl` 等で叩く。認証の取り方を先に確かめる	応答の本文と DB
表示だけの変更	修正前後の見え方を並べる	スクリーンショット
外部連携（メール・通知・他サービス）	その環境で実際に送られるか（送信先の設定）を先に確かめる	送信先・ログ

修正前と比べるか、修正後が動くことだけを見るかを先に決めます。 環境で症状を再現できないなら（例: 読み取り用の DB の遅れが原因で、手元には読み取り用の DB が無い）、比べても差が出ません。その場合は修正後だけを見ると、報告の冒頭に理由と一緒に書きます。

その環境で確かめられないもの（本番にしか無いデータ・外部サービスの設定）は、確かめられる範囲と、代わりに何で担保するか（テスト・コード）を書きます。

2. 確認項目を作る

変えた操作ごとに1行の確認項目を作ります。

列	書くこと
画面	利用者が見る画面の名前
操作	画面の文言で書いた操作
期待する動き	操作の後に画面で見えること

画面に出ない項目（フラグで隠れている、データが0件で出ない）は、撮る前に分かる範囲で外し、理由を控えます。報告の「確認していないこと」に書きます。

3. データを用意する

既存のデータで足りるか、作るかを先に決めます。

状況	扱い
修正が効くデータが既にある	DB で探して選ぶ。まず件数を数え、0件なら作る側へ
無い・境目の値が無い	自分で作る（画面から Playwright で、または SQL で）
書き込みの確認	操作の前の値を DB で控えておく

同じ課題を前に確かめたことがあるなら、前回と同じアカウント・データ・画面・操作で確かめます。 差し戻しの後の確認では、前回の報告と並べると修正前後の対比になります。条件が1つでも違うと、差が修正から出たのか条件の違いから出たのかを見分けられません。条件は前回の報告の「確認環境」と「検証用データ」から引き、ログインの状態のように残っていないものだけを同じアカウントで作り直します。前回の確認でデータが進んでいて同じ状態に戻せないときは、何が違うかを報告に書きます。

既存のデータは読むだけにし、書き換えるのは自分で足したデータだけにします。 既存のデータを書き換えて確かめると、戻し忘れたときに他の人の状態を変えます。

足す前に、戻す手順を書いておく（SQL なら削除と元の値への更新）
足す行の ID は、結合で引いて確かめる。近い ID を目で選ぶと、別の事業者や別の利用者の行に入れる
一時的に既存の値を変えるとき（ログインの日時、パスワード）は、変える前の値を控える

選ぶときの注意です。

その修正だけが効くものを選ぶ。 既存の経路でも当たるデータでは、修正の有無を見分けられない
画面に出る前提の値（公開状態など）を確かめる
画面で探すときの名前と ID を両方控える。 同じ名前が複数あると画面で特定できないので、名前で件数も引く

4. 塗りつぶす語を集める

塗りつぶすのは、実際の顧客データが画面に出うる環境（本番など）を撮るときだけです。 検証用のデータしか入っていない環境（手元・開発用の共有環境）では塗りつぶさず、MASK も渡しません。塗りつぶすと画面の文字で要素を探せなくなり、名前でアカウントを照合することもできなくなります。そうした環境では、ログインの操作を録画に入れてもかまいません（要らなければ入れなくてよい）。どの環境に実際の顧客データが入っているかは、環境のスキルかメモリが持ちます。

塗りつぶすときは、DB の値ではなく、画面に出ている文字から集めます。 DB の名前と画面の表示が一致するとは限りません（姓名の並べ方、「、」で並べた一覧）。

撮る画面を一度開き、顧客の企業名と社員の氏名・メールアドレスを innerText から集める
「、」や「,」で並んだものは1語ずつに分ける
MASK に渡す

scripts/record.mjs は、静止画を撮るたびに画面の文字に MASK の語が残っていないかを数え、残っていれば失敗にして動画を消します。漏れを目視で探さないためです。

塗りつぶすと画面の企業名でアカウントを照合できなくなります。照合はログインの段（録画しない画面）で済ませます。

5. 撮る

シナリオは1項目1スクリプトにし、scripts/record.mjs の record で包みます。使い方はファイルの冒頭にあります。ログインは録画しない context で済ませ、storageState を record へ渡します。

OUT_DIR=<スクラッチパッド>/out node <シナリオ>.mjs                      # 塗りつぶさない環境
OUT_DIR=<スクラッチパッド>/out MASK='<集めた語>' node <シナリオ>.mjs    # 塗りつぶす環境

認証情報はコマンドの引数に書かずにファイルから読みます。値も出力しません（ no_secret_values_in_output.md ）。

1項目ごとに静止画を「操作の直後」と「読み直した後」の2枚撮ります。保存した値が直後だけ出て、読み直すと消える不具合を見分けるためです。

結果だけでなく、その結果を出した条件も写します（適用中の条件の表示など）。入力欄を書き換えて実行する前の画面だと、入力と結果が食い違います。

結果が揺れうるときだけ、2〜3回流して差を見ます。 当てはまるのは、待ち時間や通信の順に左右される表示、キャッシュ、前の操作の状態が残る画面、1回目が期待と食い違った結果です。毎回流すと確認が遅くなるので、揺れる理由が無い確認は1回で済ませます。複数回流したら、報告に回数と、毎回同じだったか（違ったならどう違ったか）を書きます。

6. 判定する

期待と違うときは、修正を疑う前に前提（デプロイ・フラグ・データ・操作）を疑う
足りないケースがあれば、何を追加で見ればよいかを決めて撮り足す
最後に「必要最低限の確認が済んだか」を、受入基準と照らして言い切る。確認していないことは、コードやテストで担保されているかを添える

7. 戻す

撮り終えたら、手順3で書いた戻し方を流し、戻ったことを数えて確かめます（足した行が0件、変えた値が元の値）。戻す SQL の成功表示は、戻ったことを示しません。

自分で起動したサーバー、コンテナ、worktree も止めます。もともと動いていたものは止めません。止めてよいか分からなければ、ユーザーに尋ねます。

8. 報告を組み立てる

画面・メール・ファイルの中身など、見て確かめられるものは撮って載せます。 文字だけで済ませるのは、撮れないもの（コマンドの出力など）に限ります。読み手は、書かれた値より画像を見て確かめるためです。

画像は、説明の表の同じ行のセルに置きます。 説明の表と画像の表を別に作ると、読み手は2つの表の行を突き合わせることになります。分けるのは、そのほうが分かりやすいとき（1行に画像が多すぎて表が読めないときなど）だけです。

画像と動画が数枚なら PR 本文に、それより多ければ補足コメントにまとめます。コメントにしたら、本文の「テスト内容」から1行でリンクを張ります。課題へ報告する環境のスキルも、節の並びはこれに合わせます。

節	中身
1行目	`[fyi]` と、何を確かめたかの1〜2行（修正前と比べたか、修正後だけを見たかと、その理由）。続けて、問題があったか・あったなら何件かを書く（「問題が1件あります」「問題はありませんでした」）。課題が引数なら、クローズしてよいかも書く
確認観点	何が起きれば修正が効いたと言えるか。境目を含める
確認環境	環境・動かしたコミット・接続先・ログインの経路とアカウント・画面の通称と URL・通った経路（フラグの値）
検証用データ	用意したデータ・ファイル・アカウント。列は「開き方」「作り方」「使う手順」で、読んだ人が同じものを作り直せるところまで書く。既存のデータを選んだなら選んだ条件を、検索や絞り込みに使った語は入れた欄と選んだ理由を、作るときに詰まったことはどう解いたかを添える
確かめ方	行った操作の要約。陽性対照を見た旨も
塗りつぶしと録画していないもの	塗りつぶした環境のときだけ置く。塗りつぶした語の種類と、録画していない操作（ログイン）
結果	2枚の見方と、結果の表: `判定 / 画面 / 操作 / 期待する動き / 結果 / 画像` 。画像は表のセルに置く
確認していないこと	範囲外にしたものと、その理由。途中で見つけたこと
項目ごとの詳細	結果の表に入りきらない画像と動画。 `<details>` には畳まない（ `/format-post` の「判断に使うもの（結論・症状・影響・画像）を畳まない」）

結果の列には、画面で見えた値を書きます（「保存の直後も読み直した後も『年収を重視』」）。「問題なし」「期待どおり」とだけ書くと、何を見たかが残りません。

期待と結果は列を分け、語尾でも書き分けます。 期待には正しい値（時刻・件数・表示の文言）を「〜こと」「〜べき」で、結果には観測した値を「〜となる」「〜である」で書きます（期待「12月10日の14時の枠に出ること」、結果「❌ 12月11日の7時の枠に出る」）。1つの欄に正しい値と観測した値を一緒に書くと、❌ の行でどちらが正しいのかが分かりません。比べる相手を併記するとき（「東京のブラウザでは〜」）は、それが期待どおりかも書きます。

書くのは、貼った静止画に写っている時点の値だけです。読み手は表の値と画像を突き合わせます。直後の静止画を撮っていない項目に「直後も」と書くと、表と画像が食い違います。撮っていない時点は「（直後は撮っていない）」と書きます。

結果の表の前に、2枚の見方を書きます。2枚に同じ値が出ていれば正しい、ということは表からは読めないためです。直後の画面はこの PR で変えた処理が出した表示で、読み直した後の画面はサーバーに保存された値です。2枚の値が同じなら、画面に出した値と保存された値が食い違っていないことが分かります。

途中で見つけた別件は確かめた範囲を添えて書きます。手元でしか見ていないものは、そう書きます（ base_records_on_measurements.md ）。

投稿の前に文章の点検を通し（ no_ai_style_writing.md ）、投稿した後は ./ の参照が残っていないことを確かめます。

やってはいけないこと

期待を決めずに操作すること
見て確かめられるものを撮らずに、文字だけで報告すること
画像や動画を <details> に畳むこと。開かない読み手に届かない
分ける理由が無いのに、説明の表と画像の表を別に作ること
「起きない」ことを、陽性対照なしで判定すること
自分で足していないデータを書き換えて確かめること
戻したことを、戻す操作の成功表示だけで確かめること
塗りつぶしの漏れを、画像の目視で確かめること
実際の顧客データが入っていない環境で、塗りつぶすこと
揺れる理由が無い確認を、毎回複数回流すこと
結果を出した条件が写っていない画面で判定すること
再現できない環境で、修正前と比べた体裁の表を作ること。差が出ないので、比べたことにならない
検証用データを、開き方だけ書いて作り方を省くこと。作り直せないと、同じ確認ができない
今回の確認に当てはまらない段を、形だけ埋めること
プロジェクト固有の到達手順（ログインの方法、手元の API の起動）をこの本文に書くこと。プロジェクトの撮影スキルかメモリへ置く
撮り方を本文に書き写すこと。references/capture.md と二重になる。貼り方は testing.md に従う