Issue Review Ready

---
description: Issue本文の着手レディネスレビュー。作業着手に足る記述品質があるかを検証する全 workflow 共通ゲート。
name: issue-review-ready
---

# Issue Review Ready

Issue 本文が作業着手に足る記述品質を持つかをレビューする **全 workflow 共通**のゲートスキル。
`issue-create` 後、`issue-start` の前に実行し、記載の矛盾・不足・根拠のない推測を指摘する。

## いつ使うか

| タイミング | このスキルを使用 |
|-----------|-----------------|
| Issue 作成後、作業着手前 | ✅ 必須 |
| 既に作業フェーズに入っている Issue | ❌ 不要 |

**ワークフロー内の位置**:

- dev workflow: create → **review-ready** → start → design → ...
- docs-only workflow: create → **review-ready** → start → i-doc-update → ...

worktree 不要（メインリポジトリから実行可能）。

## 入力

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

**常に注入される変数:**

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

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

```
$ARGUMENTS = <issue_id>
```

### 解決ルール

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

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

## 共通ルール

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

## チェック観点

### 共通観点（全 type 共通）

| # | 観点 | 指摘対象 |
|---|------|----------|
| 1 | **構造の完備** | 概要・目的・完了条件の3セクションが存在し、空でない |
| 2 | **概要の具体性** | 「何を」「どこに」が特定できない曖昧な記述（対象モジュール・機能が不明） |
| 3 | **目的の根拠** | 背景・動機がない「〜したい」だけの記述、または想像・推測に基づく理由付け |
| 4 | **完了条件の検証可能性** | 客観的に判定不能な条件（「改善する」「最適化する」等の主観表現） |
| 5 | **1次情報の明示** | 事実として述べている内容に根拠がない。想像や勝手な予測が事実のように書かれている |
| 6 | **記述間の矛盾** | 概要と完了条件の不整合、目的と完了条件の乖離、スコープの暗黙的な膨張 |
| 7 | **作業スコープの推定可能性** | 作業対象の判断材料が本文にない |
| 14 | **workflow 内判定可能性** | 通常完了条件に merge 後・実機適用後・外部応答後など workflow の RETRY で環境非依存に再現できない確認が混在している、または事後確認欄が `## 完了条件` の末尾サブセクションになっていない |
| 15 | **重要判断の着手可能性** | one-way door が人間未決、source of truth の指定・優先順位が矛盾、または AI が人間の判断を代行しなければ作業スコープや公開契約を確定できない |

観点 14 の分類基準は
[`docs/dev/workflow_completion_criteria.md`](../../../docs/dev/workflow_completion_criteria.md)
§ workflow 内完了条件と事後確認の分離を正本とする。誤分類は本文編集で修正可能なため
`RETRY` とし、`ABORT` にしない。

観点 15 は
[`_shared/critical-decision-checklist.md`](../_shared/critical-decision-checklist.md)
を正本として、Issue 本文だけでなく人間の Issue コメントと、本文で source of truth に
指定された参照先も確認する。重要そうかではなく、誤ったときに後段で安く直せるかで
3 分類する。

- 決定済み方針は、その出典と決定範囲が後段で辿れるなら着手可能
- two-way door の未決は、AI の仮定として後段で検査できるなら着手可能
- one-way door の真の未決、または source of truth 間の未解決な矛盾は `ABORT`
- 人間決定は存在するが、本文への参照・記述が不足しているだけなら `RETRY`

one-way door になりやすい代表軸は、同正本の「one-way door になりやすい判断軸」を
参照する。個別項目を本 skill に複製せず、可逆性で判定する。

### type 別追加観点

Issue のラベル（`type:feature` / `type:bug` / `type:refactor` / `type:docs`）に応じて、上記共通観点に加えて以下を確認する。

ラベル取得（`type:` ラベルを全件、改行区切りで取得する）:

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

**判定の優先順（「未付与」「複数付与」「canonical 外」を区別）**:

`type:` ラベルは single-select 運用（1 Issue に 1 ラベルのみ）。以下の cardinality チェックを上から順に適用する:

1. **出力が 0 件（空）** → type ラベル未付与。**RETRY** として起票者にラベル付与を求める（observation 13 として指摘）。後段の追加観点は適用しない。
2. **出力が 2 件以上** → type ラベル複数付与。どの type 軸でレビューすべきか確定不能。**RETRY** として起票者にラベル整理（1 つに絞る）を求める。後段の追加観点は適用しない。
3. **出力が 1 件で canonical（`type:feature` / `type:bug` / `type:refactor` / `type:docs`）** → 対応する追加観点を適用する。
4. **出力が 1 件で canonical 外（`type:test` / `type:chore` / `type:perf` / `type:security` など）** → `type:feature` と同等の追加観点（feat 列）を適用する（dispatch 方式のフォールバック規則）。

| # | 観点 | feat | bug | refactor | docs |
|---|------|:----:|:---:|:--------:|:----:|
| 8 | **ユースケース / ユーザーストーリー** | ✅ ユースケース or 「[Role] として [Goal] のために [Action] したい」が 1 本以上 | — | — | — |
| 9 | **スコープ境界の明示** | ✅ feat の範囲内で閉じるか（混在禁止の宣言があるか） | — | ✅ feat / fix の混在禁止が明記 | — |
| 10 | **OB / EB / 再現手順** | — | ✅ 壊れた挙動（OB）・あるべき挙動（EB）・再現手順が分離して記述 | — | — |
| 11 | **測定可能な改善指標** | — | — | ✅ 現状の問題が観測値に落ちており、改善指標が定量 or 定性で固定されている | — |
| 12 | **対象ドキュメントパス** | — | — | — | ✅ 対象ドキュメントのパスまたは領域が明示されている |
| 13 | **コード変更の非混入宣言** | — | — | — | ✅ docs-only であり、コード変更が混ざらない宣言がある |

> **重み付けの方針**: 上記追加観点は「その type 特有の情報不足」を検出する目的。共通観点 1〜7・14・15 が通っていても、追加観点で不足があれば RETRY とする。

#### 観点 8（feat）: 許容されるユースケース記述

- 「[Role] として、[Goal] のために、[Action] したい」のユーザーストーリー形式
- あるいは「誰が / どの状況で / 何をしたくて / どう嬉しいか」の箇条書き
- 抽象的な「新機能を追加する」だけでは観点 8 を満たさない

#### 観点 10（bug）: OB / EB の最低要件

- **OB**: ログ、コマンド出力のいずれかが根拠として含まれていること
- **EB**: 仕様書パス / 既存テスト名 / Issue / ドキュメントパスなど 1 次情報の根拠があること
- **再現手順**: 前提条件 + 操作 + 観測結果が番号付きで書かれていること
- bug の admissibility は以下の 2 区分で判定する:
  - **(a) 証跡が一切ない**（再現不能と本文に書かれている / OB を示すログ・出力が全くない）→ 本スキルで ABORT（調査 Issue に格下げを推奨）
  - **(b) 実世界障害ログで証明済み**（本文またはリンク先に OB を直接示す実ログ＝失敗コマンド・エラー文言・exit code・API 応答・関連 Issue/PR の実行ログ等が存在し、かつ **その OB に対応する EB を検証する恒久回帰テストが構築可能**）→ 合成再現テストの Red→Green ログが本文に無くても **admissible**（ABORT しない）。実ログを実装前 Red 証跡の代替として扱ってよい
- この代替は**実装前 Red ログのみの例外**であり、再現可能性そのもの（OB に対応する EB を検証する回帰テストが書けること）は免除しない。実ログがあっても回帰テストで OB を検証できない genuinely 再現不能な bug は (a) として ABORT する。下流の design（番号付き再現手順）/ implement（OB 対応の回帰テスト）の要求は緩めない。修正後の回帰テスト Green・影響範囲の品質ゲート・同根欠陥確認も免除しない。実ログが OB と対応しない場合、単なる省力化・実行時間短縮・後付け都合を理由とする場合は代替不可

#### 観点 11（refactor）: 測定可能性の例

- 観測可能: 循環依存数、重複コード件数、カバレッジ %、実行時間、行数、複雑度
- 不可: 「汚い」「わかりにくい」「保守性が低い」等の主観表現

### 観点5: 許容される根拠

以下のいずれかが Issue 本文中またはリンク先に存在すれば、根拠ありと判断する:

- Issue 本文中の URL（外部ドキュメント、API 仕様等）
- 既存 docs パス（`docs/` 配下のファイルパス）
- 関連 Issue / PR 番号（`#123` 形式）
- ユーザー提供データ（ログ出力、エラーメッセージ等）
- CLI 出力の引用

### 観点7: 許容される判断材料

作業スコープが推定可能であれば OK。workflow によって判断材料は異なる:

**dev workflow（コード変更を含む Issue）:**
- 対象ファイルパスまたはディレクトリの言及
- 変更対象モジュール名の言及
- 既存コンポーネント名・モジュール名の言及

**docs-only workflow:**
- 対象ドキュメントのパスまたは領域の言及（例: `docs/dev/`, `CLAUDE.md`, スキル定義）
- 変更対象の文書カテゴリ（tutorials, reference, howto, adr 等）の記述

## レビュー方針

- **詳細設計レベルの指摘はしない**（それは `issue-review-design` の役割）
- **矛盾・記載不足・根拠不明の指摘**に特化する
- 「こう書くべき」ではなく「ここが不明/矛盾している」と指摘する

## 実行手順

### Step 1: Issue 本文・コメントの取得

```bash
kaji issue view [issue_id] --json title,body,labels,comments \
  --jq '{title: .title, body: .body, labels: [.labels[].name], comments: [.comments[] | {author: (.author.login? // .author), body: .body}]}'
```

取得した本文と人間のコメントを以降のステップで分析する。コメントが AI / bot の出力か
人間決定かを識別できない場合、そのコメントだけを人間決定の根拠にしない。

### Step 2: チェック観点に基づくレビュー

#### Step 2a: 共通観点 1〜7・14・15 の確認

1. **構造の完備**: `## 概要`, `## 目的`, `## 完了条件` の3セクションが存在し、内容が空でないことを確認
2. **概要の具体性**: 「何を」「どこに」が特定できるか確認
3. **目的の根拠**: 背景・動機が具体的に記述されているか確認
4. **完了条件の検証可能性**: 各条件が客観的に判定可能か確認
5. **1次情報の明示**: 事実として述べている内容に根拠があるか確認（許容される根拠は上記参照）
6. **記述間の矛盾**: セクション間の整合性を確認
7. **作業スコープの推定可能性**: 作業対象の判断材料があるか確認（許容される判断材料は上記参照）
8. **workflow 内判定可能性**: `## 完了条件` の通常項目は workflow を RETRY して環境非依存で同じ結果を得られるか確認する。得られない項目は末尾の `### ワークフロー完了後の確認項目` に分離され、事後確認がない場合はセクションなしまたは `- なし` になっていることを確認する
9. **重要判断の着手可能性**: 本文・人間コメント・指定された source of truth を突き合わせ、重要判断を 3 分類する。決定済み方針の出典、two-way door として後段検査できる未決、one-way door の真の未決、source of truth の矛盾を区別する

#### Step 2b: type 別追加観点の確認

Step 1 で取得した labels から type を判定し（上記「ラベル取得」の優先順に従う）、対応する追加観点を確認する:

- **0 件（未付与）** → 追加観点は評価せず、RETRY として「type ラベル未付与」を指摘
- **2 件以上（複数付与）** → 追加観点は評価せず、RETRY として「type ラベル複数付与（1 つに絞る必要あり）」を指摘
- `type:feature`（1 件） → 観点 8, 9
- `type:bug`（1 件） → 観点 10
- `type:refactor`（1 件） → 観点 9, 11
- `type:docs`（1 件） → 観点 12, 13
- **canonical 外 1 件**（`type:test` / `type:chore` / `type:perf` / `type:security` 等） → 観点 8, 9（feat と同等）

### Step 3: Verdict 判定

| status | 条件 |
|--------|------|
| PASS | 共通観点 1〜7・14・15 と該当 type 追加観点をクリア → 作業着手に進行可 |
| RETRY | 人間決定は存在するが記述・参照が不足、またはその他の修正可能な矛盾・不足・根拠不明あり → 具体的指摘を提示、修正後に再レビュー |
| ABORT | one-way door が人間未決、source of truth 間の優先順位が未決、または Issue 自体が不適切（重複、目的不明で修正不能等） |

### Step 4: Issue コメント投稿

Verdict に応じて以下の形式で Issue コメントに投稿する。

**PASS の場合:**

```bash
kaji issue comment [issue_id] --commit --body-file - <<'EOF'
## レディネスレビュー

全観点クリア。作業着手に進行可。
EOF
```

**RETRY の場合:**

```bash
kaji issue comment [issue_id] --commit --body-file - <<'EOF'
## レディネスレビュー

### 指摘事項

1. **[観点名]**: 具体的な指摘内容
2. **[観点名]**: 具体的な指摘内容

### 判定

RETRY — 上記を修正後、再度 `/issue-review-ready [issue_id]` を実行してください。
EOF
```

**ABORT の場合:**

```bash
kaji issue comment [issue_id] --commit --body-file - <<'EOF'
## レディネスレビュー

### 理由

具体的な ABORT 理由（重複先 Issue 番号、修正不能と判断した根拠など）。

### 人間が決める項目

- (未決の判断、競合する選択肢・情報源、再開条件を具体的に列挙)

### 判定

ABORT — この Issue は作業着手の対象外です。
EOF
```

### Step 5: 完了報告

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

```
## レディネスレビュー完了

| 項目 | 値 |
|------|-----|
| Issue | [issue_ref] |
| 判定 | PASS / RETRY / ABORT |

### 次のステップ

- PASS: `/issue-start [issue_id]` で worktree をセットアップ
- RETRY: Issue 本文を修正後、再度 `/issue-review-ready [issue_id]` を実行
- ABORT: Issue を close するか、内容を根本的に見直し
```

## Verdict 出力

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

```
---VERDICT---
status: PASS
reason: |
  全チェック観点をクリア
evidence: |
  共通観点1〜7・14・15と該当type追加観点について、構造・具体性・根拠・検証可能性・1次情報・整合性・スコープ推定・workflow内判定可能性・重要判断の着手可能性に問題なし
suggestion: |
---END_VERDICT---
```

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

### status の選択基準

| status | 条件 |
|--------|------|
| PASS | 全観点クリア |
| RETRY | 指摘事項あり |
| ABORT | one-way door が人間未決、source of truth が未解決に矛盾、または Issue 自体が不適切 |

`ABORT` の場合、`suggestion` に人間が決める項目、競合する選択肢・情報源、再開条件を
具体的に列挙する。one-way door を `RETRY` に流して `/issue-fix-ready` に補完させない。