fix-what-i-pointed-at

人間がバグを指摘しました。修正しましょう。

「そのカードの余白がおかしい」という指摘は、チャットでは対応できませんが、アプリ内なら具体的に伝えられます。実行中のアプリにある Reticle HUD には Notes パネルがあります。人間が Add notes をクリックし、要素を指して、どこがおかしいかを入力します。それぞれのノートは、要素、ノート、file:line を含むマークになります。通常ならスクリーンショット、説明、確認の質問が 2 回必要な一連のやり取りが、1 回の呼び出しで済みます。

まだセットアップしていない場合は、reticle スキルに従ってください。Reticle をインストールし、init によってアプリのファイルが変更される前にユーザーに確認し、1 つのフローを実演します。

マークを確認する

reticle_session({ action: "review", sessionId })

{
  "marks": [
    {
      "id": "m1",
      "note": "this button is misaligned",
      "label": "button \"Pay\"",
      "source": { "file": "src/Checkout.tsx", "line": 42 },
      "fix": "Open src/Checkout.tsx:42 and fix: this button is misaligned."
    }
  ],
  "pendingCount": 1
}

セッションの開始時に確認し、人間がアプリを操作した後にも再確認してください。読み取ってもマークは消費されないため、一覧表示 → 修正 → 検証 → 解決はどの順番で実行しても安全です。

作業の流れ

1. マークを読み取ります。複数のマークが同じファイルを指している場合はまとめます。1 回の編集で 3 件に対応できることもよくあります。
2. source.file の source.line を開きます。これが肝心です。そのボタンを描画したコンポーネントを探し回る必要はありません。
3. note の要望に合わせて修正します。ノートが曖昧な場合は、要素のラベルとソースを見ればたいてい明確になります。本当に必要な場合に限り、人間に確認してください。
4. アプリで検証します。目視だけで判断してはいけません。reticle_act_and_wait で該当するコントロールを再操作して、その結果を明示するか、レイアウトやテーマに関する指摘なら、対象の要素に対して reticle_look { action: "element" } を実行します。修正後に実際に見て確認することで、マークが再オープンされた際にも対応できます。
5. 次のように解決します。

reticle_session({ action: "review", sessionId, resolve: "m1" })

修正を検証してから解決してください。マークを解決済みにすることは、指摘された内容が完了したと人間に約束することです。

修正できない場合

そのマークについて修正できないことを伝え、未解決のままにしてください。マークを黙って無視するのは、未解決のままにしておくよりも悪いことです。人間は対応済みだと思い込み、後で未対応だと気づくことになります。ノートがバグではなく意図された動作を説明している場合も、その旨を伝え、判断を人間に委ねてください。

相手の言葉で報告する

相手が「そのボタン」を指摘したなら、「チェックアウト画面の［支払い］ボタン」のように報告し、変更内容と、正常に動作することを確認した根拠を伝えてください。マークを付ける人は画面を見ていて、リポジトリを見ているわけではありません。ファイルパスばかりでユーザー向けの説明がない報告では、相手の質問に答えられません。

---

その他の情報については、curl https://docs.reticle.sh/llms.txt を参照してください。利用可能なソースポインターがないマークが届いた場合は、kind: "gap" を指定して reticle_session { action: "feedback" } を送信する価値があります。