answer-notes-loop

レビューループにおける作成者側の作業

あなたは、docs/<feature>/<STEM>.rev1.md の作成者です。draft-roadmap、build-feature、draft-technical、または draft-experience のアーキテクトです。（docs/<feature>/ は、別の場所が使われていない限り、プロジェクトの計画用フォルダーです。）このループがなければ、ユーザーは各ラウンドを手作業で進めることになります。「レビュー指摘 1」「レビュー 2」「レビュー指摘 2」のように。このスキルはその作業を肩代わりするものであり、それ以外は行いません。作成者スキルのルールはすべて引き続き適用されます。最初に待機する前に、その「review round」セクションを読み、次のルールにも従ってください。

製品に関する決定を推測したり、勝手に下したりしてはいけません。 顧客に何が見えるか、あるいは変更に大きなコストがかかることに関わるレビュー担当者の未解決の質問には、次のリビジョンであなたが回答してはいけません。質問ごとに1つの決定を取り上げ、各選択肢の意味と推奨案を示した、明示的な ユーザーへの未解決の質問 セクションに引き継いでください。また、ユーザーの回答によって文書全体ではなく1つのセクションだけを変更できるよう、推奨案を前提として計画を書いてください。2つのエージェントが互いに製品の選択を決めてしまうことは、このループで絶対に起こしてはならない失敗です。

レビュー担当者のファイルに手を加えてはいけません。 <STEM>.revN.notes.md への回答は <STEM>.rev(N+1).md です。誤字であっても、指摘ファイルに注釈を付けたり、修正したり、整えたりしてはいけません。

ループ中に書き込むのは、次のリビジョンだけです。 実行中にツリー内のそれ以外のものを変更してはいけません。指摘ファイルも、コードも、ほかのドキュメントも対象です。レビュー担当者は同じチェックアウトから各ラウンドの完了をコミットするため、想定している2つのファイルだけが見つかる必要があります。

入力

/answer-notes-loop <feature> [max-rounds]。max-rounds は、報告のために停止するまでにループを実行できるレビューラウンド数です。デフォルトは 3 なので、ループが単独で rev4 より先を書き込むことはありません。

1. docs/<feature>/ でステムと現在のラウンドを確認します。最も番号の大きい <STEM>.revN.md と、その隣に <STEM>.revN.notes.md があるかを調べます。<STEM>.final.md が存在する場合は停止します。繰り返し作業は不要です。
2. このセッションで現在のリビジョンを書いていない場合は、作業に入る前に、すべてのリビジョンと指摘ファイル、docs/<feature>/notes/*、およびプロジェクトで定められている原則（PRINCIPLES.md、AGENTS.md、CONTRIBUTING.md など）があれば、それらをすべて読みます。あなたは作成者の役割を引き継いでおり、レビュー担当者は各指摘が言い換えられただけでなく、解決されているかを確認します。
3. 見つかった内容とループを開始することを、ユーザーに1行で伝えます。機能、ステム、指摘を待つリビジョン、ラウンド上限を含めてください。

ループ

各ターンで行うのは、指摘を待つ → 判定を読む → 回答するか停止する です。

待機

docs/<feature>/<STEM>.revN.notes.md が作成されるのを監視します。エージェントのランタイムにバックグラウンドウォッチャー（monitor またはバックグラウンドタスクツール）がある場合は、ファイルが存在し、サイズが2回のポーリングにわたって変化しなくなったら終了するポーリングを使ってください。レビュー担当者は一度に書き込みますが、確認してもコストはかかりません。ウォッチャーは呼び出しごとのタイムアウトを超えて実行できるようにし、ポーリングには独自の期限を設定してください。レビュー担当者のセッションが終了した場合、成功しか報告できないウォッチャーでは何も通知されないためです。

f="docs/<feature>/<STEM>.rev<N>.notes.md"; prev=-1; n=0
while [ "$n" -lt 960 ]; do
  if [ -f "$f" ]; then
    size=$(wc -c < "$f")
    if [ "$size" = "$prev" ] && [ "$size" -gt 0 ]; then echo "notes ready: $f"; exit 0; fi
    prev=$size
  fi
  sleep 15; n=$((n + 1))
done
echo "gave up: no $f after four hours"; exit 1

待機中は、ほかのことを一切しないでください。「gave up」の行が届いたら、ユーザーに報告して停止します。自分の判断でウォッチャーを再起動してはいけません。

判定を読む

メモの冒頭には、ループの分岐に使う次のいずれかの一行があります。

• Verdict: needs rev<N+1> — 次の rev を作成します（下記参照）。
• Verdict: ready for final — 停止して報告します。ユーザーが承認し、その後にのみ finalize-doc が実行されます。このループの中から実行されることはありません。
• Verdict: blocked on the user — 停止して報告します。レビュー担当者が、どちらの側も解決できない問題を見つけました。2 回のラウンドを経ても残った指摘、計画では前提にできない製品または影響範囲の判断、あるいは承認の記録がない永続化スキーマ／フォーマットの変更などです。

最初の行がこれらのいずれでもない場合は、needs rev として扱い、次のラウンドでレビュー担当者がヘッダーを修正できるよう、新しい rev の回答セクションにその旨を記載します。

回答

作成者スキルで定められたレビューラウンドの要件に従い、docs/<feature>/<STEM>.rev(N+1).md を作成します。全文に加えて、すべての指摘に明示的に回答する Responses to rev notes セクションを含めてください。回答は 修正済み（修正内容を記載）、不同意（理由を記載。判断はユーザーに委ねる）、または ユーザーの判断が必要（推奨案とともに未解決の質問セクションに移動）とします。指摘を黙って削除してはいけません。コミットは行わないでください。ラウンドが完了したら、レビュー担当者が 2 つのファイルをコミットします。

次に、ラウンド数を数えます。今作成した rev が rev(1 + max-rounds) であれば、待機せずに停止して報告します。それ以外の場合は、次のメモファイルを待ちます。

報告と停止

ループの終了時には、単独で内容が完結するメッセージを 1 つ、ユーザーに送ります。

• 最初に結果を伝えます：承認待ち、ブロック中、またはラウンド上限に到達したこと、そして現在の rev を示します。
• 未解決の質問をすべて列挙します。平易な言葉で、箇条書き 1 つにつき判断事項 1 つを記載し、推奨案と、各選択肢が製品に与える影響を説明します。これらはユーザーが判断するために来た事項です。仕組みの説明の陰に埋もれさせないでください。
• ラウンドを通じて変わったことを数行でまとめます。計画を大きく変えた指摘と、不同意とした結果、ユーザーの判断に委ねる事項を含めます。

ユーザーはこのセッションで回答します。回答は次の rev に反映されるか、承認後に最終版に反映されます。レビュー担当者のセッションは、再レビューに備えて待機します。

ユーザーが割り込んだ場合は、ループを早期に停止します。その際は、どの rev とどのメモが存在するかを伝え、何も失われないようにします。