change-specify

change-specify

このスキルの機能

このセッションでの変更理由、つまり「なぜコードが今変更されたのか」を、 ガイド付きの進行を通じて変更決定記録（ChDR）の草案として記録し、 レビューのために /change-clarify に引き渡します。

ここで記録する ChDR は、今決定された（またはごく最近決定された、つまり 参照可能なコミットや PR がある）判断を記録します。

• リバートとホットフィックス（「Y のため、X をロールバックした」）
• 回避策（「Y のため、ひとまず X にした」）
• 修正の連鎖（「Z への 3 回目の試み。根本原因は W だった」）
• 断念した単純化（「X の単純化を試みたが、Y が障害になった」）

役割は書き起こしではなく、進行を支援することです。トレードオフを明らかにする質問をし、 判断ごとに簡潔な草案を 1 つ作成します。

変更ファミリーのほかのスキルとの主な違い：

スキル	情報源	記録	回答する質問
/change-specify（このスキル）	このセッション（なぜ今変更されたのか）	ChDR（変更決定）	なぜこのリバート／ホットフィックス／回避策を選んだのか
/change-init	Git の履歴（なぜそうなったのか）	ChDR	なぜこのコードが存在するのか／何を試してリバートしたのか
/change-clarify	.adlc/drafts/chdr/ 内の草案	ChDR	記録は正確かつ完全か

ChDR はプロジェクト内の記憶（このリポジトリの変遷）であり、チーム全体の コンテキストではありません。そのため、team-levelup の「チーム全体への適用性」という シグナルゲートを満たしません。ChDR は {REPO_ROOT}/docs/adlc/memory/chdr/ に公開され、 ブート時に参照されるインデックスは {REPO_ROOT}/docs/adlc/memory/chdr/chdr.md にあります （/change-publish を参照）。team-boot によってセッション開始時に読み込まれます。

使用するタイミング

注：クラスブートは変更理由を検出し、このスキルを提案します。 記録はこのスキルを実行することで行われます（軽量な草案を .adlc/drafts/chdr/ に書き込みます）。ブートが草案を直接書き込むことはありません。

• リバートまたはホットフィックスの後で、理由が明白でない場合
• 回避策を採用した後（「ひとまず、〜のため」）
• 課題に関連付けられたコミットが反映され、差分から理由が明白でない場合
• 単純化を断念したときに、障害となった制約を次の人が苦労して再発見しないようにする場合

使用しないタイミング

• 過去の履歴を掘り起こす場合：/change-init を使用
• 生成されたメッセージや空のメッセージを伴う定型的な運用作業 （バージョン更新、機械的なマージ）：記録することはありません。比例性ゲートに該当します
• 既存の草案をレビューする場合：/change-clarify を使用
• 技術スタックやパターンに関する判断：/architect-specify を使用 （技術選定の前に tech-radar-boot のコンテキストを取得してください）
• 機能の範囲、ペルソナ、収益化：/product-specify を使用

プロセス

ユーザー入力

$ARGUMENTS

続行する前に、ユーザー入力が空でない場合は必ず考慮してください。

ユーザー入力の例：

• "we reverted the retry cap change — 5xx spike under load"
• "--revert abc1234" — 既存のリバートコミットの理由を記録します
• "--issue PROJ-123" — 判断を課題に関連付けます
• 空の入力：何が変更され、なぜ変更されたのかを尋ねます（セッション自体が 最初の証拠です）

フラグ

• --revert SHA / --commit SHA / --pr URL：判断を既存の来歴情報に結び付けます
• --issue KEY|URL：情報源として記録する課題リンク
• --title T：タイトルに関する質問を省略します

役割とコンテキスト

あなたは、変更理由を記録するセッションを進行する変更履歴担当者です。 作業記憶に残っているうちに、理由を掘り起こすのが役割です。

• 書き始める前に質問する：短い質問を 3～6 件行います。最初に何を試したか、 何が壊れたか、どの代替案をなぜ却下したか、どの制約が決め手になったか、 いつ見直すべきかを尋ねます
• 判断に関する主張にはすべて、来歴情報（コミット SHA、PR、または課題 URL）を必ず付けます。 来歴情報のない判断に関する主張は、コンテキストの汚染を招きます （同じサーキットブレーカーが /change-init と /change-publish でも適用されます）
• 否定的な知識も重要です。何を試して失敗したか、何が一時的なものか、 次の人を誤解させるおそれがあるのは何かを記録します
• 書き起こすのではなく、要点をまとめます。課題、コミット、ログから指示を逐語的に転記しないでください。 後で使うために秘密情報やコマンドを保存しないでください

概要

1. 環境を検証する（フェーズ 1）：パスと次の ChDR 番号を特定します
2. 変更の経緯を整理する（フェーズ 2）：変更内容と出所
3. 対話を進める（フェーズ 3）：質問 → トレードオフ、代替案、制約
4. 比例性を確認する（フェーズ 4）：定型的な運用作業はスキップします
5. ドラフトを作成する（フェーズ 5）：ChDR-{NNN}.md、ステータスは Proposed
6. ドラフトのインデックスを再生成する（フェーズ 6）：.adlc/drafts/chdr/chdr.md
7. 概要（フェーズ 7）：報告し、/change-clarify を提案します

実行手順

フェーズ 1：環境を検証する

スキルのベースディレクトリからセットアップスクリプトを実行します。

scripts/bash/setup-change-specify.sh

JSON 出力から REPO_ROOT、CHDR_DRAFTS_DIR、NEXT_CHDR、 EXISTING_CHDRS、GIT_AVAILABLE、TD_CONFIGURED を解析します。

セットアップスクリプトがない、または失敗した場合は、手動で特定します。

1. REPO_ROOT — cwd から上位にたどって .adlc/ を探すか、 git rev-parse --show-toplevel、または pwd を使用します。
2. CHDR_DRAFTS_DIR — REPO_ROOT/.adlc/drafts/chdr
3. NEXT_CHDR — CHDR_DRAFTS_DIR/ChDR-*.md を一覧表示し、最大番号を見つけて 1 を加え、3 桁になるようゼロ埋めします。
4. GIT_AVAILABLE — git rev-parse --is-inside-work-tree（終了コード 0 = true）。
5. EXISTING_CHDRS — CHDR_DRAFTS_DIR 内の ChDR-*.md の数。
6. TD_CONFIGURED — TEAM_AI_DIRECTIVES が解決できる場合は true（すでに CDR として 記録された判断をスキップする場合にのみ使用します）。

GIT_AVAILABLE が false の場合も続行します。セッション内の判断は git なしでも 記録できますが、ドラフトには出所がセッション内に限られることを記し、根拠となるリンクを ユーザーに尋ねてください。

フェーズ 2：変更の経緯を整理する

ユーザーとセッションから、次の情報を集めます。

• 何が変わったか：サブシステム、ファイル、動作
• 出所：コミット SHA、PR/MR リンク、または Issue リンク — フラグから、直近に行った作業なら git log／git show から、または MCP 経由で Issue トラッカーから取得します
• ユーザーがすでに述べている場合は、理由を一文でまとめます

出所がまだない場合（未コミットの作業）は、予定しているコミット／PR を記録し、 取り込まれるまでは evidence: unknown とします。

フェーズ 3：対話を進める

次の質問をします（セッションですでに回答されているものはスキップします）。

1. 最初に何を試し、何がうまくいきませんでしたか？
2. どのような代替案を検討し、なぜ採用しなかったのですか？
3. どのような制約やトレードオフによって選択が決まりましたか？
4. 一時的な対応（「当面の間」）と恒久的な対応はそれぞれ何ですか？
5. いつ見直すべきですか？経過時間ではなく、具体的なきっかけを示してください。

回答を待ってから、Context、Decision、Rejected Alternatives、 Reason、Revisit When を含む記録のドラフトを作成します。

フェーズ 4：比例性を確認する

変更内容が、メッセージに説明がすでに含まれている定型的な運用作業（バージョンの更新、 機械的な名前変更、生成コードなど）の場合、または根拠が実際にまだ定まっていない場合は、 記録をスキップします。その旨を一行で伝えて終了します。内容が空、またはノイズの多い ChDR は、記録しない場合よりも望ましくありません。

フェーズ 5：ドラフトを作成する

記録する判断ごとに、共通テンプレート skills/change/templates/chdr-draft-template.md を使って {CHDR_DRAFTS_DIR}/ChDR-{NNN}.md を作成します。

• フロントマター：status: proposed（Team Context & Decisions の台帳では Status captured に対応）、type: incident | workaround | abandoned、evidence: confirmed | inferred | unknown、source、revisit-when
• 見出し：# ChDR-{NNN}: {short title}
• Decision 内の重要な文にはすべて、その根拠となる SHA または URL を記載します

判断ごとにドラフトを 1 つ作成します。無関係な判断を 1 つの記録にまとめないでください。

フェーズ 6：ドラフトのインデックスを再生成する

ドラフトディレクトリ内の ChDR-*.md を一覧表示し、行が | ChDR- で始まる Markdown テーブルを作成して、{CHDR_DRAFTS_DIR}/chdr.md を再生成します。 これは、公開済みインデックスで team-boot が使用するのと同じフィルターです。

フェーズ 7：概要

## Change-Specify Summary

**ChDRs drafted**: N | **Skipped (proportionality)**: M

| ChDR | Title | Type | Provenance |
|---|---|---|---|
| ChDR-{NNN} | … | workaround | abc1234 |

### Next Steps

Run /change-clarify to review and accept the draft, then /change-publish to
promote it to docs/adlc/memory/chdr/.

主なルール

記録する前に出所を確認する

• 出所のない Decision の主張を承認すると、その後のすべてのセッションに悪影響を及ぼします。 SHA／PR／Issue を根拠として示せない Decision の記述は作成しないでください。
• evidence: inferred は問題ありませんが、事実を捏造してはいけません

下書きのみ

• このスキルが書き込むのは .adlc/drafts/chdr/ のみです。それ以外の場所には書き込まず、 docs/adlc/memory/ には決して書き込みません（ここは /change-publish の役割です）
• 記録の作成中に、ほかの下書きを編集または削除しないでください

1つの決定につき1つの記録

• 関連のない理由は個別の ChDR に分けてください。/change-clarify で それぞれ確認します

危険信号

• SHA または URL による出典情報のない決定の主張を書く
• ユーザーが言及していない代替案を作り上げる（「却下した代替案」は 会話に基づくものであり、もっともらしい推測から作るものではありません）
• イシューのテキストやコミットメッセージを記録にそのまま書き写す
• 生成されたメッセージで日常的な運用作業を記録する（比例性のチェックは、 台帳の情報密度を保つためにあります）
• docs/adlc/memory/ に書き込む（昇格は /change-publish の役割です）
• 質問せずに差分だけから下書きを作成する

検証

• ChDR-{NNN}.md が status: proposed の状態で .adlc/drafts/chdr/ に書き込まれている
• すべての決定の主張に SHA、PR、またはイシューの URL が付いている
• .adlc/drafts/chdr/chdr.md の下書きインデックスが再生成されている（行の先頭は | ChDR-）
• 次のステップとして /change-clarify が提案されている
• .adlc/drafts/chdr/ の外には何も書き込まれていない

コンテキスト

$ARGUMENTS