Menu
設計ドキュメントに対し、汎用的なソフトウェア設計原則に基づいてレビューを行う。
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
設計書（draft/design/）に基づき、TDD（テスト駆動開発）アプローチを用いて機能を実装する。
実装完了後の成果物に対し、設計整合性とコード品質の観点から厳格なレビューを実施する
Issue 作成後・workflow 起動前に人間が明示起動する要件 interview。one-way door を含みうる重要な Issue で、未決の decision tree を 1 問ずつ推奨案付きで確認し、決定事項と provenance を Issue に固定するときだけ使用する。軽微な Issue や workflow 実行中には自動起動しない。
第2層のインシデント調査レビュー収束サイクルを 1 コマンドで手動起動する slash command wrapper。kaji run .kaji/wf/official/incident.yaml <incident_issue_id> を Bash 経由で起動し、exit code を verdict に縮約する。
Issue要件に基づき、draft/design/に設計書を作成する。worktree内での作業が前提。
ワークフローを手動実行して検証し、失敗時は継続せず原因を調査して Issue に記録する。成功時も気づきや詰まりどころを Issue に記録する。
| description | 設計ドキュメントに対し、汎用的なソフトウェア設計原則に基づいてレビューを行う。 |
| name | 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 ツールで読み込んでから作業を開始すること。
docs/dev/testing-convention.mddocs/reference/python/python-style.md
docs/reference/python/naming-conventions.md /
type-hints.md / docstring-style.md / error-handling.md /
logging.md を追加読込docs/dev/development_workflow.md_shared/worktree-resolve.md の手順に従い、 Worktree の絶対パスを取得すること。以降のステップではこのパスを使用する。
設計書の読み込み:
cat [worktree_dir]/draft/design/issue-[issue_id]-*.md
一次情報の記載を確認:
設計書に以下が明記されているか確認：
判断 / 方針 / 出典または仮定 / 設計で行った詳細化 の 4 要素があるABORTRETRY（Changes Requested）ABORT の場合は --verdict-step review-design --verdict-status ABORT を付けたコメントに、
未決の判断、競合する選択肢・情報源、再開条件を列挙して終了する。RETRY に流して
/issue-fix-design に人間判断を補完させない。
人間決定自体は確認できるが、設計書の一次情報または provenance の記載がない、または
不十分な場合は、レビュー本体に入らず以下のコメントを投稿して終了する（この早期
リターンは Changes Requested = RETRY 相当のため verdict マーカーを RETRY で付与する）。
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以降は実行しない。
一次情報と重要判断 provenance が記載され、Gate Check で one-way door の真の未決が ない場合のみ、このステップに進みます。
重要: レビュー時は設計書の記述だけでなく、一次情報を実際に参照して整合性を確認してください。
一次情報にアクセスできない場合は Changes Requested として設計者に対応を求めてください。
対応方法は issue-design の「一次情報のアクセス可能性ルール」を参照：
Issue ラベルから type:* ラベルを 配列として 取得し、共通観点の重み付けを調整する:
kaji issue view [issue_id] --json labels --jq '[.labels[].name] | map(select(startswith("type:")))'
cardinality チェック（先に判定）:
/issue-review-ready への差し戻しを Must Fix として投稿する（observation: 複数 type ラベル付与）。Changes Requested で停止する/issue-review-ready への差し戻しを Must Fix として投稿する（observation: type ラベル未付与）type 値による分岐:
type:feature / type:bug / type:refactor / type:docs） → 対応する重み付けを適用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 固有の追加観点:
/i-doc-review の守備範囲。dev workflow の review-design に来るのは誤経路 → /i-doc-update への差し戻しを検討重み付けの運用: 上表で「高」にあたる観点で不足があれば Must Fix として CR 判定。「低」は Should Fix に留める。type に関係しない観点（共通）の指摘は従来通り Must / Should を内容に応じて判断する。
_shared/critical-decision-checklist.md を正本として、一般的な設計品質レビューより先に
次を独立検査する。
判定は次のとおり。
ABORTRETRY以下の汎用的な原則に基づいてレビューしてください。
抽象化と責務の分離 (Abstraction & Scope):
インターフェース設計 (Interface Design):
信頼性とエッジケース (Reliability):
検証可能性 (Testability):
docs/dev/testing-convention.md 準拠）:
uv pip install -e . など副作用のある検証を行う場合、隔離方針が明記されているかtesting-convention.md の「実行時の振る舞いを変える変更」節参照）: ドメインロジック追加・条件分岐追加・データ変換仕様変更・API 契約変更・過去障害の再発防止。これらに該当する変更でテストを省略している場合は Changes Requested影響ドキュメント:
Issue 本文に ## 完了条件 セクションがある場合、設計が完了条件を充足できる構造になっているか確認する。
確認対象の例:
確認結果は Step 3 の Issue コメントに含めて後段への証跡とする。
レビュー結果を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 のときだけ付ける」条件付き出力は禁止。
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
以下の形式で報告してください:
## 設計レビュー完了
| 項目 | 値 |
|------|-----|
| Issue | [issue_ref] |
| 判定 | Approve / Changes Requested |
### 次のステップ
- Approve: `/issue-implement [issue_id]` で実装を開始
- Changes Requested: `/issue-fix-design [issue_id]` で修正
実行完了後、以下の形式で 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 | 条件 |
|---|---|
| PASS | Approve |
| RETRY | 人間決定は存在するが provenance・一次情報の記載が不足、明示済み方針を上書き・弱化・格下げしているが復元可能、またはその他の Changes Requested |
| ABORT | one-way door が人間未決、source of truth が未解決に矛盾、またはその他の重大な問題 |
ABORT の suggestion には、人間が決める項目、競合する選択肢・情報源、再開条件を
具体的に列挙する。