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/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 § workflow 内完了条件と事後確認の分離を正本とする。誤分類は本文編集で修正可能なため RETRY とし、ABORT にしない。

観点 15 は _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: ラベルを全件、改行区切りで取得する）:

uv run 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 本文・コメントの取得

uv run 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 の場合:

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

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

RETRY の場合:

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

### 指摘事項

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

### 判定

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

ABORT の場合:

uv run 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 に補完させない。