levelup-clarify

levelup-clarify

このスキルの機能

保留中のCDR（ステータスがDiscoveredまたはProposed）をレビューし、今後の扱いをAccepted、Rejected、またはDeferredのいずれかに決定します。

これは、team-ai-directivesへのすべての貢献に対する品質ゲートです。

• パターンがプロジェクト固有ではなく、チーム全体に適用されることを検証します
• 既存のteam-ai-directivesと重複していないか確認します
• CDRに明確なコンテキスト、決定、根拠があることを確認します
• {REPO_ROOT}/.adlc/drafts/cdr/CDR-{NNN}.md内のCDRステータスを更新します
• {REPO_ROOT}/.adlc/drafts/cdr/cdr.mdのインデックスを再生成します

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

使用するタイミング

• /levelup-initの後：既存のコードベースで見つかったパターンを検証します
• /levelup-specifyの後：提案された機能の学びをレビューします
• /team-repairで競合が見つかった後：修復によって作成された競合CDRを解決します
• 定期レビュー：古い保留中のCDRを整理します

使用しないタイミング

• 保留中のCDRがない場合：ステータスがDiscovered/ProposedのCDRがなければ、確認するものはありません
• 直接編集する場合：レビューのワークフローを迂回するためにこのスキルを使用しないでください
• 定期的な健全性チェック：チームのAIディレクティブのメンテナンスには/team-repairを使用してください

プロセス

ユーザー入力

$ARGUMENTS

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

ユーザー入力の例：

• "CDR-001 CDR-003" — 特定のCDRに絞ります
• "rules" — ルールタイプのCDRのみを確認します
• "all" — 保留中のすべてのCDRを確認します
• 空の入力：ステータスが"Discovered"または"Proposed"のすべてのCDRを確認します

フラグ

• --all：保留中のすべてのCDRを確認します（空の入力と同じです）
• --type TYPE：コンテキストタイプで絞り込みます（rules、personas、examples、skills、constitution、evals）
• --limit N：セッションあたりの確認件数をN件に制限します（デフォルト：5）
• --no-evals-gate：evals回帰ゲートを無効にします（デフォルト：ゲートはON）

役割とコンテキスト

あなたは、見つかったパターンをレビューするコンテキストバリデーターとして対応します。役割は次のとおりです。

• パターンが現在も妥当であることを検証します
• 適用範囲（チーム全体かプロジェクト固有か）を明確にします
• 既存のteam-ai-directivesとの重複を確認します
• 対象を絞った質問を通じてCDRの内容を改善します

CDR品質チェックリスト

各CDRには以下が必要です。

• パターンを説明する明確なコンテキスト
• 明示的な決定の記述
• コードベースまたは機能から得られた根拠
• 対象モジュールのパスが適切な形式であること
• ステータスが正確であること
• 既存のディレクティブと競合していないこと
• チーム全体に適用可能であること
• 強制可能性が分類されていること：機械的（決定論的なチェック）か、判断を要するもの（コンテキストルール）か

概要

1. 保留中のCDRを読み込む（フェーズ1）：ステータスがDiscovered/ProposedのCDRファイルを解析します
2. 事前検証（フェーズ2）：必須セクションがないCDRをスキップします
3. evals回帰ゲート（フェーズ2a）：承認前に既存のゴールデンセットを実行します（デフォルトでON）
4. 強制可能性ゲート（フェーズ2b）：承認を提示する前に、機械的なものか判断を要するものかを分類します
5. 不足点の特定（フェーズ3）：確認が必要な点を列挙します
6. 順次確認（フェーズ4）：1回のやり取りにつきCDRを1件確認します
7. CDRを更新する（フェーズ5）：各決定の後、ステータスと確認メタデータを書き込みます
8. インデックスを再生成する（フェーズ6）：cdr.mdを更新します
9. 要約（フェーズ7）：結果を提示します

実行手順

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

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

scripts/bash/setup-levelup-clarify.sh

{REPO_ROOT}/.adlc/drafts/cdr/CDR-*.mdのすべてのファイルを読み込み、次のように絞り込みます。

• 対象：### Status: **Discovered**または### Status: **Proposed**
• スキップ：### Status: **Accepted**、**Rejected**、**Deprecated**

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

1. REPO_ROOT — cwdから上位にたどって.adlc/を探すか、git rev-parse --show-toplevelを実行します。
2. CDR_DRAFTS_DIR — REPO_ROOT/.adlc/drafts/cdr
3. PENDING_COUNT — grep -l '^### Status: \*\*(Discovered|Proposed)\*\*' CDR_DRAFTS_DIR/CDR-*.md | wc -l

ユーザーが特定のCDR IDまたはタイプを指定した場合は、それに応じて絞り込みます。

保留中のCDRがない場合：

No pending CDRs found.
Run /levelup-init or /levelup-specify to create CDRs 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：事前検証

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

• ### Context
• ### Decision
• ### Evidence
• ### Target Module

無効な CDR はスキップし、次の内容を報告します：

## Skipped CDRs

| CDR | Issue | Action |
|---|---|---|
| CDR-XXX | Missing Evidence | Add evidence and re-run clarify |

フェーズ 2a：評価の回帰ゲート

デフォルト：オン。 無効にするには --no-evals-gate を使用します。

評価用 CDR、または対応する評価がある指示 CDR をレビューする場合、既存のゴールデンセットを team-ai-directives/evals/ から実行し、この CDR を受け入れると既存の指示遵守テストが壊れるかどうかを確認します。

評価用 CDR の場合：評価の品質を検証します：

• すべてのケースに具体的な根拠への参照（セッションの説明またはコードファイルの行番号）がある
• 合否が二択である（曖昧なケースがない）
• 評価用 CDR が対応する指示 CDR を参照している
• 不合格ケースに修正内容（何をすべきだったか）が記載されている

対応する評価がある指示 CDR の場合：回帰チェックを実行します：

1. 既存のゴールデンセットを {TEAM_AI_DIRECTIVES}/evals/ から読み込みます
2. 既存のゴールデンセットがない場合 → ゲートをスキップします（回帰の可能性はありません）
3. 同じ指示領域のゴールデンセットが存在する場合：
   • 既存のゴールデンセットのケースを LLM 呼び出しでエージェントに対して実行します
   • この CDR を受け入れることで指示が変更される場合、既存の評価ケースが引き続き合格するか確認します
   • 新しい指示で既存の評価が不合格になる場合 → CDR を Blocked (Evals) としてマークします

ブロックされた CDR は保留中の状態のままとし、次の注記を付けます：

### Clarification

- **Date**: [YYYY-MM-DD]
- **Action**: Blocked (Evals)
- **Reason**: Accepting this CDR would break N existing goldenset cases in evals/{directive-id}/

次の内容を報告します：

## Evals Regression Gate

| CDR | Gate Result | Details |
|---|---|---|
| CDR-001 | PASS | No existing goldensets in scope |
| CDR-002 | BLOCKED | 3 existing cases would fail with modified rule |

フェーズ 2b：強制可能性ゲート

デフォルト：オン。 保留中のルール型 CDR ごとに、受け入れを提示する前に強制可能性を分類します。決定的なチェックを優先します（EVAL-010）：

分類	例	主な対応
機械的（固定パターン）	禁止 API、インポート形式、ファイル配置ルール、固定の構文パターン	決定的なチェック — ユニットテスト、バイナリー評価器、プリコミットフック、リンタールール、または CI ジョブ。最初に一度実装すれば、コンテキストルールによって毎回同じ判断を再導出する必要がなくなります
判断が必要	ファイル間の一貫性、「周囲のスタイルに合っている」こと、意図の理解が必要なもの	通常どおり、コンテキストルール（CDR）を使用

ルールを記述するより、チェックを構築することを優先します。 機械的なルールの CDR は、まずアクション P — チェックに昇格（フェーズ 4）で提示します。チェックのそばに見つけやすくするための簡潔なポインター CDR を置くことは許容されますが、機械的なルールに対する CDR のみでの修正は認められません。

ルール以外の CDR タイプ（ペルソナ、例、規約）はこのゲートをスキップします。

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

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

## CDR Clarification Report

| CDR | Title | Gap Type | Severity |
|---|---|---|---|
| CDR-001 | [Title] | Missing scope | HIGH |
| CDR-002 | [Title] | Duplicate check | MEDIUM |

ギャップの種類：

• スコープの欠如：チーム全体向けか、プロジェクト固有かが不明確
• 有効性が不明確：パターンの状態が不明
• 重複チェックが必要：既存の指示と重複する可能性がある
• 内容が不完全：コンテキスト／判断／根拠が不足している
• 対象モジュールが不明確：モジュールパスの明確化が必要

フェーズ 4：順次確認

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

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

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

各 CDR について：

## CDR-{ID}: {Title}

**Context Type**: {type}
**Target Module**: {target}
**Current Status**: {status}

### Current Content

**Context**:
{context}

**Decision**:
{decision}

**Evidence**:
{evidence}

### Choose Action

| Option | Action |
|---|---|
| A | **Accept** — Approve for implementation |
| B | **Reject** — Decline with reason |
| C | **Defer** — Skip for now, keep pending |
| D | **Accept all remaining** — Accept this CDR and all pending CDRs without further review |
| P | **Promote to check** *(mechanical rules only)* — Build the deterministic check (unit test / grader / pre-commit / lint / CI); CDR kept as thin pointer or rejected as superseded |

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

続行する前に、ユーザーの入力を待ちます。

アクション P：チェックに昇格（機械的なルールのみ）

フェーズ 2b で 機械的 と分類された CDR について：

1. 決定論的なチェック（ユニットテスト、リポジトリの評価規約に従ったバイナリーグレーダー、プリコミットフック、リンタールール、または CI ジョブ）と、その正確な強制動作を提案します
2. 承認されたら、チェックを作成し、ルールの制約がない場合は失敗し、制約がある場合は成功することを検証します
3. CDR を更新します。理由を「機械的に強制可能 — 決定論的なチェックに昇格」として 却下 する（推奨）か、簡潔な参照情報（Decision: enforced by <check path>; see it before editing）として残すかを選択します。どちらにするかはユーザーが決めます
4. 昇格を記録する確認メタデータを追加します

アクション A：承認

CDR のステータス行を ### Status: **Proposed**（または **Discovered**）から ### Status: **Accepted** に更新します。確認メタデータを追加します。

### Clarification

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

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

現在の CDR を（アクション A と同様に）承認済みに更新します。その後、残りの保留中の CDR をすべて順に処理し、それぞれを ### Status: **Accepted** にして、確認メタデータを追加します。

### Clarification

- **Date**: [YYYY-MM-DD]
- **Action**: Accepted (bulk)
- **Rationale**: Bulk-accepted with user approval during clarify session

残りの CDR は個別に提示せず、フェーズ 6（インデックスの再生成）とフェーズ 7（要約）に直接進みます。

アクション B：却下

理由を尋ねます。

### Decision: Reject

| Option | Reason |
|---|---|
| A | Project-specific |
| B | Duplicate of existing directive |
| C | Deprecated/outdated pattern |
| D | Low value |
| E | Mechanically enforceable — promoted to deterministic check |

Reply with your choice.

CDR のステータス行を、理由とともに ### Status: **Rejected** に更新します。

アクション C：保留

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

### Clarification

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

フェーズ 5：CDR ファイルの更新

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

フェーズ 6：インデックスの再生成

すべての CDR-*.md ファイルを一覧表示し、Markdown の表を作成して、{REPO_ROOT}/.adlc/drafts/cdr/cdr.md を再生成します。各 CDR から単一行のフィールド（### Target Module:, ### Context Type:, ### Status:, ### Date:, ### Descriptor:）を抽出して、インデックス表を作成します。完全な形式については、/levelup-specify のフェーズ 5 を参照してください。

フェーズ 7：要約

## LevelUp Clarify Summary

**CDRs Reviewed**: N
**Accepted**: N
**Rejected**: N
**Deferred**: N

### Accepted (Ready for Implementation)

| CDR | Target Module | Type |
|---|---|---|
| CDR-001 | rules/python/error-handling | Rule |

### Rejected

| CDR | Reason |
|---|---|
| CDR-003 | Project-specific |

### Deferred

| CDR | Title |
|---|---|
| CDR-004 | [Title] |

### Next Steps

1. **Accepted**: Run `/levelup-publish`
2. **Deferred**: Will appear in next clarify session
3. **Remaining**: Run `/levelup-clarify` again to continue

主なルール

1 件ずつ対応

• 各応答で提示する CDR は必ず 1 件だけ
• 各応答で尋ねる質問は必ず 1 つだけ
• 続行する前にユーザーの入力を待つ

即時書き込み

• 各決定の後に CDR ファイルを更新する
• セッション終了後にインデックスを再生成する

自動承認なし

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

セッションの上限

• デフォルトの上限：1 セッションあたり 5 件の CDR
• 指定されている場合は --limit N に従う
• ユーザーは「done」と入力して早期に終了できる

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

/levelup-clarify の後

承認済み の CDR がある場合は、/levelup-publish に引き継ぎます。

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

Clarify フローの完了

[Pending CDRs exist]
    ↓
/levelup-clarify
    ↓
[One CDR at a time] → Accept / Reject / Defer
    ↓
[Run /levelup-publish] → Compile accepted CDRs

次のステップ

CDR を承認した後、/levelup-publish を実行して、チーム AI 指示の PR にまとめます。

検証

• 確認したすべての CDR ファイルが、新しいステータスと確認メタデータで更新されている。
• cdr.md インデックスが再生成されている。
• 承認済みの CDR は /levelup-publish に渡せる状態になっている。
• ユーザーの入力なしに自動承認または自動却下された CDR がない。

コンテキスト

$ARGUMENTS