verify-ui-change

実行中のアプリで変更を検証する

ユーザーに見えるものを編集しました。実際のアプリがその動作をし、DOM 以外の何かが同意するまでは、何も証明されていません。

これは Reticle を使用します。Reticle はユーザーの実行中アプリに開発時専用の SDK を埋め込み、reticle_* MCP ツールとして公開します。スクリーンショットは不要で、検証ループのためにブラウザーをダウンロードする必要もなく、独自の開発サーバーもありません。

1. ツールはありますか？

reticle_session({ action: "list" })

• セッションが返ってくる → 手順 2 に進みます。
• ツールが存在しない → Reticle がインストールされていません。まずユーザーに確認してください。init は package.json、ロックファイル、ビルド設定を変更します。同意が得られたら、RETICLE_INSTALL_SOURCE=npx_skill npx @reticlehq/server@latest init を実行し、ツールを使わずに続けます。出力された ⚠ をすべて解消し、アプリを提供しているものがなければ、プロジェクト独自の開発スクリプトをバックグラウンドで起動してから、npx @reticlehq/server open <the url the dev server is serving> で開きます。アプリが起動して接続された後に限り、自分ではできないことを 1 つだけ依頼してください。MCP サーバーを読み込むためのクライアントの再起動です。init コマンドを実行したところで止めると、ユーザーには設定ファイルと、計測機能のないページが残ります。セットアップの全手順は reticle スキルにあります。
• ツールはあるが、リストが空 → next_step があれば、まずそれを読みます。そこには init の同意確認があり、アプリが実行中の場合はインストール不要のリースについて書かれています。それ以外の場合は、応答の why フィールドを読みます。「アプリが実行されていない」「アプリは実行されているが、このデーモンに接続したことがない」「タブが開いていたが閉じられた」を区別しており、それぞれ修正方法が異なります。アプリが実行されていない場合は、package.json のプロジェクト独自の開発スクリプトを自分でバックグラウンド起動し、実行中であることと停止方法をユーザーに 1 行で伝えます。2 つ目は起動しないでください。コマンドを推測しないでください。何も終了させないでください。権限の確認はホストが行います。アプリがすでに実行中の場合、不足しているのはアプリではなく SDK です。ユーザーに、すでに起動しているものを起動し直すよう求めないでください。

2. 行動する前に、結果を明確にする

これがこの手法のすべてです。結果を見た後に書かれた期待は、起きたことに合わせていくらでも正当化できます。事前に書かれた期待はそうはいきません。

reticle_look({ action: "page", sessionId, mode: "interactive" })   // controls only, with refs

reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "allOf", predicates: [
  { kind: "net",     method: "POST", urlContains: "/api/...", status: 200 },
  { kind: "element", query: { testid: "..." } },
  { kind: "console", level: "error", absent: true },
]}})

複数ステップの操作ですか？ reticle_act { steps: [...] } を 1 回呼び出して操作し、その後に結果を 1 回だけアサートします。操作 → スナップショット → 操作 → スナップショットとはしないでください。同じことを、何倍ものコストをかけて証明するだけです。

判定は reticle_act_and_wait、reticle_assert、および expect を指定したステップを含む reticle_act { steps } から得られます。 単独の reticle_act、look、navigate、observe は、アプリを操作または読み取るだけで、何も証明しません。判定なしで終わる操作には、何回呼び出していても結果がありません。

3. 判定を正直に読み取る

verified	意味	対応
yes	指定した結果が起きた	証拠とともに報告します
no	起きなかった、または別の情報源が UI と矛盾した	実際の問題として、because とともに報告します
unknown	Reticle はアプリを操作したものの、判定できなかった	合格ではありません。 不明であることと、その理由を伝えます

unknown／unsettled の場合は、再操作するのではなく、操作結果に含まれる since を使って再アサートします：reticle_assert({ predicate, since, timeout_ms: 8000 })。再操作すると、すでに起きた副作用を繰り返すことになります。

判定を合格にするために、チェックを決して緩めないでください。 アサーションを編集して合格するようにしても、何も証明されません。

4. 触れていない箇所を確認する

reticle_run({ tool: "reticle_verify", sessionId, args: { action: "coverage" } })   // { total, exercised, untouched }

untouched に、変更の影響を受けるコントロールがまだ含まれているなら、操作は未完了です。1 回の呼び出しで、開いていない箇所を残したまま合格を報告するのを防ぐ、最も手軽な確認ができます。

5. レポート

実行したこと、判定結果、根拠を伝えます。リクエストとステータス、変化した状態、アプリ独自のシグナルを記載します。何か失敗した場合は、失敗した要素に対して reticle_look({ action: "element", sessionId, ref }) を実行すると file:line が得られます。レポートに記載してください。

次に reticle_session({ action: "yield", mode: "waiting" }) を実行して、人間のパネルに「live」と表示され続けないようにします。

---

詳しい情報は、1 ページずつ取得できます。インデックスには curl https://docs.reticle.sh/llms.txt を実行し、必要なページだけを取得してください（https://docs.reticle.sh/tools/act-and-wait.md、https://docs.reticle.sh/predicates.md、https://docs.reticle.sh/troubleshooting.md）。Reticle 自体が正しく動作しない場合は、reticle_session { action: "feedback" } で報告します。1 回呼び出せば、そのまま作業を続けられます。