change-clarify

change-clarify

このスキルの機能

保留中の ChDR（ステータスが Discovered または Proposed）を確認し、その扱いを Accepted、Rejected、Deferred のいずれかに決定します。

これは、Change Decision Record の品質ゲートです。履歴から推測された決定をプロジェクトのメモリに登録し、team-boot によって今後のセッションに挿入する前の、人間による確認ポイントです。

• 推測された決定が、引用されたコミット SHA／課題 URL によって裏付けられていることを検証します（出所の確認 — コンテキスト汚染を防ぐ安全装置）
• 推測された根拠の信頼度を確認し、信頼度の低い主張や裏付けのない主張にフラグを立てます
• 課題リンクの有効性と、取得した課題の要約が正確であること（原文の丸写しではないこと）を確認します
• 確認できた場合は、Consequences（リバート／修正の連鎖）が記録されていることを確認します
• {REPO_ROOT}/.adlc/drafts/chdr/ChDR-{NNN}.md の ChDR ステータスを更新します
• {REPO_ROOT}/.adlc/drafts/chdr/chdr.md のインデックスを再生成します

これは対話型コマンドです。 各やり取りで ChDR を必ず1件だけ提示し、ユーザーの入力を待ってください。

使用するタイミング

• /change-init の後：履歴から抽出された ChDR を検証してから昇格させます
• 定期的なレビュー：古くなった保留中の ChDR を整理します

使用しないタイミング

• 保留中の ChDR がない場合：ステータスが Discovered／Proposed の ChDR がなければ、確認するものはありません
• CDR のレビュー：/team-levelup を使用してください（CDR と ChDR は別種の記録で、それぞれ独立したゲートがあります）
• 直接編集する場合：レビューのワークフローを迂回するために、このスキルを使用しないでください

プロセス

ユーザー入力

$ARGUMENTS

入力が空でない場合は、先に進む前にユーザー入力を必ず考慮してください。

ユーザー入力の例：

• "ChDR-001 ChDR-003" — 指定した ChDR に絞って確認します
• "all" — 保留中の ChDR をすべて確認します
• 空の入力：ステータスが "Discovered" または "Proposed" の ChDR をすべて確認します

フラグ

• --all：保留中の ChDR をすべて確認します（空の入力と同じです）
• --limit N：1セッションあたりの確認件数を N 件に制限します（デフォルト：5）

役割とコンテキスト

履歴から推測された決定を確認する Change Validator として行動してください。チーム全体のパターンを検証する CDR の確認とは異なり、重視するのは証拠の忠実性です。

• 決定は引用されたコミットから実際に推測できるものでしょうか。それともエージェントが作り上げたものでしょうか。
• 信頼度は正直に設定されていますか（簡潔なコミットメッセージで課題リンクもないのに信頼度が HIGH の主張は疑わしいものです）。
• 課題の要約は正確で、機密情報の詳細をそのまま漏らしていませんか。
• リバート／修正の連鎖が存在する場合、それらは記録されていますか（最も価値の高い内容です）。

ChDR 品質チェックリスト

各 ChDR には次の項目が必要です。

• ### Context に、変更が行われた理由（課題の要約またはコミットメッセージ）が記載されている
• ### Decision に、推測された決定と信頼度が記載されている
• Decision のすべての主張に SHA または課題 URL が引用されている（出所の確認 — 必須）
• ### Consequences（リバート／修正の連鎖、または「確認できたものなし」と明記）
• ### Evidence に具体的な SHA、ファイル、課題リンクが記載されている
• 課題の要約はそのまま貼り付けず、言い換えられている（セキュリティ）
• ステータスが正確である

概要

1. 保留中の ChDR を読み込む（フェーズ 1）：ステータスが Discovered／Proposed の ChDR ファイルを解析します
2. 事前検証（フェーズ 2）：必須セクションがない ChDR、または出所が示されていない Decision の主張を含む ChDR をスキップします
3. 不足点の特定（フェーズ 3）：確認が必要な項目を一覧表示します
4. 順次確認（フェーズ 4）：各やり取りで ChDR を1件ずつ確認します
5. ChDR の更新（フェーズ 5）：判断のたびにステータスと確認メタデータを書き込みます
6. インデックスの再生成（フェーズ 6）：chdr.md を更新します
7. 要約（フェーズ 7）：結果を提示します

実行手順

フェーズ 1：保留中の ChDR を読み込む

セットアップスクリプトを実行します。

scripts/bash/setup-change-clarify.sh

すべての {REPO_ROOT}/.adlc/drafts/chdr/ChDR-*.md ファイルを読み込み、次の条件で絞り込みます。

• 含める：### Status: **Discovered** または ### Status: **Proposed**
• スキップ：### Status: **Accepted**、**Rejected**、**Published**、**Deprecated**

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

1. REPO_ROOT — cwd から上位にたどって .adlc/ を探すか、git rev-parse --show-toplevel を実行します。
2. CHDR_DRAFTS_DIR — REPO_ROOT/.adlc/drafts/chdr
3. PENDING_COUNT — Discovered/Proposed のステータスが設定されたファイル数を数えます。

保留中の ChDR がない場合：

No pending ChDRs found.
Run /change-init to mine git history first.

ステップ 0：簡易ドラフト形式を検出する

レビュー対象のドラフトが簡易ドラフトテンプレートを使用しているか確認します（フロントマターに type、evidence、source、revisit-when フィールドがあり、本文に正式テンプレートの全セクションが含まれず、## Rejected Alternatives／## Reason セクションがある場合）。

簡易形式の場合：

1. ドラフトに記録されたフィールド（Context、Decision、Rejected Alternatives、Reason）を読み取ります。
2. 正式な完全版テンプレートに変換します。
   • ADR：Decision Drivers、Considered Options、Pros/Cons、Constitution Alignment、Related ADRs を含む完全な MADR 形式
   • PDR：Market Forces、Consequences、Alternatives Considered、Links を含む完全な PDR 形式
   • ChDR：Issue Links、Commits、Consequences、Evidence を含む完全な ChDR 形式
   • CDR：Context Type、Target Module、Descriptor、Evidence を含む完全な CDR 形式
   • EVAL：Error Analysis、Pass/Fail Examples、Implementation Notes を含む完全な評価形式
3. セッションのコンテキストから情報を補います（簡易ドラフトで省略された可能性のある詳細を追加します）。
4. 情報を補ったドラフトを提示してレビューします。

すでに完全な形式の場合は、通常のレビューに進みます。

フェーズ 2：事前検証

保留中の各 ChDR について、必須セクションを確認します。

• ### Context
• ### Decision（信頼度を示すマーカーが 1 つ以上あること）
• ### Consequences
• ### Evidence
• 出典情報：### Decision 内の重要な文すべてが SHA（\b[0-9a-f]{7,40}\b）または URL（https?://）を参照していること

無効な ChDR はスキップし、次のように報告します。

## Skipped ChDRs

| ChDR | Issue | Action |
|---|---|---|
| ChDR-XXX | Decision claims lack SHA/URL provenance | Re-run /change-init or add evidence manually |

フェーズ 3：ギャップの特定

ギャップレポートを生成します。

## ChDR Clarification Report

| ChDR | Title | Gap Type | Severity |
|---|---|---|---|
| ChDR-001 | [Title] | Low-confidence decision | MEDIUM |
| ChDR-002 | [Title] | Issue summary too verbose | LOW |

ギャップの種類：

• 信頼度の低い判断：判断に LOW confidence と記載されている — 却下または保留を検討します
• 出典のない主張：SHA/URL を含まない Decision の文（フェーズ 2 で検出されるはずです）
• Issue の要約が冗長：言い換えずにそのまま貼り付けられている（セキュリティ上の問題）
• 結果の記載漏れ：観測期間内にリバートが確認されているにもかかわらず、Consequences セクションが空
• 古い情報：クラスターのコミットが後からリバートされた（判断が覆された — 却下またはステータスの変更を検討します）

フェーズ 4：順次確認

重要：各やり取りで提示する ChDR は必ず 1 件だけにしてください。次のことは禁止します。

• 複数の ChDR をまとめて提示する
• アクションを自動選択する
• ユーザーの明示的な入力なしに先へ進む
• 一度に複数の質問をする

セッション上限：セッションごとの ChDR はデフォルトで 5 件です。ユーザーは「done」と入力して早期終了できます。

各 ChDR について：

## ChDR-{ID}: {Title}

**Status**: {status}
**Issue Links**: {links or "none"}
**Commits**: {sha list}

### Current Content

**Context**:
{context}

**Decision** (confidence: {level}):
{decision}

**Consequences**:
{consequences}

**Evidence**:
{evidence}

### Choose Action

| Option | Action |
|---|---|
| A | **Accept** — Approve for promotion to memory |
| B | **Reject** — Decline with reason |
| C | **Defer** — Skip for now, keep pending |
| D | **Accept all remaining** — Accept this ChDR and all pending ChDRs without further review |

Reply with your choice (A/B/C/D).

先に進む前にユーザーの入力を待ちます。

アクション A：承認

ステータスを ### Status: **Accepted** に更新します。確認メタデータを追加します。

### Clarification

- **Date**: [YYYY-MM-DD]
- **Action**: Accepted
- **Rationale**: [summary of review]

アクション D：残りをすべて承認

現在の ChDR を承認し（アクション A）、続いて保留中の残りの各 ChDR のステータスを ### Status: **Accepted** に更新し、一括メタデータを付与します。ChDR ごとの提示は省略します。フェーズ 6 に進みます。

アクション B：却下

理由を尋ねます。

### Decision: Reject

| Option | Reason |
|---|---|
| A | Decision was reversed (later reverted) |
| B | Inferred rationale unsupported by evidence |
| C | Project-specific / not worth recording |
| D | Duplicate of an existing ChDR or ADR |

Reply with your choice.

理由を付けてステータスを ### Status: **Rejected** に更新します。

アクション C：保留

ステータスはそのままにします。次のメモを追加します。

### Clarification

- **Date**: [YYYY-MM-DD]
- **Action**: Deferred
- **Reason**: [need more context / waiting on team / low priority]

フェーズ 5：ChDR ファイルを更新する

各 ChDR のやり取りの後、直ちにファイルを更新します。最後にまとめて更新してはいけません。

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

すべての ChDR-*.md ファイルを列挙し、1 行フィールド（### Status:、### Date:、### Issue Links:、### Commits:、### Descriptor:）から Markdown テーブルを作成して、{REPO_ROOT}/.adlc/drafts/chdr/chdr.md を再生成します。

フェーズ 7：要約

## Change-Clarify Summary

**ChDRs Reviewed**: N
**Accepted**: N
**Rejected**: N
**Deferred**: N

### Accepted (Ready for Promotion)

| ChDR | Title |
|---|---|
| ChDR-001 | [Title] |

### Rejected

| ChDR | Reason |
|---|---|
| ChDR-003 | Decision was reversed (later reverted) |

### Deferred

| ChDR | Title |
|---|---|
| ChDR-004 | [Title] |

### Next Steps

1. **Accepted**: Run `/change-publish` to promote to `docs/adlc/memory/chdr/`
2. **Deferred**: will appear in next clarify session
3. **Remaining**: run `/change-clarify` again to continue

主なルール

1件ずつ

• 各応答で提示する ChDR は必ず1件だけにします
• 各応答で質問するのは必ず1つだけにします
• 次に進む前にユーザーの入力を待ちます

即時書き込み

• 判断のたびに ChDR ファイルを更新します
• セッション終了後にインデックスを再生成します

自動承認なし

• ユーザーが明示的に選択しない限り、承認も却下もしません
• ユーザーの希望を推測しません

出典情報を必須条件とする

• SHA/URL の出典情報がない判断の主張は、データ汚染のリスクがあるため、却下するか、承認前に証拠を求めます
• 証拠が十分であれば、信頼度が LOW の判断は承認してもかまいません。証拠がない場合、信頼度が HIGH の判断は承認できません

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

/change-clarify の後

いずれかの ChDR が承認された場合は、/change-publish に引き継ぎます。

{
  "command": "clarify",
  "accepted": ["ChDR-001", "ChDR-002"],
  "rejected": ["ChDR-003"],
  "deferred": ["ChDR-004"]
}

Clarify フローの完了

[Pending ChDRs exist]
    ↓
/change-clarify
    ↓
[One ChDR at a time] → Accept / Reject / Defer
    ↓
[Run /change-publish] → Promote accepted ChDRs to docs/adlc/memory/chdr/

次のステップ

ChDR を承認した後、/change-publish を実行してプロジェクトのメモリに反映し、起動時に参照する chdr.md インデックスを再生成します。

検証

• 確認したすべての ChDR ファイルが、新しいステータスと明確化メタデータで更新されています。
• chdr.md のドラフトインデックスが再生成されています。
• 承認済みの ChDR は /change-publish で処理できる状態です。
• ユーザーの入力なしに自動承認または自動却下された ChDR はありません。
• 承認済みの ChDR では、判断の主張すべてに出典情報があります。

コンテキスト

$ARGUMENTS