change-init

change-init

このスキルの機能

git の履歴からChange Decision Record（ChDR）、つまりコードが現在の形になった理由を掘り起こし、人によるレビュー用のドラフト記録を作成します。

ChDR は過去に行われた決定を記録します。その決定は、コミットとリンクされた課題トラッカーにしか残っていないものです。

• git log の一定範囲をスキャンし、課題トラッカーを参照するコミットメッセージ（JIRA キー、GitHub／GitLab の #NNN、MR の !NNN、課題 URL）を探します
• 同じ課題キーを共有するコミットを、ひとつの変更ストーリーにまとめます
• 要件レベルのコンテキストを得るため、課題のタイトル／本文を可能な範囲で取得します（GitLab は MCP 経由、GitHub は gh 経由、それ以外はリンクのみ）
• 差分の概要から決定を推測し、結果（リバート、後続の修正チェーンなど、他の場所ではほとんど記録されないネガティブな知見）を記録します
• ステータスをDiscoveredとして、{REPO_ROOT}/.adlc/drafts/chdr/ に ChDR-{NNN}.md を書き込みます
• {REPO_ROOT}/.adlc/drafts/chdr/chdr.md のインデックスを再生成します

team-levelup 系スキルとの主な違い：

スキル	情報源	記録	答える問い
/team-init	現在のコード（現在の状態）	CDR（Context Directive）	再利用できるパターンは何か
/team-levelup	現在のセッション	CDR	このセッションで何を学んだか
/change-specify	このセッション（今、なぜ変更されたか）	ChDR（Change Decision）	なぜこのリバート／ホットフィックス／回避策を選んだのか
/change-init（このスキル）	git の履歴（なぜこの状態になったか）	ChDR（Change Decision）	なぜこのコードが存在するのか／何を試してリバートしたのか

ChDR はプロジェクト固有のメモリ（このリポジトリの変遷）であり、チーム全体のコンテキストではありません。そのため、team-levelup の「チーム全体への適用可能性」という判定基準を満たしません。ChDR は {REPO_ROOT}/docs/adlc/memory/chdr/ に公開され（/change-publish を参照）、インデックスはセッション開始時に team-boot によって注入されます。

使用するタイミング

注：Class boots は、セッション中に変更理由を検出すると /change-specify（軽量なドラフトを .adlc/drafts/ に書き込むスキル）を提案します。 このスキルは、対話形式での詳細な調査、つまり履歴のガイド付き調査、変更ストーリーのグループ化、文書化前の理由の復元に使用します。

• 既存コードベースへのオンボーディング：誰もドキュメントを書かずに、エージェントにプロジェクトのメモリを提供する
• 不慣れなコードをリファクタリングする前：古いコミットとチケットにしか残っていない制約、つまりチェスタトンの柵を明らかにする
• 失われた理由の復元：ADR は作成されていないものの、コミットと課題が残っている場合
• インシデント後の学習：リバート／修正チェーンを主要な成果として記録する

使用しないタイミング

• グリーンフィールド／履歴がない場合：調査対象がありません
• 現在のパターンを文書化する場合：/team-init を使用します（現在の状態）
• このセッションで得た学びを記録する場合：/team-levelup を使用します
• このセッションでの変更理由を記録する場合：/change-specify を使用します
• 未処理の ChDR がすでにある場合：まず /change-clarify を実行してレビューします

プロセス

ユーザー入力

$ARGUMENTS

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

ユーザー入力の例：

• "--since 6months" — スキャン範囲を制限します
• "--tracker gitlab" — トラッカーの種類を指定します（デフォルトでは自動判定）
• "--no-fetch" — 課題リンクのみを記録し、課題本文は取得しません
• "--include-unlinked" — 関連性の高い未リンクのコミット（リバートや大規模な横断的差分）も対象にします
• "src/payments" — 対象をパスで制限します
• 空の入力：リポジトリ全体の直近 500 件のコミットをスキャンし、トラッカーを自動判定します

フラグ

• --since DATE / --until DATE / --max-count N（デフォルト 500）：git log の対象範囲を指定します
• --path PATH：対象をパス指定で制限します
• --tracker gitlab|github|jira|auto（デフォルト auto）：課題トラッカーとの連携を指定します
• --no-fetch：課題リンクの検出と記録のみを行い、本文は取得しません
• --include-unlinked：関連性の高い未リンクのコミット（リバートや、3 つ以上のサブシステムに及ぶ差分）もグループ化します
• --limit N（デフォルト 20）：生成する ChDR の数を制限します
• --resume：前回中断した状態から再開します

役割と背景

あなたは、コードがその形になった「理由」を明らかにするコンテキスト考古学者です。仕事は証拠から推論することであり、創作することではありません。

• Decision の主張にはすべて、推論の根拠となったコミット SHA および／または issue URL を必ず記載してください（出典の明記は必須です。根拠のない推論による理由付けはコンテキスト汚染であり、理由付けがないことよりも悪質です）。
• Decision ごとに確信度（HIGH／MEDIUM／LOW）を記録してください。
• 不明な点は明示してください（「選択理由は不明 — コミットメッセージが簡潔で、関連する issue もありません」）。
• リバートや後続の修正チェーンは、最も価値の高い情報です。これらは否定的な知見（「X を試したところ、Y が壊れた」）であり、ほかではほとんど記録されていません。

概要

1. 環境の検証（フェーズ 1）：git リポジトリ、パスの解決、次の ChDR 番号
2. 対象期間のスキャン（フェーズ 2）：期間を指定した git log
3. Issue リンクの検出（フェーズ 3）：コミットメッセージに対する正規表現
4. 変更ストーリーへの分類（フェーズ 4）：issue キーごとにコミットをグループ化
5. 可能な範囲での Issue 取得（フェーズ 5）：トラッカーの内容を取得（失敗時も適切に続行）
6. リバート／修正チェーンの検出（フェーズ 6）：否定的な知見を第一級の情報として扱う
7. スコアリングと優先順位付け（フェーズ 7）：変更されたサブシステム、差分の規模、チェーン
8. ChDR の生成（フェーズ 8）：ドラフトとインデックスを作成
9. 出力（フェーズ 9）：リンク率の指標を含む概要

実行手順

フェーズ 1：環境の検証

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

scripts/bash/setup-change-init.sh

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

セットアップスクリプトが利用できない、または失敗した場合は、手動で解決します。

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. TD_CONFIGURED — TEAM_AI_DIRECTIVES が解決される場合は true です（CDR としてすでに記録されている重複した Decision を除外する場合にのみ使用します）。

GIT_AVAILABLE が false の場合：

Not a git repository — change-init has nothing to mine.
Run /team-init to scan current code instead.

正常に終了します（空のドラフトは作成しません）。

フェーズ 2：対象期間のスキャン

git log --pretty=format:'%H%x09%an%x09%ad%x09%s%n%b' --date=short \
  ${SINCE:+--since="$SINCE"} ${UNTIL:+--until="$UNTIL"} --max-count="${MAX_COUNT:-500}" \
  ${PATHSPEC:+-- "$PATHSPEC"} 2>/dev/null

コミットごとに、SHA、作成者、日付、件名、本文、変更されたファイル（git show --stat --name-only）、およびサブシステム（変更されたファイルのトップレベルディレクトリ）を記録します。

フェーズ 3：Issue リンクの検出

各コミットメッセージ（件名 + 本文）に対して、次の正規表現を組み合わせて適用します。

パターン	トラッカー	例
\b[A-Z][A-Z0-9]+-\d+\b	JIRA	PROJ-123
(?<!\w)#\d+\b	GitHub/GitLab の issue	#123
\b!\d+\b	GitLab MR / Gerrit	!42
`https?://\S+/(issues	pull	merge_requests

トラッカーの種類は、git remote get-url origin と検出されたリンクの形式（gitlab.com / github.com / atlassian.net）から自動的に推定します。--tracker を指定すると上書きされます。

リンクが検出されなかったコミットはリンクなしとして扱います。--include-unlinked が指定されていない限りスキップします。指定されている場合も、リバートであるか、3 つ以上のサブシステムに変更があるコミットのみを保持します。

フェーズ 4：変更ストーリーへの分類

コミットを issue キーごとにグループ化します。1 つの issue キーにつき、候補となる ChDR を 1 つ作成します。URL のみのリンクは issue 番号に正規化します。クラスター内の件名と本文のテキストを結合し、根拠となる情報のコーパスとして使用します。

Phase 5: Issue のベストエフォート取得

各クラスターについて、変更のきっかけとなった要件を把握するため、Issue のタイトルと本文の要約を Context として取得します。ベストエフォートで実施し、処理をブロックすることはありません。

• GitLab：設定済みの GitLab MCP ツール（プロジェクトと iid を指定した gitlab_get_issue）を使用します。利用できない場合は、glab issue view を試します。
• GitHub：gh が認証済みの場合は、gh issue view <num> --json title,body を実行します。
• JIRA / 到達不可：リンクのみとし、URL を根拠として記録します。Context はコミットメッセージのみから作成します。

--no-fetch を指定すると、このフェーズ全体をスキップします。取得に失敗しても、コミットメッセージに基づく Context に切り替えるだけで、中断しません。

セキュリティ：Issue の本文には機密情報が含まれる場合があります。要件は1～3文で要約し、生の Issue 本文を ChDR にそのまま貼り付けないでください。昇格の前に、ヒューマンゲート（/change-clarify）で確認します。

Phase 6: Revert／Fix チェーンの検出（第一級の対象）

Issue との関連付けに関係なく、対象期間全体を調べます。

• Revert：git log --grep='^Revert "' --pretty=format:'%H %s' と git log --grep='revert' -i を実行します。取り消された元のコミットは、否定的な知識として記録します。
• Fix チェーン：件名が fix(?!ed)?\b または hotfix に一致し、対象期間内の以前のコミットと同じファイルを変更しているコミットを検出します。これは回帰を修正する後続変更です。元の変更と修正のペアを、結果として記録します。

Issue に紐づいていない Revert や Fix チェーンも、--include-unlinked を指定すると記録されます（紐づいていないシグナルの中で最も価値が高いためです）。Revert／Fix チェーンが Issue に紐づくクラスターに属する場合は、そのクラスターの ### Consequences に追加します。

Phase 7: スコアリングと優先順位付け

各候補をスコアリングします（0.0～1.0）。

• 変更されたサブシステム（複数にまたがる場合は高く評価）
• 差分のサイズ（大きいほど高く評価。ただし上限あり）
• Revert／Fix チェーンの結果がある（加点 — 否定的な知識）
• Issue の Context を取得できている（加点 — より豊富な根拠）
• 新しさ（控えめに加点）

スコアの降順に並べ、上位 --limit 件（デフォルトは20件）を選びます。スコアが0.2未満の候補（軽微なもの）はスキップします。

Phase 8: ChDR の生成

選択した各変更ストーリーについて、{CHDR_DRAFTS_DIR}/ChDR-{NNN}.md を作成します。

## ChDR-NNN: [Title — from issue title or commit subject]

### Status: **Discovered**

### Date: [YYYY-MM-DD of most recent commit in cluster]

### Source: Git history via /change-init

### Issue Links: [keys/URLs, or "none detected"]

### Commits: [sha list, abbreviated]

### Target Module: `docs/adlc/memory/chdr/[slug].md`

### Descriptor: One-line "when to consult this" summary for the chdr.md index.

### Context
[Why the change was made — issue title/body summary (1-3 sentences) + commit messages. Cite SHAs inline.]

### Decision
[What was decided/implemented — inferred from diffs. Mark confidence: HIGH/MEDIUM/LOW. Each claim cites its SHA/URL.]

### Consequences
[Reverts, follow-up fix chains, later modifications — negative knowledge. "None observed" if the cluster has no reversals.]

### Evidence
- `{sha}`: {commit subject}
- {file/path}: {what changed}
- {issue-url}: {title} (fetched | link-only)

ルール：

• すべての ### Decision の主張には、SHA または URL を根拠として記載します（出所情報 — コンテキスト汚染を防ぐ仕組みです）。
• 「理由不明」は許容され、創作するより望ましい表現です。
• Decision の主張には、必ず確信度を記載します。

次に、{CHDR_DRAFTS_DIR}/ChDR-*.md ファイルをすべて列挙し、それぞれの1行フィールドから Markdown テーブルを作成して、{CHDR_DRAFTS_DIR}/chdr.md のインデックスを再生成します。

# Change Decision Records (Drafts)

## ChDR Index

| ID | Status | Date | Issues | Commits | Descriptor |
|----|--------|------|--------|---------|------------|
| ChDR-001 | Discovered | 2026-08-16 | PROJ-123 | abc1234 | Why payments retries are capped at 3 |

**Stats**: N entries | Last Updated: YYYY-MM-DD

Phase 9: 概要の出力

## Change-Init Summary

- Scan window: [since/until or "last N commits"]
- Commits scanned: N
- Issue-linked commits: M (linkage rate: P%)
- Clusters formed: K
- Revert/fix chains detected: C
- ChDRs generated: N (capped at --limit)
- Output: `{REPO_ROOT}/.adlc/drafts/chdr/`

関連付け率は、コーパスの品質に関する目安です（調査によると、根拠の密度はチームの規律によって大きく異なり、Linux カーネルのような規律あるプロジェクトでは85～99％、それ以外ではかなり低くなります）。約30％を下回る場合は、次回の実行で --include-unlinked を指定することを提案してください。

主なルール

根拠に基づき、決して捏造しない

• コミットと Issue から推測できる決定のみを記録します。
• すべての Decision の主張に、具体的な SHA および／または Issue の URL を記載します。
• 確信度（HIGH／MEDIUM／LOW）を記載します。
• 「理由不明」は許容されます。捏造は許容されません。

非破壊

• 承認なしに既存の ChDR を上書きしないでください。
• 手動で追加された内容を保持してください。
• 同じ Issue キーの ChDR が既に存在する場合は、適切にマージしてください。

適切な縮退動作

• Git リポジトリではない場合 → 正常に終了し、空のドラフトを作成しません。
• トラッカーに到達できない場合 → リンクのみを根拠として処理を続行します。
• コミットメッセージが空または簡潔すぎる場合 → 差分と Issue の取得内容を使用します。どちらもない場合は、そのクラスターをスキップします。

拒否理由を捏造しない

• 推測した決定には、中立的な「検討した代替案」という表現を使用します。
• 「X が選ばれなかった理由は不明です」は許容されます。

ワークフローのガイダンスと移行

/change-init の後

必須：/change-clarify を実行して、検出された ChDR を検証します。

/change-init
    ↓
[Mine git history] → Detect issue links, cluster, infer decisions
    ↓
[Generate ChDRs] → Write to .adlc/drafts/chdr/ChDR-{NNN}.md (Discovered)
    ↓
[Run /change-clarify] → Validate and accept/reject ChDRs
    ↓
[Run /change-publish] → Promote accepted ChDRs to docs/adlc/memory/chdr/
    ↓
[team-boot] → Injects docs/adlc/memory/chdr/chdr.md index at next session start

次のステップ

init の完了後、/change-clarify を実行して、検出された ChDR を精査し、検証します。

検証

• ChDR が {REPO_ROOT}/.adlc/drafts/chdr/ChDR-{NNN}.md にステータス Discovered で書き込まれていること。
• 自動生成された chdr.md インデックスが {REPO_ROOT}/.adlc/drafts/chdr/ に存在すること。
• すべての ChDR の ### Decision の主張に、出典として少なくとも 1 つの SHA または issue URL が記載されていること。
• 対象期間に検出された Revert／fix チェーンが、### Consequences に記載されていること（または「None observed」）。
• リンケージ率の指標がサマリーに記載されていること。
• 明示的な承認なしに既存の ChDR が上書きされていないこと。

コンテキスト

$ARGUMENTS