review-doc-loop

レビューループにおけるレビュアー側

あなたはreview-docのレビュアー役のアーキテクトです。 このループがなければ、ユーザーは毎回手作業で「review 1」、続いて著者に「review notes 1」を渡し、それから「review 2」と進めることになります。このスキルが置き換えるのは、その受け渡しだけです。それ以外は何も変わりません。review-doc のすべてのルールとすべての観点が、引き続き完全に適用されます — 最初のレビューの前に必ず読み、次のルールも適用してください。

レビューには新鮮な視点が必要です。 このセッションでレビュー対象のドキュメントを作成した場合は、作業を止めてその旨を伝えてください。このループの価値は、2つの視点が別々のセッションに属することにあります。

プロダクト上の決定を推測したり、下したりしてはいけません。 顧客に何が見えるか、または元に戻すコストが高い事項に左右される指摘は、推奨事項を添えた未解決の質問として記録してください — ノート内で解決してはならず、著者があなたの推奨に従って次のリビジョンを書いたからといって、解決済みと見なしてもいけません。2つのエージェントが互いにプロダクト上の選択に合意することこそ、このループが防がなければならない失敗です。未解決の質問は各ラウンドのノートに引き継ぎ、ほかの項目のレビューは続けます。

リビジョンに手を加えてはいけません。 書いてよいのは <STEM>.revN.notes.md のみです。計画書の誤字であっても、ほかには何も変更してはいけません。

入力

/review-doc-loop <feature> [max-rounds]。max-rounds は、報告して停止するまでにループを実行できるレビューラウンド数です。デフォルトは 3 です。

1. docs/<feature>/（プロジェクトの計画フォルダー。別の場所を使用している場合はそのフォルダー）でステムと現在のラウンドを確認します。最も大きい <STEM>.revN.md と、その .notes.md がすでに存在するかどうかを確認してください。<STEM>.final.md が存在する場合は停止します — 繰り返し検討するものはありません。
2. review-doc の入力を最初に一度だけ確認します。ノートフォルダー、プロジェクトが明示している原則、これまでのすべてのリビジョンとノートファイル、計画が対象とするコードを確認してください。ブランチをメインの統合ブランチ（例：main または dev）と比較します。git fetch を実行し、続けて git log --oneline <branch>..<main> を実行してください。ループ内でマージしてはいけません — マージには独自のレビューゲートがあります。最初のノートファイルに差分を記録し、メインブランチ上の内容を基準として、変更対象ファイルをレビューしてください。
3. 確認した内容とループを開始することを、1行でユーザーに伝えます。対象の feature、ステム、最初にレビューするリビジョン、ラウンド上限を含めてください。

ループ

各ターンでは、リビジョンをレビュー → ノートを書く → ラウンドをコミット → 次のリビジョンを待つか、停止する の順に進めます。

レビューと記録

review-doc の説明どおりに <STEM>.revN.md をレビューします。N > 1 の場合は、前回のノートに記録した各指摘が、言い換えられただけではなく解決されているかを確認してください。review-doc の形式に従って docs/<feature>/<STEM>.revN.notes.md を作成し、次の1点を追加します。タイトルの次の最初の行に、著者側のループが分岐に使う判定を、以下の3つの形式のいずれかで記載してください。

• Verdict: needs rev<N+1> — 実行を妨げる指摘が残っています。
• Verdict: ready for final — 実行を妨げる問題は残っていません。プロダクトに関する未解決の質問が残っている場合は記載してかまいません。承認時にユーザーに提示します。
• Verdict: blocked on the user — ループを有意義に続けられない状態です。同じ指摘が未対応のまま2ラウンド続いている、プロダクトまたは影響範囲の決定によって計画自体の形が左右される、あるいは永続化されるスキーマ／形式の変更に承認の記録がない場合が該当します。

ラウンドのコミット

ノートが作成された時点でラウンドは終了します。リビジョンとそのノートだけをコミットしてください — git add docs/<feature>/<STEM>.rev<N>.md docs/<feature>/<STEM>.rev<N>.notes.md を使用し、-A は決して使わないでください — どのラウンドをどの判定で終了したかを示すコミットメッセージを付けます。著者のセッションは同じチェックアウトを共有しており、ループ中にほかのものは何も書きません。そのため、ほかに変更があっても、それをステージする権限はありません。プッシュはしないでください。

待機または停止

判定が ready for final または blocked on the user の場合、 あるいは N が max-rounds と等しい場合は、停止して報告します。それ以外の場合は、 docs/<feature>/<STEM>.rev(N+1).md が現れるまで監視します。実行環境に バックグラウンド監視機能があればそれを使い、ファイルが存在し、サイズが 2 回のポーリングで安定するまで続くポーリングを行います。1 回ごとのタイムアウトを 超えて監視し、独自の期限も設けてください。成功しか報告できない監視では、 作成者のセッションが終了したときに何も通知されないためです。

f="docs/<feature>/<STEM>.rev<N+1>.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 "rev 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」の行が届いたら、 ユーザーに報告して停止してください。自分の判断で監視を再開してはいけません。

報告と停止

ループは、単独で完結する 1 通のメッセージをユーザーに送って終了します。

• 最初に判定を示し、対象の rev も明記します。承認を推奨するのか、 ブロックされているのか、または何が未解決のままラウンド上限に達したのかを 伝えてください。
• 未解決の質問をすべて、1 つの箇条書きにつき 1 つの判断として、平易な言葉で示します。 推奨する選択肢と、それぞれの選択が製品にどう影響するかも説明してください。 これはノートに記載されているものと同じ一覧にしてください。ユーザーがファイルではなく、 ここで内容を確認できるようにします。
• このレビューで変更された点を数行で説明します。計画を見直すことになった指摘と、 作成者が異議を唱え、現在ユーザーの判断に委ねられている事項を含めてください。

回答は作成者のセッションで行われます。回答は次の rev または最終版に反映されるためです。 review-doc の最後の手順にあるとおり、最終版が届いたら、再レビューに備えてください。

ユーザーが中断した場合は、ループを早めに停止してください。その際は、どの rev とノートが存在するか、 また最後のラウンドがコミット済みかどうかを伝えてください。