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

issue-small-change-review

Skill16 starsChanged 2 days agoApache-2.0View on GitHub

dev-small workflow の独立レビュー・最終確認工程。実装 session と別 context で実 diff と受け入れ条件を確認し、自身で品質検証を実行して PR 前提と完了条件を判定する。tracked file は編集しない。

The file

Files
SKILL.md

Issue Small Change Review

dev-small(.kaji/wf/custom/dev/dev-small.yaml)の review-change / verify-change step。 実装した session と同じ context ではレビューしない(workflow では別 session で起動される)。 Issue の決定事項・受け入れ条件と実 diff を照合し、HEAD に対して自分で品質検証を 1 回実行し、 PR 前提と完了条件を確認して判定する。修正が必要なら実装側(fix-change)へ戻す。

いつ使うか

タイミングこのスキル
dev-small の review-change(change PASS 後)/ verify-change(fix-change PASS 後)✅
標準 dev のコードレビュー❌ /issue-review-code
PR 上のレビュー❌ /review / /pr-verify

ワークフロー内の位置: change → review-change → (fix-change → verify-change) → pr → review-poll → close

入力

ハーネス経由(コンテキスト変数)

変数用途
issue_id / issue_ref / step_id / verdict_path対象 Issue、phase(review-change / verify-change)、verdict 保存先
worktree_dir / branch_name / default_branch / git_remoteレビュー対象(差分範囲の基点は [git_remote]/[default_branch])
cycle_count / max_iterations参照可

design_path は注入されても使わない。

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

$ARGUMENTS = <issue_id>

worktree_dir が無い場合だけ _shared/worktree-resolve.md で絶対パスを得る。 step_id が無い場合は verdict marker から phase を決める: 最新 fix-change PASS が最新の review 系報告より新しければ verify-change、それ以外は review-change(kaji issue resolve-verdict [issue_id] --step <step> の created_at を比較)。 marker が欠落して source: "artifact" で返った場合は ended_at を ISO 8601 の時刻として比較し、null(時刻不明)で比較が必要なら推測せず停止する。

以降の [worktree_dir] は注入値または解決した絶対パス。Bash は毎回 cd [worktree_dir] && ... で実行する。

読み込み条件

区分読むもの条件
通常Issue 本文・labels(kaji issue view [issue_id] --json title,body,labels)常時
通常最新の change PASS 報告review-change
通常最新の fix-change PASS 報告と、それが対応した直前の最新 review 系 RETRY 報告verify-change
通常git diff [git_remote]/[default_branch]...HEAD と変更ファイル実体review-change
通常git diff <全体レビュー済み SHA>..HEAD と変更ファイル実体verify-change(起点は下記)
通常自身の検証出力(成功時は終了状態・集計・JSON)常時
例外docs/dev/baseline-check.mdknown_failures / baseline 不整合
例外失敗した検証の関連ログ全文検証失敗時
例外docs/dev/testing-convention.md / docs/reference/python/*.md 該当節テストの妥当性・規約逸脱の判断が必要な場合
例外docs/dev/shared_skill_rules.md § auto close keyword 回避hazard pattern の判定に迷う場合
例外docs/dev/workflow_completion_criteria.md § 本文にチェックボックスがない場合完了条件がチェックボックス形式でない場合
例外_shared/report-unrelated-issues.md無関係な問題を発見した場合

設計書、Pre-Handoff Review 報告、final-check 報告は読まず、要求もしない。Issue の全コメント履歴を無条件に読み直さない。

入力報告の取得(1 行目の verdict marker を厳密照合し最新 1 件):

# review-change: 最新の change PASS
kaji issue view [issue_id] --json comments \
  | jq -r '[.comments[] | select(.body | test("^<!-- kaji-verdict: step=change status=PASS -->"))] | last | .body'
# verify-change: 最新の fix-change PASS と、最新の review 系報告(RETRY 指摘と全体レビュー済み範囲)
kaji issue view [issue_id] --json comments \
  | jq -r '[.comments[] | select(.body | test("^<!-- kaji-verdict: step=fix-change status=PASS -->"))] | last | .body'
kaji issue view [issue_id] --json comments \
  | jq -r '[.comments[] | select(.body | test("^<!-- kaji-verdict: step=(review-change|verify-change) status=RETRY -->"))] | last | .body'

実行手順(review-change)

Step 1: 前提確認

  • type:* ラベルがちょうど 1 件であること。0 件・複数・type:docs は ABORT。
  • 入力報告(最新 step=change status=PASS marker)が無ければ ABORT。

Step 2: 状態確認

  • HEAD full SHA を記録する。入力報告の SHA と一致しなければ、追加 commit の範囲を指摘に含める。
  • git status --porcelain が空でなければ、path ごとの差分を読んで原因(レビュー前停止中の未 commit 変更 / 原因不明 等)を 指摘に記載する。ファイルは触らない。
  • どちらの場合もレビューを打ち切らず、Step 3 の全体レビューを commit 済みの [git_remote]/[default_branch]...HEAD に対して行う (未 commit 変更はレビュー対象外として指摘に残す)。

Step 3: レビュー観点([git_remote]/[default_branch]...HEAD の全体)

観点確認内容
(a) 要件充足Issue の決定事項・受け入れ条件・不変条件を満たす
(b) Scope 混在Issue スコープ外・type 責任範囲外・無関係なついで修正がない
(c) 検証の妥当性bug の回帰テスト、feature の新挙動テスト、refactor の振る舞い非変更、docs / metadata-only の変更固有検証
(d) docs 整合挙動・運用の変更に対応する docs が更新されている
(e) auto-close 規約commit message・追加 / 変更ファイル・報告に hazard pattern(closing keyword + Issue 番号)がない
(f) 適用条件の維持大きな設計判断(公開互換性・権限境界・データ移行等)が現れていない
(g) 報告と実物の対応報告の SHA・変更ファイル・検証内容が実物と一致する

(b)(e) は標準 dev の Pre-Handoff Review 観点をこの独立レビューへ集約したもの。

hazard pattern の機械確認例:

cd [worktree_dir] && git log [git_remote]/[default_branch]..HEAD --format='%B' | \
  grep -iE '\b(clos(e[sd]?|ing)|fix(e[sd]|ing)?|resolv(e[sd]?|ing)|implement(s|ing|ed)?)\s*:?\s*#[0-9]'

Step 4: 自身の品質検証(HEAD に対して 1 回)

Step 2 で working tree が dirty だった場合は、結果が HEAD に対応しないため実行せず「未実施(dirty tree)」と記録する (PASS にはならない。次の verify-change が HEAD で実行する)。

  1. scope 評価: git diff --name-only [git_remote]/[default_branch]...HEAD の各 path を --scope に繰り返し渡す。--worktree を必ず渡す。

    cd [worktree_dir] && source .venv/bin/activate && \
      python -m kaji_harness.scripts.baseline_precheck --worktree [worktree_dir] \
        --evaluate --scope <path1> --scope <path2>

    missing_baseline / stale_baseline / blocked / invalid、または known_failures で stop: true か意味的関連がある → ABORT。

  2. gate:
    • clean: source .venv/bin/activate && make check
    • known_failures: ruff check kaji_harness/ tests/ experiments/ / ruff format --check kaji_harness/ tests/ experiments/ / mypy kaji_harness/ の全 PASS と、 python -m kaji_harness.scripts.baseline_precheck --worktree [worktree_dir] --compare の verdict: ok かつ regressions: []。 空配列や終了コードだけで成功扱いしない
  3. 変更に応じた追加検証(docs 変更時の make verify-docs、workflow YAML 変更時の make validate-workflows 等)。

失敗は関連ログを引用して RETRY。検証後に git status --porcelain を再確認し、tracked file が変化していれば、変化した path と 「検証(コマンド名)による変更」という原因を指摘に記載して保全し RETRY(戻さない・commit しない)。

Step 5: 判定

次の順に評価する。

  • 最初に、blocking finding の有無に関係なく、### ワークフロー完了後の確認項目 を除く完了条件を走査し、 軽量経路で満たせない項目(設計書の作成・設計書への準拠・設計レビューなど、dev-small にない工程の成果物を前提とする項目。 判定基準の正本: docs/dev/workflow_guide.md § dev-small の適用条件)があれば ABORT する。RETRY より優先する。 判定に迷う項目は ABORT 側に倒し、判定根拠を報告に書く。
    • 報告には該当項目(本文の文言をそのまま引用)と前提とする dev-small にない工程、人間が決める事項 (該当項目を dev-small に合わせて本文から変更するか、標準 dev に切り替えるか)を記す。 同時に見つかった blocking finding は ABORT 理由とは別に併記する(RETRY にはしない)。
    • Issue 本文の項目は書き換え・削除・チェックしない。
  • blocking finding がある → RETRY。指摘は 指摘 N 形式で file:line・根拠・期待する修正を書く。好み・scope 外改善・ 将来の改善だけでは RETRY にしない(非 blocking 所見として記載可)。
  • 適用外(大きな設計判断・公開互換性・権限境界等が必要と判明)→ ABORT。
  • finding なし →
    1. ### ワークフロー完了後の確認項目 を除く完了条件を HEAD に対して全件照合する。満たせる項目の未充足は RETRY (軽量経路で満たせない項目は先頭の検査で ABORT 済み)。
    2. PR 前提: working tree clean、HEAD == 検証した SHA、[default_branch] より先行する commit が 1 件以上。
    3. Issue 本文を再取得し、確認済み項目だけ [x] に更新する。事後確認項目は [ ] のまま残す。失敗は ABORT。

      kaji issue view [issue_id] --json body -q '.body' > <tmp>/issue-body.md
      # 確認済み項目だけ "- [ ]" を "- [x]" に変更する
      kaji issue edit [issue_id] --commit --body-file <tmp>/issue-body.md
    4. PASS。

Step 6: 報告

下記「報告」に従い Issue コメント → stdout → kaji verdict publish(verdict_path への公開)の順に残す。

実行手順(verify-change)

review-change との差分だけを示す。Step 1 の入力報告は最新の fix-change PASS 報告(無ければ ABORT)。Step 2・4〜6 は共通。

  • 確認範囲の起点: 直近の review 系報告に記録された 全体レビュー済み SHA を使う。 記録が無い(初回の全体レビューが未完了)、またはその SHA が HEAD の ancestor でない (git merge-base --is-ancestor <SHA> HEAD が非 0)場合は、Step 3 の全体レビューを [git_remote]/[default_branch]...HEAD に対して review-change と同じ規則(新規指摘可)で行い、完了を報告に記録する。
  • 全体レビュー済み SHA がある場合の確認範囲は、直前 RETRY 報告の各指摘の解消(または反論の妥当性)と、 git diff <全体レビュー済み SHA>..HEAD の修正影響(回帰・scope・auto-close 規約)。解消済み指摘を再開しない。 新たに RETRY にしてよいのは、修正差分起因の問題・HEAD での検証失敗・HEAD で未充足の完了条件・報告と実物の不一致・ working tree の dirty に限る(レビューサイクル収束のため)。
  • ただし Step 5 先頭の「軽量経路で満たせない完了条件」の検査には、この確認範囲の限定を適用しない。 HEAD 時点の Issue 本文に対して毎回行い、検出すれば RETRY より優先して ABORT する。
  • 報告の全体レビュー済み範囲は、確認を終えた HEAD に更新する。

報告

1 コメントにまとめる。1 行目の verdict marker は kaji issue comment が付与する。

kaji issue comment [issue_id] --commit \
  --verdict-step [step_id] --verdict-status <STATUS> --body-file - <<'EOF'
## 小修正 レビュー結果([step_id])

(本文)

---VERDICT---
(verdict block)
---END_VERDICT---
EOF

本文の項目:

  • レビュー対象 full SHA、入力報告の参照(step・created_at)、判定
  • 指摘(指摘 N: file:line・根拠・期待する修正)または所見。verify-change は前回指摘ごとの解消状況
  • 自身の検証: コマンド・終了状態・集計・--evaluate / --compare JSON の要点、または未実施とその理由
  • 完了条件の照合結果と本文更新結果、PR 前提
  • 全体レビュー済み範囲: [default_branch]...<SHA> の全体レビューを完了した SHA。完了していなければ「未完了」と未実施の範囲・理由
  • 引き継ぎ状態: 報告時の HEAD full SHA と working tree(clean、または dirty path ごとの原因)
  • ABORT 時: 停止理由(該当条件と根拠)、人間が決める必要のある事項、branch・worktree path・HEAD full SHA・ git status --porcelain の要約、関連報告の参照、「再実行は初めから」の案内

成功時の検証ログ全文は貼らない。Issue コメント投稿に失敗した場合は ABORT とし、verdict を stdout に出して kaji verdict publish で公開する。

副作用の境界

Issue コメント投稿と、PASS 時の Issue 本文チェックボックス更新のみ。tracked file の編集・commit・push・PR 作成・merge・ label 変更・worktree 作成/削除・session-state 編集・他 workflow 起動はしない。人間レビューはこの工程の検証・判定を代替しない。

Verdict 出力

作業報告コメント末尾、stdout に同じ内容を残し、最後に prompt の kaji verdict publish で verdict_path へ公開する(verdict_path を直接書かない)。

---VERDICT---
status: PASS
reason: |
  全体レビューで finding なし、HEAD で自身の検証が成功し、完了条件を確認した
evidence: |
  HEAD <full SHA>、make check exit 0(pytest N passed)、完了条件 N 件を [x] に更新
suggestion: |
---END_VERDICT---
status条件(review-change / verify-change 共通)
PASS[git_remote]/[default_branch]...HEAD の全体レビューが完了済み、finding なし、working tree clean、HEAD で自身の検証が成功、完了条件を全件確認し本文更新済み、PR 前提を満たす
RETRY具体的な修正を要する blocking finding(未 commit 変更・SHA 不一致・検証失敗・検証による tracked file の変化・軽量経路で満たせる未充足の完了条件を含む)
ABORT適用外、軽量経路で満たせない完了条件(blocking finding の有無に関係なく RETRY より優先)、入力報告の欠落、baseline 停止基準、type ラベル不正、Issue 本文更新・コメント投稿の失敗

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.