issue-review-design

description	設計ドキュメントに対し、汎用的なソフトウェア設計原則に基づいてレビューを行う。
name	issue-review-design

Issue Review Design

重要: このスキルは実装/設計を行ったセッションとは 別のセッション で実行することを推奨します。 同一セッションで実行すると、実装時のバイアスがレビュー判断に影響する可能性があります。

実装フェーズに入る前に、設計ドキュメントの品質を検証します。 特定の実装詳細（How）に依存せず、要件（What）、制約（Constraints）、および利用者視点（UX）が明確に定義されているかを確認します。

いつ使うか

タイミング	このスキルを使用
設計完了後、実装開始前	✅ 必須
仕様変更時の再レビュー	⚠️ 推奨

ワークフロー内の位置: design → review-design → (fix → verify) → implement

入力

ハーネス経由（コンテキスト変数）

常に注入される変数:

変数	型	説明
issue_id	str	正規化済み Issue ID（GitHub 数値または local ID）
issue_ref	str	人間可読の Issue 参照（GitHub では #<issue_id>、local では bare ID）
step_id	str	現在のステップ ID

条件付きで注入される変数:

変数	型	条件	説明
cycle_count	int	サイクル内ステップのみ	現在のイテレーション番号
max_iterations	int	サイクル内ステップのみ	サイクルの上限回数

手動実行（スラッシュコマンド）

$ARGUMENTS = <issue_id>

解決ルール

コンテキスト変数 issue_id が存在すればそちらを使用。 なければ $ARGUMENTS の第1引数を issue_id として使用。

issue_ref はハーネス経由ではプロンプトに自動注入される（prompt.py 側で provider 別に整形）。手動実行時は issue_id から導出する: GitHub 数値 ID なら #<issue_id>、local-* 形式なら bare ID（# を付けない）。

前提知識の読み込み

以下のドキュメントを Read ツールで読み込んでから作業を開始すること。

1. テスト規約: docs/dev/testing-convention.md
2. コーディング規約: docs/reference/python-standards.md
3. 開発ワークフロー: docs/dev/kaji-workflow.md

共通ルール

• _shared/report-unrelated-issues.md — 作業中に発見した無関係な問題の報告ルール
• _shared/critical-decision-checklist.md — 人間の重要判断、AI の仮定、one-way door の分類と停止条件の正本。レビュー前に必ず読み込む

実行手順

Step 1: Worktree 情報の取得

_shared/worktree-resolve.md の手順に従い、 Worktree の絶対パスを取得すること。以降のステップではこのパスを使用する。

Step 1.5: 設計書の読み込み、一次情報・provenance の確認（Gate Check）

1. 設計書の読み込み:

   cat [worktree_dir]/draft/design/issue-[issue_id]-*.md
   

2. 一次情報の記載を確認:

設計書に以下が明記されているか確認：

• 参照した一次情報の一覧（公式ドキュメント、RFC、API仕様書、ライブラリのソースコード等）
• 各一次情報へのURL/パス（検証可能な形式）

3. 重要判断 provenance を確認:

• 判断 / 方針 / 出典または仮定 / 設計で行った詳細化 の 4 要素がある
• 人間決定の出典を検証できる
• AI の仮定が人間決定と区別され、根拠と後段の検査先を持つ
• 「該当なし」の場合も、その確認根拠がある

Gate Check の判定順

1. provenance と一次情報を Issue 本文・人間コメント・指定された source of truth に 突き合わせる
2. one-way door の真の未決、または source of truth 間の未解決な矛盾があれば、 通常レビューへ進まず ABORT
3. 人間決定は存在し、一次情報や provenance の記載・参照が不足している、または 設計が明示済み方針を上書き・弱化・格下げしているが元の決定へ戻せる場合は RETRY（Changes Requested）

ABORT の場合は --verdict-step review-design --verdict-status ABORT を付けたコメントに、 未決の判断、競合する選択肢・情報源、再開条件を列挙して終了する。RETRY に流して /issue-fix-design に人間判断を補完させない。

一次情報または provenance の記載不備 → 早期リターン

人間決定自体は確認できるが、設計書の一次情報または provenance の記載がない、または 不十分な場合は、レビュー本体に入らず以下のコメントを投稿して終了する（この早期 リターンは Changes Requested = RETRY 相当のため verdict マーカーを RETRY で付与する）。

uv run kaji issue comment [issue_id] --commit \
  --verdict-step review-design --verdict-status RETRY \
  --body-file - <<'EOF'
# 設計レビュー：一次情報 / provenance の記載が必要

## 指摘事項

設計書の**一次情報（Primary Sources）または重要判断 provenance の記載が不十分です**。

設計レビューを行うには、以下を設計書に追記してください：

### 必要な情報

1. **参照した一次情報の一覧**
   - 公式ドキュメント、RFC、API仕様書、ライブラリのソースコード等
   - URLまたはファイルパスを明記

2. **一次情報から得た根拠**
   - 設計判断の裏付けとなる情報を引用または要約

3. **重要判断 provenance**
   - 判断 / 方針 / 出典または仮定 / 設計で行った詳細化
   - AI の仮定には根拠と後段の検査先を明記

### 例

\`\`\`markdown
## 参照情報（Primary Sources）

| 情報源 | URL/パス | 根拠（引用/要約） |
|--------|----------|------------------------|
| Python公式ドキュメント | https://docs.python.org/... | 「〜を使用することで...」（該当箇所の引用） |
| Pydantic 2 Migration | https://docs.pydantic.dev/... | 〜が推奨されている（要約） |
\`\`\`

## 判定

❌ **Changes Requested** - 一次情報を追記後、再度レビューを依頼してください。

### 次のステップ

\`/issue-fix-design [issue_id]\` で一次情報を追記
EOF

この時点でレビュー終了。Step 2以降は実行しない。

---

Step 2: 設計レビュー（一次情報を参照）

一次情報と重要判断 provenance が記載され、Gate Check で one-way door の真の未決が ない場合のみ、このステップに進みます。

重要: レビュー時は設計書の記述だけでなく、一次情報を実際に参照して整合性を確認してください。

レビュー時の一次情報活用

1. 一次情報を取得: 設計書に記載されたURLにアクセス、またはファイルを読み込んで確認
2. 整合性チェック: 設計内容が一次情報と矛盾していないか検証
3. 最新性チェック: 一次情報が古くなっていないか（deprecatedなAPI等）確認

一次情報にアクセスできない場合

一次情報にアクセスできない場合は Changes Requested として設計者に対応を求めてください。

対応方法は issue-design の「一次情報のアクセス可能性ルール」を参照：

• 公開URL → そのまま記載
• ログイン必須/有償 → ダウンロードしてリポジトリ配置、または該当箇所を引用
• 社内限定/NDA → 使用不可、公開版または引用で代替

type の取得と観点の重み付け

Issue ラベルから type:* ラベルを 配列として 取得し、共通観点の重み付けを調整する:

uv run kaji issue view [issue_id] --json labels --jq '[.labels[].name] | map(select(startswith("type:")))'

cardinality チェック（先に判定）:

• 配列要素数が 2 以上 → 複数 type ラベルが付与されている。設計レビューに入らず、/issue-review-ready への差し戻しを Must Fix として投稿する（observation: 複数 type ラベル付与）。Changes Requested で停止する
• 配列が空 → type ラベル未付与。設計レビューに入らず、/issue-review-ready への差し戻しを Must Fix として投稿する（observation: type ラベル未付与）
• 配列要素数が 1 → その要素を採用し、以下の判定に進む

type 値による分岐:

1. canonical（type:feature / type:bug / type:refactor / type:docs） → 対応する重み付けを適用
2. canonical 外（type:test / type:chore / type:perf / type:security など） → type:feature と同等に扱う（フォールバック規則）

type 別重み付け（共通観点 1〜5 に対する強調度）:

観点	feat	bug	refactor	docs
1. 抽象化と責務の分離	高（IF 設計が中心）	中	高（責務再編が主題）	—
2. インターフェース設計	高（使用例・命名・idiom 必須）	低（IF 原則不変）	中（IF 不変の確認）	—
3. 信頼性とエッジケース	高（新規ロジックのエラー系）	高（OB/EB 整合・同根の漏れ）	低（振る舞い非変更）	—
4. 検証可能性（テスト戦略）	高（S/M/L 網羅）	高（再現テスト必須）	高（safety net・bridging test）	—
5. 影響ドキュメント	高	中	中	高（docs-only なら主題）

type 固有の追加観点:

• feat: 代替案の検討がある / ユースケースが具体的 / 使用例が実装前に提示されている
• bug: OB と EB が 1 次情報で裏付けられている / 再現手順が最小 / 根本原因が「なぜ」まで書かれている / 同根の他の壊れ箇所が調査済み
• refactor: ベースライン計測コマンドが明記 / 改善指標が測定可能 / 公開 IF 不変の宣言がある / safety net テストの方針が明確
• docs: type=docs は基本的に /i-doc-review の守備範囲。dev workflow の review-design に来るのは誤経路 → /i-doc-update への差し戻しを検討

重み付けの運用: 上表で「高」にあたる観点で不足があれば Must Fix として CR 判定。「低」は Should Fix に留める。type に関係しない観点（共通）の指摘は従来通り Must / Should を内容に応じて判断する。

重要判断 audit

_shared/critical-decision-checklist.md を正本として、一般的な設計品質レビューより先に 次を独立検査する。

1. Issue 本文、人間コメント、既存契約、指定された source of truth から人間決定を辿れるか
2. 設計が人間決定の範囲内を詳細化しており、判断自体を上書き・弱化していないか
3. source of truth を人間の確認なしに参考資料へ格下げしていないか
4. AI の仮定が明示され、two-way door であり、根拠と後段の検査先を持つか
5. 同正本の「one-way door になりやすい判断軸」を参照し、代表軸の未決を AI が 自己解釈で埋めていないか

判定は次のとおり。

• 真の未決や source of truth の矛盾 → ABORT
• 決定は存在するが provenance の転記・参照が不十分、または明示済み方針から逸脱 → RETRY
• 決定済み方針の詳細化と、検査可能な two-way door の仮定のみ → 通常レビューを継続

レビュー基準

以下の汎用的な原則に基づいてレビューしてください。

1. 抽象化と責務の分離 (Abstraction & Scope):

   • What & Why: 「何を作るか」と「なぜ作るか」が明確か？
   • No Implementation Details: 特定の言語やライブラリの内部実装（How）に過度に踏み込んでいないか？（疑似コードはOK）
   • Constraints: システムの制約条件（性能、セキュリティ、依存関係）が明記されているか？

2. インターフェース設計 (Interface Design):

   • Usage Sample: 利用者が実際に使用する際のコード例やAPI定義が含まれているか？
   • Idiomatic: そのインターフェースは、対象言語やプラットフォームの慣習（Idioms）に適合しているか？
   • Naming: 直感的で意図が伝わる命名がなされているか？

3. 信頼性とエッジケース (Reliability):

   • Source of Truth: 一次情報の内容と設計が整合しているか？（コピペではなく理解に基づいているか）
   • Decision Provenance: 人間決定の出典、AI の仮定、設計で行った詳細化が分離されているか？
   • No Downgrade: 人間指定の source of truth が上書き・弱化・格下げされていないか？
   • Error Handling: 正常系だけでなく、異常系（エラー、境界値）の挙動が定義されているか？
   • 一次情報との乖離: 一次情報に記載されているが設計で考慮されていない点はないか？

4. 検証可能性 (Testability):

   • テストケースの羅列ではなく、**「検証すべき観点」**が言語化されているか？
   • 変更タイプに応じたテスト戦略チェック（docs/dev/testing-convention.md 準拠）:
     • 変更タイプ（実行時コード変更 / docs-only / metadata-only / packaging-only）が明示されているか
     • 実行時コード変更なら Small / Medium / Large の検証観点が定義されているか
     • 恒久テストを追加しない場合、その理由が「docs-only / metadata-only / packaging-only 変更」節の 4 条件に沿って示されているか
     • スキップ時のエビデンス（既存テスト名、外部保証、確認内容）が記載されているか
     • uv pip install -e . など副作用のある検証を行う場合、隔離方針が明記されているか
   • 原則として新規テストを要求する変更（testing-convention.md の「実行時の振る舞いを変える変更」節参照）: ドメインロジック追加・条件分岐追加・データ変換仕様変更・API 契約変更・過去障害の再発防止。これらに該当する変更でテストを省略している場合は Changes Requested
   • 不正当な省略理由（「省略してはいけない理由」節に該当する場合は Changes Requested）:
     • 「実行時間が長い」「Large テストはステージングで検証」など → サンプル期間等で短縮可能 / CI で再現できる構成にすること
     • 「API キーがない」「DB が起動していない」など環境不備 → 修正可能な問題でありスキップ理由ではない
     • 実行時コード変更に対し「Small テストで十分カバーされている」→ テストサイズごとに検証対象が異なる

5. 影響ドキュメント:

   • 「影響ドキュメント」セクションが存在し、影響範囲が適切に評価されているか？

Step 2.5: 完了条件の段階確認

Issue 本文に ## 完了条件 セクションがある場合、設計が完了条件を充足できる構造になっているか確認する。

確認対象の例:

• 設計書のテスト方針が完了条件の要求を満たしているか
• 影響ドキュメントの評価が完了条件と整合しているか
• 設計段階で対応すべき条件が漏れていないか

確認結果は Step 3 の Issue コメントに含めて後段への証跡とする。

Step 3: レビュー結果のコメント

レビュー結果をGitHub Issueにコメントします。

verdict マーカーの無条件付与（必須）: レビュー結果コメントには 常に --verdict-step review-design --verdict-status <STATUS> を付与する。<STATUS> は本 skill が返す status（PASS / RETRY / ABORT）に置換する。review-design は design 再入 BACK を発行しないが、マーカーの無条件付与により「review-design の Changes Requested コメントが issue-design Step 1.6 で design 再入 BACK と誤検出される」旧バグの再発経路を status 語彙レベルで構造的に排除する（ADR 008 決定 3。旧実装ではこの混同が誤検出源だった）。「BACK のときだけ付ける」条件付き出力は禁止。

uv run kaji issue comment [issue_id] --commit \
  --verdict-step review-design --verdict-status <STATUS> \
  --body-file - <<'EOF'
# 設計レビュー結果

## 重要判断 audit

- **人間決定の出典**: (確認した Issue 節、コメント、既存契約)
- **AI の仮定**: (仮定、可逆性、後段の検査先。なければ「なし」)
- **source of truth**: (指定と、上書き・格下げがないことの確認)
- **one-way door**: (未決なし / 未決項目と停止理由)

## 参照した一次情報

（レビュー時に確認した一次情報とその確認結果）

| 情報源 | 確認結果 |
|--------|----------|
| [URL] | ✅ 設計と整合 / ⚠️ 差異あり |

## 概要

(設計の明確さと、実装着手の可否判定)

## 指摘事項 (Must Fix)

- [ ] **項目**: 指摘内容
  - (要件の欠落、論理的な矛盾、不明確なインターフェースなど)
  - **一次情報との関連**: （該当する場合）

## 改善提案 (Should Fix)

- **項目**: 提案内容
  - (より良い命名、将来性を考慮した構造の提案など)

## 完了条件の段階確認

設計段階の完了条件に対する充足判定:

- [ ] (条件1): ✅ 設計書の○○で対応 / ❌ 不足（理由）
- [ ] (条件2): ✅ / ❌

## 判定

[ ] Approve (実装着手可)
[ ] Changes Requested (設計修正が必要)
EOF

Step 4: 完了報告

以下の形式で報告してください:

## 設計レビュー完了

| 項目 | 値 |
|------|-----|
| Issue | [issue_ref] |
| 判定 | Approve / Changes Requested |

### 次のステップ

- Approve: `/issue-implement [issue_id]` で実装を開始
- Changes Requested: `/issue-fix-design [issue_id]` で修正

Verdict 出力

実行完了後、以下の形式で verdict を出力すること:

---VERDICT---
status: PASS
reason: |
  設計品質基準を満たしている
evidence: |
  重要判断 provenance と source of truth を Issue・一次情報に照合済み。AI 仮定は two-way door として後段の検査先が明記され、未決の one-way door はない。テスト戦略 S/M/L 網羅
suggestion: |
---END_VERDICT---

重要: verdict は stdout にそのまま出力 すること。Issue コメントや Issue 本文更新とは別に、最終的な verdict ブロックは stdout に残す。

status の選択基準

status	条件
PASS	Approve
RETRY	人間決定は存在するが provenance・一次情報の記載が不足、明示済み方針を上書き・弱化・格下げしているが復元可能、またはその他の Changes Requested
ABORT	one-way door が人間未決、source of truth が未解決に矛盾、またはその他の重大な問題

ABORT の suggestion には、人間が決める項目、競合する選択肢・情報源、再開条件を 具体的に列挙する。