decision-doc reference

decision-doc は、ユーザーにしか決められない判断を推奨案で仮確定し、HTML のレビューで確定させる skill である。

差し戻しは RHW(reviewable-html-workbench)の inline comment と判断ごとの選択 widget だけで受ける。chat で決定 ID を指定してもらう方式と自前 HTML fallback は使わない。

Issue 作成、コード変更、commit、PR 作成、下流 skill の起動は行わない。

直接質問は既定で 0 件とする。推奨を立てられない論点も HTML の「確認できていないこと」節で回答してもらう。

対話手段がない非対話 worker から呼ばれた場合は decision-doc を起動せず、needs_user_decision と構造化した質問一覧を親へ返す。

まず何が起きるか

テーマまたは既存 research packet から判断を仮確定した packet-in.json を作り、HTML を既定 browser で開く。

HTML の本文には、対象と目的、ユーザーが決める判断、確認できていないことだけを出す。確認済みの事実、変えない契約、採らなかった案、agent が決めてよい仮確定は、末尾の付録に閉じた状態で畳む。

本文の判断は 7 件までを目安とする。判断の見出しには packet の decisions[].topic を、目的には goal を出す。design doc など参照先がある場合は source_facts[].source に URL を書くと参照 link に載る。

Issue も design doc も無いテーマでは、packet の background を「背景」として本文に出す。

ユーザーは判断ごとに推奨案か代替案を選び、必要なら comment を書いて完了 checkbox を入れる。agent は comment に add-reply で返信し、完了後に packet-out.json を作る。

起動方法は次の 2 つである。

/decision-doc <テーマ>
/decision-doc research-packet=<path>

どちらにも open=on|off を付けられる。既定は open=on で、open=off なら browser を開かず preview URL だけを報告する。

出力先は state root に固定する。出力先や追加入力を変える option は持たない。

前提条件

RHW の CLI が必要である。skill は開始時に python3 -m scripts.html_review_workbench.cli --help で存在を確認する。

見つからない場合は HTML を生成しない。次の導入 command を示して停止する。

# Claude Code
claude plugin marketplace add u-ichi/reviewable-html-workbench
claude plugin install reviewable-html-workbench
# Codex
codex plugin marketplace add u-ichi/reviewable-html-workbench
codex plugin add reviewable-html-workbench@reviewable-html-workbench-local

RHW を自動で install することはない。

artifacts

artifact は state root の artifacts/decision-doc/<id>/ に、packet-in.json、document-model.json、RHW の bundle/ の順に生成される。レビュー完了後に packet-out.json が加わる。

呼び出し元 skill が id を指定した場合、decision-doc は採番せず、その id を artifact id と packet-in.json の id に使う。

packet-out.json は task-research-packet.v1 互換で、下流 skill は research-packet= でそのまま読める。

render と ingest の入出力、判定順、変換規則は task-research contract の decision-doc 節にある。

レビュー完了と ingest

レビュー完了の合図は、RHW の preview server から届く decision_doc_completed event である。event を受けた skill は保存済みの widget state を読み直して ingest する。

完了 checkbox は、先行する widget 保存がすべて remote に保存されてから保存される。完了後に選択や回答を変えると完了は外れる。

comment を受けて判断を直した場合、skill は再 render したうえで完了 checkbox の入れ直しを案内する。

ingest が success かつ proceed のときだけ、skill は --prior-packet 付きの validate を通してから packet-out.json を報告する。

停止と再開

blocked の間は packet-out.json を報告しない。