agentleFS
apokamoapokamo/kaji/.claude/skills/issue-review-ready/SKILL.md

issue-review-ready

Skill16 starsChanged 2 days agoApache-2.0View on GitHub

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

The file

Files
SKILL.md

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_idstr正規化済み Issue ID(GitHub 数値)
issue_refstr人間可読の Issue 参照(GitHub では #<issue_id>)
step_idstr現在のステップ ID

手動実行(スラッシュコマンド)

$ARGUMENTS = <issue_id>

解決ルール

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

issue_ref はハーネス経由ではプロンプトに自動注入される(prompt.py 側で provider 別に整形)。手動実行時は issue_id から #<issue_id> を導出する。

共通ルール

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

チェック観点

共通観点(全 type 共通)

#観点指摘対象
1構造の完備概要・目的・完了条件の3セクションが存在し、空でない
2概要の具体性「何を」「どこに」が特定できない曖昧な記述(対象モジュール・機能が不明)
3目的の根拠背景・動機がない「〜したい」だけの記述、または想像・推測に基づく理由付け
4完了条件の検証可能性客観的に判定不能な条件(「改善する」「最適化する」等の主観表現)
51次情報の明示事実として述べている内容に根拠がない。想像や勝手な予測が事実のように書かれている
6記述間の矛盾概要と完了条件の不整合、目的と完了条件の乖離、スコープの暗黙的な膨張
7作業スコープの推定可能性作業対象の判断材料が本文にない
14workflow 内判定可能性通常完了条件に 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: ラベルを全件、改行区切りで取得する):

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 方式のフォールバック規則)。
#観点featbugrefactordocs
8ユースケース / ユーザーストーリー✅ ユースケース or 「[Role] として [Goal] のために [Action] したい」が 1 本以上———
9スコープ境界の明示✅ feat の範囲内で閉じるか(混在禁止の宣言があるか)—✅ feat / fix の混在禁止が明記—
10OB / 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 本文・コメントの取得

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人間決定は存在するが記述・参照が不足、またはその他の修正可能な矛盾・不足・根拠不明あり → 具体的指摘を提示、修正後に再レビュー
ABORTone-way door が人間未決、source of truth 間の優先順位が未決、または Issue 自体が不適切(重複、目的不明で修正不能等)

Step 4: Issue コメント投稿

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

verdict マーカーの無条件付与(必須): 3 つのテンプレートはどれも --verdict-step review-ready --verdict-status <STATUS> を持ち、status はテンプレートごとに PASS / RETRY / ABORT に固定している。判定した status のテンプレートをそのまま使い、フラグを消したり別の status に書き換えたりしない。CLI が body 1 行目に <!-- kaji-verdict: step=review-ready status=<STATUS> --> を付け、issue-fix-ready はこの marker だけで review-ready の判定を取得する(docs/dev/shared_skill_rules.md § verdict マーカー契約)。

PASS の場合:

kaji issue comment [issue_id] --commit \
  --verdict-step review-ready --verdict-status PASS \
  --body-file - <<'EOF'
## レディネスレビュー

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

RETRY の場合:

kaji issue comment [issue_id] --commit \
  --verdict-step review-ready --verdict-status RETRY \
  --body-file - <<'EOF'
## レディネスレビュー

### 指摘事項

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

### 判定

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

ABORT の場合:

kaji issue comment [issue_id] --commit \
  --verdict-step review-ready --verdict-status ABORT \
  --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指摘事項あり
ABORTone-way door が人間未決、source of truth が未解決に矛盾、または Issue 自体が不適切

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.