narrative-review

name	narrative-review
context	fork
description	マークダウン / script / 設定の差分を「文量バランス」「経緯コメント検出」の 2 観点でレビューする。文量バランスは markdown のみ、経緯コメント検出は `.md` / `.sh` / `.sb` / `.json` を対象。「ナラティブ レビュー」「文量バランス」「経緯コメント残ってない」で発動

ナラティブ レビュー (markdown / script / 設定の差分)

main ブランチとの diff を下記ルールで判定する。ファイル編集は行わない。修正判断は呼び出し元に委ねる。

対象

git diff --name-only origin/main...HEAD -- \
  '*.md' '**/*.md' \
  '*.sh' '**/*.sh' \
  '*.sb' '**/*.sb' \
  '*.json' '**/*.json'

出力が空なら PASS (no target files changed) を返して終了する。

ファイル種別ごとに適用ルールが変わる。次の表のとおり

• *.md — 文量バランス (4 観点) と経緯コメント検出 (5 観点目) の両方
• *.sh / *.sb / *.json — 経緯コメント検出のみ

ルール

文量バランス (markdown 専用)

SKILL.md / CLAUDE.md / commands/*.md の散文肥大化を 4 観点で検出する。README.md 等の一般 docs には緩く適用する。

1. 判定 / 分岐ロジックがコマンド節 (実行可能 snippet) に集約されているか
2. description / 目的 / 手順が最小置換で済んでいるか
3. 手順への補足が 1 行に圧縮されているか
4. 差分の経緯解説が本文に残っていないか (経緯は commit メッセージ / PR description 側にあるべき)

経緯コメント検出 (markdown / script / 設定共通)

経緯コメントとは、現在の挙動や設計意図でなく、過去の状態や廃止された案を残した記述。git history で追える情報のため、コード / docs 本体には残さない。

何を「経緯」と判定するか

次の signal のうち 1 つ以上に当たると「経緯コメント」と判定する。トリガー語そのものを禁止リスト化するのではなく、文の 指示対象 を読む

• 過去状態への言及 — 「もとは X だった」「以前は X」「これまでは X」「当初は X」「従来は X」「以前の実装」「previously」「originally」「used to」
• 廃止 / 移行 / 削除に至った理由 — 「X を廃止した」「X から Y へ移行した」「X を整理 / trim / 統一した」「X を捨てた理由」
• 過去の方針への言及 — 「過去の方針」「廃止背景」「廃止理由」「以前の判断」「経緯」
• 比較対象が現存しない過去案 — 「A 案ではなく B にした」「X だと Y で困るので Z」(X が既に存在しない時)
• 変更時刻に紐づく説明 — 「2026-06-XX に変更」「PR #XYZ で変わった」「コミット XXXXXX で」

トリガー語を避けた言い換えも、指示対象が過去であれば経緯として扱う。例:

• 「もとは〜だった」
• 「当初の意図は」

何を「正当」と判定するか

次に当たる記述は「経緯」に該当せず、コード / docs 本体へ残してよい。git history で補えない情報のため

• 現在の挙動 / 意図の説明 — 「X は Y を保証する」「この関数は Z 用」
• 現在有効な制約 / 不変条件 — 「mode は read か write のいずれか」「ここで lock を握る」
• 既知の落とし穴 / 警告 — 「N >= 100 で O(N^2) になるため注意」「この path は IPv4 のみ受け取る」
• 設計判断のうち 今も生きている 根拠 — 「順序依存があるため逐次実行」「冪等性確保のため UUID 採用」(過去案との対比ではなく現在の制約)
• 引用 / 外部仕様への参照 — 「RFC 1234 セクション 3.2 に従う」「man 5 sudoers 参照」

判別の核は 時制と指示対象。「現在こうである」を述べる文は残す。「過去こうだった」「過去こうしたから今こう」を述べる文は剥がす。

例

経緯コメント (FAIL すべき)

# もともと Obsidian Sync を使っていたが、サブスク解約のため git clone へ移行。
# SSH key は当時の認証で必要だった。

{
  // 廃止理由: 旧 API は rate limit が低かったため v2 に切り替え。
  "endpoint": "v2"
}

かつてはレイヤ 1 で deny を貫通させていたが、現在は明示 allow を採用している (Layer 4 と同じ rw allow + 用途のパラ括弧注釈)。

正当な inline コメント (PASS すべき)

# vault 配下のみ rw allow (Layer 4 と同等、worker が write する)

{
  // v2 endpoint は 1000 req/min まで許容
  "endpoint": "v2"
}

`endpoint` は `v1` / `v2` を受け取り、`v2` は 1000 req/min まで許容する。

手順

ファイル別に git diff origin/main...HEAD -- <file> と Read <file> を実行し、上記ルール違反を行番号付きで列挙する。

• markdown は文量バランス 4 観点 + 経緯コメント検出を両方適用する
• .sh / .sb / .json は経緯コメント検出のみ適用する
• false positive を避けるため、判別に迷う comment は 保留 とし、最終出力では「保留」セクションに別記する。FAIL 扱いにはしない

出力

PASS か FAIL を 1 行出力する。FAIL 時、指摘事項と推奨修正を箇条書きで添える。判別が難しい comment は ### 保留 セクションへ別記し、PASS / FAIL 判定の対象外とする。