Polish before commit

polish-before-commit

提案だけでなく、自動修正まで行う。 プロジェクト規約・パターン一貫性・impl/spec 整合 (現状 Ruby/RSpec の delegate/def 撤去後 dead-mock 削除のみ、TS/JS/Python は範囲外で skip) を点検し、Step 4 → 5 → 6 → 7 は順序固定で再評価ループ禁止。

特殊モードの読み替え: review-only (ファイル変更不可) / 他者 PR 点検 / subagent 委譲 (Task 起動) 時の検出・報告・Step 9 の読み替えは references/execution-modes.md を参照する (通常フロー = 単独起動・自ブランチ・ファイル編集可 では読み込み不要)。user が「ファイル変更はしない」「レビューのみ」「他者の PR」を指示した場合、または利用可能ツール一覧が subagent 委譲を示す場合に適用する。

フロー最終段の役割: この skill はフローの最後に置かれることを想定する。代表的な前段列 (可変) は /simplify → /vercel-react-best-practices → /review-code-quality → 組み込み /code-review → 本 skill だが、実運用ではこの間に /vercel-composition-patterns・/express-intent-in-code、文章チェーン (/dry-ssot-text → /purge-private-vocab) 等が挟まる場合がある。Step 9 で /review-code-quality からの申し送り (.git/quality-review-handoff-<branch>.md) と本 skill の Manual Review Items を集約し、末尾でユーザー判断が必要な項目を一覧提示してから止まる (連続スキル実行で個別レポートが transcript に埋もれ握りつぶされるのを防ぐため)。

Orchestrated モード: ファイル存在からの推測では判定しない。呼び出し側（将来のオーケストレータ）が Task 起動プロンプトで「orchestrated モードで実行。escalation は <path> に記帳して続行せよ」のように明示指示した場合のみ発動する。指示が無い単独起動では現行動作（判断項目 1 件以上で停止しユーザーの明示指示を待つ）のまま進む。差分は Manual Review Items #4 (dead mock 部分削除) と Step 9 のみで、詳細は references/orchestrated-mode.md を参照。

Task complexity tier

Tier	判定	実行 Step
lite	1 ファイル、diff <30 LoC (ファイル総行数でなく追加+削除行数)、規約 hit 0、Ruby delegate/def 撤去なし (全条件を AND で満たす)	Step 5 (lint) + Step 8 (final review) + Step 9 (集約)
standard (default)	2-5 ファイル, 規約 hit 1-3 (lite にも deep にも該当しないもの)	Step 1-5 + Step 8 + Step 9 (Step 6/7 は条件 hit 時のみ)
deep	6+ ファイル または 規約 hit 4+ または Ruby delegate or def 撤去あり または multi-language (OR — いずれか 1 つで deep に昇格)	全 Step (1-9)

Step 1 (規約の収集) は tier 判定の前に全 tier で必ず実行する (tier 判定基準の「規約 hit 数」は Step 1 の収集結果からしか得られないため)。上表の「実行 Step」列は Step 1 通過後にどの検査・修正 Step (4 以降) を実行するかを指し、lite でも Step 1 は飛ばさない。リスク領域 (auth / billing / payment / migration) は LoC によらず deep。

補足:

• 規約 hit 数: Step 1 で収集した明文規約への一致件数のみを指す (Step 4 の既存パターン多数派逸脱は判定軸が別のため含めない)。Step 1 はリポジトリ内 CLAUDE.md/rules とグローバル ~/.claude/CLAUDE.md/rules の両方を収集対象とするため、hit 数は両者を合算した件数で数える (起源による区別はしない)。
• Step 4 / Step 7: tier 表の「実行 Step」列に無い tier では、各 Step 固有の条件判定 (規約の有無等) より tier-skip を優先し [<Step>: tier-{lite,standard,deep} により省略] を出力する。Step 固有の条件不一致文言は、その tier の「実行 Step」列に含まれる場合のみ使う。standard 行末尾の「(Step 6/7 は条件 hit 時のみ)」但し書きは「実行 Step 列の記載」に含める: standard tier の Step 7 は列本体に明示列挙されていなくても行末尾但し書きで条件付き実行が許容される Step として扱い、code-comments.md 等が hit していれば Step 7 は tier-skip せず条件バリアント ([コメント改善: 違反なし（規約適用済み）] 等) を出力する。
• Step 6 (dead mock): Ruby PR で delegate :X / def X 撤去を含む場合のみ実行する。Step 4/7 と異なり tier 表の「実行 Step」列の記載に関わらず、条件一致で tier 問わず発火する。skip 時の bracket 文言は「条件由来 (Ruby/RSpec 対象外・撤去なし等) > tier 由来」で選ぶ: 変更ファイルに *.rb なし or spec なし or 削除 identifier 0 件 のいずれかに該当すれば tier に関わらず条件バリアント ([dead mock: スキップ (Ruby/RSpec 対象外)] 等、references/dead-mock-removal.md の 4 バリアント) を出力する。[dead mock: tier-{lite,standard,deep} により省略] は使わない (Step 6 は tier 表列に依存しないため)。
• Step 9 (判断申し送りの集約): tier 問わず必ず実行する (フロー最終出力のため lite でも省略不可)。

Manual Review Items (自動修正せず提案のみ → Step 9 で集約)

以下は本 skill が検出しても自動修正せず、Step 9 の「ユーザー判断が必要な項目」に集約する (auto-fix に入る前にこの分類を確定しておくため、Step 一覧より前に置く):

1. 設計判断: サービス切り出し / モジュール化 / 責務分離
2. 影響範囲調査: メソッド名・引数・戻り値の変更
3. ビジネスロジック: バリデーション追加 / 認可変更
4. Dead mock の部分削除 (receive_messages(a:, b:) のうち一部 identifier だけ削除): 書換え候補を併記してユーザー承認後に編集 (Orchestrated モード時は削除せず、書換え候補を escalation ledger に保留として記帳する。references/orchestrated-mode.md 参照)
5. Reference-free dead file (Ruby 以外): 直近ブランチで追加された __mocks__/** や spike* / scratch* prefix の TS/JS/Python ファイルで、外部参照が grep で 0 件 (import / require / test loader での参照無し) のもの。Step 6 の dead-mock 削除は Ruby/RSpec 限定のため、他言語の spike 残骸は自動削除せず Manual Review に集約して user 判断を仰ぐ (誤検出時に削除するとテスト setup が壊れうるため)。判定は本 skill 直前に実行済みの /code-review が拾い Step 8 で取り込んだ「dead file」指摘を優先し、独自 grep で追加検出する範囲はこの 3 prefix に限定する。

現在の対象 (skill 読み込み時に自動取得)

!git branch --show-current

!git diff --name-only origin/${BASE_BRANCH:-develop}...HEAD

!git diff --name-only HEAD

!git diff --name-only --cached

上 4 行は Claude Code が skill 読み込み時に実行し結果へ置換する (読み取り専用・冪等)。2-4 行目はそれぞれ ブランチ全体 / 未コミット (worktree) / staged 差分で、スコープ判定 (Quick start 1) に使う。失敗時のフォールバックは原因別: (a) 生コマンド文字列のまま見える (注入非対応環境) → Quick start 1 の同コマンドを Bash で実行。(b) unknown revision 等のエラー (base branch が develop でない) → 次の順で能動的に解決する (/create-pr Step 0b と同じ手順、git remote show origin 単独には頼らない — remote の HEAD symref が dangling だと (unknown) を返し base を特定できないため): ① gh repo view --json defaultBranchRef --jq .defaultBranchRef.name ② 失敗時 git symbolic-ref refs/remotes/origin/HEAD --short | sed 's@^origin/@@' ③ いずれも失敗なら main を既定にする。決定した値を BASE_BRANCH=<base> として以降のコマンドに指定して再実行する (以降の ${BASE_BRANCH:-develop} はこの値を優先して使う)。

Quick start

1. 引数 $ARGUMENTS あり → そのファイルを対象。なし → git diff --name-only origin/${BASE_BRANCH:-develop}...HEAD (ブランチ全体) で取得 (0 件なら終了)。ただしブランチ全体と未コミット+staged 差分が大きく乖離する長命ブランチでは、今 commit しようとしている未コミット+staged 差分 (冒頭 3-4 行目) を既定スコープにする (本 skill は commit 直前の用途なので、過去コミット分まで巻き込まない。ブランチ全体を polish したい時のみ明示指定し、判断に迷えば user に確認)。
2. 規約を収集 (下記 Workflow Step 1) → 規約 hit 数 + ファイル数で tier 表の実行範囲を確定 → tier 対応 Step を順に実行。
3. 各 Step の結果を文言バリアント表に厳密一致させた最終レポートを返す (silent skip 禁止)。バリアント表を持つのは Step 4/5/6/7/8/9 のみで、表の無い Step (規約収集・対象ファイル確定・処理方式) は bracket 文言不要 (要約 1 行で足りる)。省略文言の使い分け: tier 由来の省略は [<Step>: tier-{lite,standard,deep} により省略]、条件不一致由来のスキップ (Step 6 の撤去なし等) は各 Step 固有のスキップバリアント文言を優先する。最後に Step 9 で ### ⚠️ ユーザー判断が必要な項目 を集約提示し、commit へ進まず判断を仰ぐ。

Workflow

1. 規約の収集

find . -maxdepth 4 -name "CLAUDE.md" -type f 2>/dev/null
find . -maxdepth 5 -path "*/.claude/rules/*.md" -type f 2>/dev/null

加えて ~/.claude/CLAUDE.md と ~/.claude/rules/*.md も Read。抽出対象: コーディング規約 / 命名 / 禁止事項 / 推奨パターン / コメント原則。0 件なら以降の各ステップのフォールバック (スキップ + 文言明示) に従う。

規約 0 件時の分岐: Step 4 → 既存パターン多数決のみ (規約根拠なしの逸脱検出は行わない、文言 [パターン一貫性: 違反なし] を流用) / Step 7 → 即 [コメント改善: スキップ（規約に原則なし）] を出力。

2. 対象ファイル確定 / 3. 処理方式

Step 2 は Quick start の通り。Step 3 の並列化判定は 3 分岐:

• ファイル ≤ 5: main thread で直接処理
• ファイル > 5 かつ単一言語: main thread で順次処理 (subagent 並列化しない — 単一言語では規約セットが共通で分散のオーバーヘッドが節約時間を上回る)
• ファイル > 5 かつ複数言語混在: subagent_type: "general-purpose" で並列 (規約・対象ファイル・references/pattern-consistency.md を渡す)

Task が利用可能ツール一覧に無い場合は並列化せず main thread で順次処理する (references/execution-modes.md の「委譲実行」節参照)。

4. パターン一貫性

対象ファイルの既存パターン分析 → 同一ファイル内混在検出 → 類似ファイル間不整合検出 → 規約整合性確認 → 既存パターンへ統一。

統一先の優先順 (上から、一致したら止める) — auto-fix の判断はこの順で確定する:

1. プロジェクト規約 (CLAUDE.md / rules) に対象パターンのキーワードを含む明示指定 → それに従う (多数派と競合しても規約が勝つ)
2. 同一ファイル内の多数派 (2/3 以上の出現) → それに合わせる。Priority 2 は「同一ファイル内でパターンが混在している場合」にのみ適用する (単一 style で 100% 一貫しているファイルは「多数派 = 自ファイル style」と自己参照的に読まず、Priority 3 (ディレクトリ多数派) へフォールスルーする)
3. 同一ディレクトリの他ファイルの多数派 (5 割超) → それに合わせる
4. 上記で決まらない (同数 / 出現 1 件) → 自動修正せず Manual Review Items に統一先候補を列挙
5. 同種ファイル 0 件 (新規追加 only で比較対象なし) → 判定不能、[パターン一貫性: 違反なし]

言語別の混在しやすい観点 (Ruby の結果オブジェクト OpenStruct/Hash・inline/block rescue、TS の絶対/相対 import・type/interface 等) とファイル間整合 (認可チェック配置・トランザクション境界等) の網羅例は references/pattern-consistency.md を参照。

4.6 同種違反の網羅確認 (必須): 1 ファイルでパターン違反を修正したら、変更ファイル群の他箇所に同じ違反が残っていないか grep で網羅確認し、見つけた違反は同時修正する。

• 検査コマンド汎用形: grep -l '<違反パターン>' $(git diff --name-only origin/${BASE_BRANCH:-develop}...HEAD)
• Step 5 (lint) が Step 2 で確定した変更ファイル群全体をカバーするため、4.6 で広げた範囲も自動再検証される。

Step 4 レポート文言 (3 バリアント、いずれかを必ず出力):

条件	文言
違反 0 件	[パターン一貫性: 違反なし]
1 ファイル修正 + 他箇所 0 件	[パターン一貫性: N 件修正、網羅確認 OK]
複数ファイル同時修正	[パターン一貫性: N 件修正 (うち網羅確認発火 M 件)]

「違反なし」バリアントは 2 経路をカバーする: (a) 統一先の優先順で違反を検出しなかった場合、(b) 統一先の優先順 5 (同種ファイル 0 件、新規追加 only で比較対象なし) で判定不能となった場合。executor が両経路を区別する必要はなく、同一文言に落として問題ない (下流の Step 5-8 での再検証で違反があれば拾われる)。

5. lint 自動修正 (言語別分岐)

言語	コマンド
Ruby	bundle exec rubocop ${files} --autocorrect-all
TypeScript/JavaScript	yarn eslint ${files} --fix
Python	ruff check --fix ${files} または black ${files}
その他 (Go/Rust/Shell 等)	Makefile / package.json / pyproject.toml から lint タスク探索。なければ [lint: 未定義言語のためスキップ（手動確認要）]

成功するまで最大 3 回繰り返す。3 回試行で解決しなければ手動対応として報告。

順序保証: Step 5 の auto-fix 差分は Step 6 / 7 の評価対象に含める (lint 結果を信頼)。Step 4 の再評価はしない。Step 4 → 5 → 6 → 7 で確定、逆順・再評価ループは禁止。

Step 5 レポート文言 (5 バリアント、いずれかを必ず出力):

条件	文言
違反 0 件	[lint: 違反なし]
自動修正実施	[lint: N 件自動修正]
対象言語のツールが未導入/未設定 (依存関係・設定ファイル不在)	[lint: ツール未導入のためスキップ（手動確認要）]
3 回試行しても解決しない	[lint: 3 回試行で未解決、手動対応要]
表に無い言語 (その他行)	[lint: 未定義言語のためスキップ（手動確認要）]

6. Dead mock 削除 (Ruby/RSpec)

詳細手順・スキップ条件・文言 4 バリアントは references/dead-mock-removal.md に従う。要旨:

• 対象: impl 側で delegate :X / def X を撤去した PR の spec 残存 mock (receive(:X) / receive_messages(X:) / instance_double(..., X:) / double(..., X:))。
• スキップ判定の優先順: ① *.rb なし / spec/ なし → 対象外、② 削除 identifier 0 件 → 撤去なし。
• 削除単位: 単独 stub と「全 identifier が削除済の receive_messages」は auto、部分削除は Manual Review。
• 削除後は編集 spec 全件を bundle exec rspec で 0 failures 確認。失敗時は revert + 報告。

7. コメント改善

Step 1 で収集した規約テキストに「コメント」「comment」キーワードを含む節がある場合のみ実施。なければ独自判断で追加・削除しない。先行パス (/express-intent-in-code や /dry-ssot-text 等) で判断済みの箇所は対象外とし、規約準拠の機械的観点のみに限定する。この hit 判定は tier 表の「規約 hit 数」とは独立: tier 表の hit 数は全収集規約の件数を数えるが、Step 7 の実行判定は「収集規約の中に『コメント』『comment』キーワード節が含まれるか」で行う (tier=standard で hit 1 でも、その 1 件が typescript-coding.md (キーワード節なし) なら Step 7 は [コメント改善: スキップ（規約に原則なし）] を出力する)。ただし comment-writing メタ規約 — 「書くと決めたコメントの文面」を定め先行パス /express-intent-in-code が適用する規約 (例: ~/.claude/rules/code-comments.md) — はこの hit 母集団に数えない: その領域は先行パスが所有済みで Step 7 は対象外だから、Step 1 が収集するグローバル規約セットに含まれていても Step 7 実行の根拠にはならない。hit 判定は diff に適用される coding convention (repo CLAUDE.md/rules・言語別 coding 規約) のコメント原則節の有無だけで行う (repo CLAUDE.md の「コメント原則」節はこれに該当し Step 7 を発火させる)。

Step 7 レポート文言 (3 バリアント、いずれかを必ず出力):

条件	文言
規約に原則なし	[コメント改善: スキップ（規約に原則なし）]
規約あり + 違反なし	[コメント改善: 違反なし（規約適用済み）]
規約あり + 修正実施	[コメント改善: N 件修正（<規約根拠>準拠）] (根拠は適用規約のファイル名)

8. 最終レビュー

組み込み /code-review skill は本 skill からは起動しない (組み込み /code-review には disable-model-invocation が設定されており、Skill ツール経由の起動が失敗して別 skill への意図しないフォールバックを誘発した実測があるため)。ユーザーが本 skill の直前に /code-review を起動しておき (検出エージェントと検証エージェントを分離した多段構成のため effort xhigh を推奨)、Step 8 ではその実行結果を取り込む:

1. 会話内に直前の /code-review 実行結果があれば、その指摘を auto-fix 済み / 未対応に分類し、未対応分を Step 9 の集約へ渡す。
2. 実行結果が会話内に見つからない場合は、main thread で同等のレビュー (変更 diff のバグ・規約違反確認) を直接行い、[最終レビュー: ... (fallback)] と明示する (silent skip 禁止。自発的に /code-review を起動して補完しない — 起動タイミングはユーザーが制御する)。

diff が URL の生成・リダイレクト・route helper (url_for 系)・パス断片の受け渡しに触れる場合、フレームワークの暗黙のリクエスト文脈自動付与 (Rails の default_url_options 等) によるクエリ混入で「クエリなしパス」前提の結合契約が壊れていないかを、取り込み時の追加観点として自前で点検する (事前 /code-review が拾っていない場合の補完。静的レビューでの早期発見の一助であり、実行検証の代替にはならない — Gotchas 参照)。

review-only で他者の PR を点検する場合: 事前の /code-review も PR head を展開した worktree (gh pr checkout または git worktree add) 上で実行しておく。指摘の根拠行が PR head と一致しない worktree に由来する場合は、PR head 側で再確認してから採用する (stale なローカル worktree の値を根拠にした誤指摘の実績があるため。/review-code-quality の「PR レビューモード」と同じ規則)。

Step 8 レポート文言 (2 バリアント、いずれかを必ず出力):

条件	文言
指摘なし	[最終レビュー: 指摘なし]
指摘あり	[最終レビュー: 指摘 N 件 (内訳: バグ X / 規約違反 Y / その他 Z)]

内訳 3 分類の判定基準: バグ = 実行時に誤動作する欠陥 (誤った出力・例外・データ破損等)。規約違反 = Step 1 で収集した明文規約との不一致。その他 = 上記いずれでもない品質指摘 (デッドコード・命名・テスト不足等)。

9. 判断申し送りの集約 (フロー最終 / 全 tier 必須)

このフローの最終出力として、ユーザー判断が必要な項目を 1 箇所に集約・提示してから止まる。連続スキル実行で個別レポートが transcript に埋もれ握りつぶされるのを防ぐ。

1. 申し送りファイルを読む (--git-dir でなく --git-common-dir を使う: git worktree add で作った linked worktree では --git-dir が worktree 固有ディレクトリを返し、main 側と共有の申し送りファイルを見失うため。通常の worktree では両者は同じ値になり挙動は変わらない。ファイル名のブランチ名は、共有 --git-common-dir を使う複数 worktree の並行セッションが単一ファイルを相互 overwrite しないための分離):

   HANDOFF="$(git rev-parse --git-common-dir)/quality-review-handoff-$(git branch --show-current | tr '/' '-').md"
   [ -f "$HANDOFF" ] && cat "$HANDOFF"
   

   ブランチ名付きファイルが無い場合は旧パス $(git rev-parse --git-common-dir)/quality-review-handoff.md も確認し、branch: が現在ブランチと一致する場合のみ採用する (書き手の /review-code-quality が旧版のままの移行期対応。不一致なら並行セッションの成果物なので削除もしない)。 本 skill 実行前に外部診断ツール (react-doctor 等) の指摘が会話内で共有され、修正しきれず残った指摘がある場合は、その残存指摘も出所「外部診断ツール」として集約リストに追加する (修正済みの指摘は集約不要)。
2. ファイル先頭の branch: が現在のブランチ (git branch --show-current) と一致するもののみ採用。不一致なら stale として除外し [申し送り: stale (別ブランチ) のため除外] を 1 行明示。
3. 採用した申し送り項目 + 本 skill の Manual Review Items (前掲・tier 表直後) + Step 8 (最終レビュー) の指摘のうち auto-fix されず残ったもの + 1. で追加した外部診断ツールの残存指摘を統合する。同一箇所・同一の設計判断を指す指摘は出所が異なっても 1 件にまとめ出所欄に複数ラベルを併記し、それ以外は各項目 1 件のまま扱う (Step 8 由来も次項の出所ラベルでは「polish 検出」に含める — review-code-quality からの申し送りと区別できればよく、出所を 3 系統に分けて併記する必要はない)。
4. 末尾に ### ⚠️ ユーザー判断が必要な項目 セクションを出力。各項目は /abs/path:line + 要約 + 出所 (review-code-quality 申し送り / polish 検出 / 外部診断ツール、複数該当時は併記) + 推奨対応を併記。1 項目の形式例:

### ⚠️ ユーザー判断が必要な項目
1. `/repo/app/services/billing_service.rb:42` — 認可チェックを before_action へ寄せるか要判断 (出所: polish 検出) → 推奨: TeamsController と揃え before_action :authorize へ統一
2. `/repo/spec/models/user_spec.rb:88` — `receive_messages(a:, b:)` の `a:` のみ削除の部分 dead-mock (出所: polish 検出) → 推奨: `b:` を残す書換え案で承認後に編集
3. `/repo/src/components/SettingsPanel.tsx:1` — props 増加に伴うコンポーネント分割の要否 (出所: review-code-quality 申し送り / 外部診断ツール) → 推奨: 同一論点のため分割要否の判断をまとめて実施 (二重対応を避ける)

5. 一覧を提示したらここで本 skill は終了する。 agent 側から commit / git add / /create-pr を自発実行・提案しない (フロー開始時点で既にコミット / PR を指示済みなら、その指示に従ってよい)。本 skill の後に外部診断ツール (例: npx react-doctor) を実行する場合は、その指摘は本 skill の集約一覧に含まれない (本 skill 実行前に共有され修正しきれず残った指摘は Step 9 の 1. のとおり集約対象であり、この後実行ケースとは前提が異なる) — ユーザーが別途確認するか、ツール実行後に Step 8-9 だけ再実行して束ね直す。判断項目の有無で終了時の文言を分ける (自発 commit はしない原則はどちらも同じ):
   • 判断項目 0 件: 質問形にせず「判断項目なし。コミット可能な状態」と完了報告して終了する (ユーザーの返答を待たない)。
   • 判断項目 1 件以上: 現行どおり一覧を提示し「polish 完了。コミットへ進めますか?」と 1 文返してユーザーの明示指示を待つ。
   • Orchestrated モード時: 判断項目が 1 件以上でもユーザーの返答を待たず、一覧を escalation ledger に記帳したうえで完了報告して終了する。記帳内容は references/orchestrated-mode.md を参照。
6. 提示後、申し送りファイルをクリアする (次フローに stale を持ち越さない): [ -f "$HANDOFF" ] && rm "$HANDOFF"

Step 9 レポート文言 (3 バリアント、いずれかを必ず出力):

条件	文言
判断項目 0 件	[ユーザー判断項目: なし]
判断項目あり (外部診断ツール由来の残存指摘なし)	[ユーザー判断項目: N 件 (申し送り X / polish 検出 Y)]
判断項目あり (外部診断ツール由来の残存指摘 1 件以上、統合先が無く単独計上のもの)	[ユーザー判断項目: N 件 (申し送り X / polish 検出 Y / 外部診断ツール Z)]

集計基準: Y (polish 検出) は「Step 8 残存指摘 + Manual Review Items を dedup した後の件数」 (Step 9-3 の「同一箇所・同一の設計判断を指す指摘は 1 件にまとめる」規則を適用済みの数値。単純合算ではない)。X (申し送り) と Z (外部診断ツール) も同様に dedup 後の件数。N = X + Y + Z の合計。複数出所併記の統合項目は、採用した上位深刻度の出所側にのみ 1 カウントする (残る出所側の件数からは差し引く。例: 申し送り Major + Manual Review Minor が同一箇所で統合 → 上位 = 申し送り Major を採用し X に 1 計上、Y には計上しない)。

Gotchas（観測済みの罠 — 実測で判明したものを 1 件 1 行で追記）

• 規約 hit 数の数え方: tier 判定基準の「規約 hit 数」は「規約への一致件数」とだけ定義され、1 規約に複数箇所で違反がある場合に規約の項目数で数えるか違反箇所数で数えるかが未定義。fresh executor 2 回の検証で解釈が割れた (既知ギャップとして据え置き、今回の改修テーマ外)
• 申し送りファイルは rm 前に必ず Read する: branch: と内容が現在のフローの成果物であることを確認してから消す (linked worktree 環境で、パス探索の fallback が拾った別セッションの残骸 handoff を未読のまま rm した実測事例。stale (別ブランチ) は Step 9 の除外対象であって削除対象ではない)
• URL 生成への暗黙リクエスト文脈混入は静的レビューで取りこぼしやすい: フレームワークがリクエストスコープの値を URL 生成へ自動付与する挙動 (Rails の default_url_options 等) は diff を読むだけでは気づきにくく、実行して観測しない限り見落としやすい (実測: _sp クエリの混入で /id?token= の結合契約が壊れ 404 になったが、品質レビュー 7 パス全通過後にユーザーの実機操作で発覚)

併用推奨 skill

• /review-code-quality — 設計レベルの品質課題を検出し、自動適用しない needs-judgment を本 skill へ申し送る (Step 9 で集約)
• 組み込み /code-review — 本 skill の直前にユーザーが起動する最終レビュー (Step 8 が結果を取り込む。本 skill からは起動しない)
• /create-pr — Step 9 のユーザー判断が片付いた後にカレントブランチから PR を作成