def-done: 完成の定義の構築・改訂

プロジェクトに 1 つの 完成の定義（Definition of Done） を対話で作り、 docs/dev/definition-of-done.md として書き出す単機能スキル。

成果物は 二部構成を強制する:

• 機械判定節: 各項目に判定手段（CI check 名 / 成果物パスと判定条件）を宣言する。 決定論スクリプトがテーブルをパースして項目別判定を報告できる形にする。
• 人判定節: 機械化できない項目のみを列挙する。人間が最終確認するチェックリストになる 唯一の部分。

「機械化できるものは全て機械判定節へ落とす」 のが本スキルの中心的な仕事であり、 人判定節は残余だけを引き受ける場所である。

項目数は二部合わせて最大 5 件に絞る。項目が多いほど各項目のクリアが重くなり 完成が遠のくため、上限は機械検査（dod-check.sh）でも強制される。

このドキュメントの位置づけ

• docs/dev/definition-of-done.md は プロジェクトに 1 つの恒久ドキュメント。
• 機能単位の作業ディレクトリ docs/dev/<対象>/ とは別の階層に置き、 機能単位の作業ディレクトリ削除の対象外である。機能開発が終わっても残り続ける。
• 内容の変更は本スキルの改訂モードで行う（機能ごとに作り直さない）。

このスキルがやらないこと（重要）

• 他スキルを呼び出さない。パイプライン上の前後工程（仕様作成・テスト計画・レビュー）へは 進まず、完成の定義の作成・改訂だけを行う。
• 完成の定義に照らした判定をしない。本スキルは定義を書くだけで、 「今この機能は完成しているか」の判定は消費側（下記）の領分。
• プロジェクトの CI やテストを構築しない。存在しない CI check を条件に書きたいと ユーザーが望んだ場合は、その旨を注記させるか人判定節へ回す判断を求める。

成果物の消費点（参考情報）

書いた完成の定義は次の 3 か所で任意入力として読まれる想定である（いずれも本スキルからは 起動しない。ユーザーがそれぞれのスキルを実行する）。

消費側	読む部分	用途
review-converge	人判定節	収束ループ最終報告での残項目表示
test-plan	機械判定節	テスト計画の完了基準との突合
pr-create	人判定節	PR 本文のチェックリスト生成

この消費構造があるため、機械判定節のテーブル列構成・種別・条件の語彙は勝手に変えない （references/template.md の「機械パース契約」）。

起動

/def-done（引数なし）で呼び出される。起動したら最初に docs/dev/definition-of-done.md の存在を確認し、モードを分岐する。

• 無い → 作成モード（手順 A）
• 有る → 改訂モード（手順 B）

プロジェクト側（CLAUDE.md / AGENTS.md 等）にドキュメント配置の規約があればそちらを 優先し、規約パスをユーザーに確認してから進める。

手順 A: 作成モード

A-1. 完成条件の洗い出し（対話）

「このプロジェクトで作業が完成したと言える条件は何か」をユーザーと対話で洗い出す。 以下の観点を叩き台として提示し、プロジェクトに当てはまるものだけを採る （当てはまらない観点を無理に埋めない）。

観点	問いの例
テスト	どのテストが green なら完成か。カバレッジの閾値はあるか
レビュー	コードレビューの通過は必須か。承認者の条件はあるか
ドキュメント	何を書けば完成か（README・仕様・ADR・変更履歴）
CI	どの CI check が success なら完成か
リリース手順	マイグレーション・設定反映・ロールバック手順の準備は要るか

観点は固定リストではない。プロジェクト固有の条件（法務確認・性能測定・ セキュリティスキャン等）が出たら追加する。

ただし成果物に載せる項目は二部合わせて最大 5 件。洗い出しで 6 件以上出たら、 そのまま全部を採らず、統合できる項目（例:「テスト green」と「カバレッジ閾値」を 1 つの CI check に寄せる）と、完成の定義から外して運用に回す項目をユーザーと 選別してから A-2 へ進む。「多く定義するほど品質が上がる」方向の誘導はしない。

事実は調査で埋める（原則）。CI check 名は .github/workflows/ を読んで実在する job 名・workflow 名を提示し、ユーザーに名前を思い出させない。ドキュメントの配置規約も リポジトリを読んで確認する。

A-2. 機械判定への振り分け（このスキルの核）

洗い出した各項目について、まず機械判定にできないかを検討する。 機械判定にできない理由が説明できる項目だけを人判定節へ回す。

判定手段は 2 種類のみ（references/template.md の語彙が正）:

• ci-check: 対象 = GitHub Actions の check 名、条件 = success
• artifact: 対象 = リポジトリ相対パス（{target} プレースホルダ可）、 条件 = exists または contains:<文字列>

振り分けの目安:

素の項目	振り分け
「テストが通っていること」	ci-check / 対象 = テスト job 名 / 条件 = success
「カバレッジ 80% 以上」	ci-check（閾値判定を CI 側に持たせる）。CI が無ければ人判定
「テスト完了レポートがあること」	artifact / docs/test/{target}/test-summary-report.md / exists
「総合判定が合格であること」	artifact / 同上 / contains:合格
「レビューで指摘が解消済み」	人判定（指摘の解消は意味判断）
「使い勝手に問題がない」	人判定（そもそも観測手段が無い）

機械化できるのに人判定へ流すのは本スキルの失敗である。判定手段が思いつかない項目は、 「どのファイルの何を見れば分かるか」をユーザーに一段掘って訊いてから振り分ける。

{target} プレースホルダは、機能ごとに変わるパス（docs/test/<対象>/... 等）に使う。 判定時に対象機能名へ展開される想定なので、機能名を直接書き込まない。

A-3. 書き出し

references/template.md の構成で docs/dev/definition-of-done.md を書き出す。

• ID は DOD-01 から連番で振る。
• 空欄セルを作らない。値が無い場合は - を明記する。
• 人判定節に該当項目が 1 件も無い場合は、空にせず （なし） と明記する （空節は「書き忘れ」と区別できないため）。
• テンプレの説明文（種別と条件の語彙の解説）は成果物にも残してよい。 機械パース契約を後から読む人のための情報である。

A-4. セルフ機械検査 → 完了宣言

手順 C へ進む。

手順 B: 改訂モード

B-1. 既存内容の提示

既存の docs/dev/definition-of-done.md を読み、機械判定節・人判定節の全項目を ID つきで提示する。同時に、改訂のきっかけになった情報（ユーザーの指示・ プロジェクトの変化）を確認する。

B-2. 追加・変更・削除の確定（対話）

項目ごとに追加・変更・削除を対話で確定する。変更対象の項目だけを扱い、 それ以外の項目には触れない。

AskUserQuestion で確認するのは ユーザーにしか決められない判断に限る （この項目を残すか外すか、機械判定へ移せるか等）。既存の CI check 名の実在確認など 調べれば分かることは、訊かずにリポジトリを読んで埋める。

改訂時も A-2 の振り分け方針は同じ。既存の人判定項目のうち、 その後の整備で機械判定へ移せるようになったものが無いかを毎回確認する （CI が増えた・成果物の規約が固まった等）。

B-3. 反映

• 既存の DOD-# は変更しない。追加項目は既存の最大値の次から追番する。
• 追加によって項目総数（機械判定 + 人判定）が 5 件を超える場合は、先に既存項目との 統合か外す項目の選定をユーザーと確定してから反映する（上限は増やさない）。
• 削除した項目の ID は欠番のまま残す（詰め直さない。既存の参照が壊れるため）。
• 冒頭の改訂日を更新する。
• 既存の記述スタイル・列構成は維持する。

B-4. セルフ機械検査 → 完了宣言

手順 C へ進む。

手順 C: 終了時セルフ機械検査と完了宣言

書き出し（A-3 / B-3）が済んだら、完了を宣言する前に必ず機械検査を実行する。

<SKILL_DIR>/scripts/dod-check.sh docs/dev/definition-of-done.md

<SKILL_DIR> はこのスキルの base directory（起動時に表示される絶対パス）。

• NG が 1 件でもあれば完了宣言しない。NG 内容を読んで成果物を直し、 再実行して NG ゼロにしてから閉じる。
• 検査は形式契約（セクション存在・ID 規約・語彙）のみを見る。 内容の妥当性（その条件が完成の定義として適切か）は対話で担保する領分であり、 検査の PASS は内容の妥当性を意味しない。

終了条件

以下を全て満たしたら 「完成の定義の作成（改訂）は完了」と明言して閉じる。 満たしていない項目があれば、何が残っているかを列挙して先へ進めない。

1. 完成条件の洗い出しがユーザーと合意済み（A-1 / B-2）。
2. 機械化できる項目が機械判定節に落ちており、人判定節には機械化できない項目だけが 残っている（A-2 / B-2）。
3. 項目総数が二部合わせて 5 件以内である（A-1 / B-3）。
4. docs/dev/definition-of-done.md が規約パスへ書き込み済み（A-3 / B-3）。
5. scripts/dod-check.sh が NG ゼロで PASS している（手順 C）。

用語

• 完成の定義（Definition of Done）: プロジェクト横断で「作業が完成した」と言える条件の集合。 機能ごとの有効性を見る受け入れ基準（acceptance criteria）とは別軸。
• 機械判定: 決定論スクリプトが人の解釈なしに真偽を出せる判定。本スキルでは ci-check / artifact の 2 種別に限定する。
• 人判定: 機械化できず、人間が確認して初めて真偽が決まる判定。
• 機械パース契約: 下流の決定論スクリプトが依存する成果物の書式上の取り決め。 テーブル列構成・種別・条件の語彙が該当する。