Fix prose

語彙・言い回しの自動修正

コードコメントやドキュメントの自然言語を走査し、rules.toml で宣言した「直したい語彙・言い回し」を検出してその場で書き換える。 AI らしい定型語、過剰敬語、冗長表現、ヘッジなど、自分の好みに合わせた語彙ルールを辞書で管理する。

検出は scan.py（ルール辞書を読んで該当箇所を JSON で返す）が担い、書き換えは本手順に従って Claude が行う。 コード識別子やコードフェンス内はスクリプト側で対象外にしているため、コメント・散文だけが対象になる。

入力

$ARGUMENTS に走査対象のパスとオプションが渡される。

• パスはファイル / ディレクトリを複数指定可（ディレクトリは再帰）
• --profile <name> で contextual 語の許容範囲を切り替え（省略時は rules.toml の default_profile）
  • technical … コード / 技術文書向け。技術的に正当な語（robust 等）は許容
  • docs … 一般ドキュメント向け
  • strict … contextual もすべて指摘

例

• /fix-prose src/ → src 配下を technical で走査・修正
• /fix-prose README.md docs/ --profile docs
• /fix-prose . → カレント以下すべて

手順

1. スキャンの実行

uv run ${CLAUDE_SKILL_DIR}/scan.py $ARGUMENTS を実行する。

• $ARGUMENTS が空の場合は、対象が不明なのでユーザーにパスを尋ねる
• パスにスペースや glob 文字（* ? 等）を含む場合は、Bash コマンド構築時に各パスを個別にダブルクォートで囲む（$ARGUMENTS 全体を一括クォートするとフラグや複数パスの分割が壊れる）
• 依存（pygments, typer）は PEP 723 により uv run が自動解決する
• 非ゼロ終了した場合は stderr のエラーをユーザーに報告して終了

2. 出力（JSON）の解析

stdout は JSON で、以下のフィールドを含む。

• profile - 適用プロファイル
• files_scanned - 走査したファイル数
• files_skipped - スキップしたファイル（理由付き）
• summary - 件数集計（total, always, pattern, contextual_flagged, contextual_allowed, density_reports）
• findings - 検出配列
  • path, line - 該当箇所
  • lang - en / ja
  • tier - always / contextual / pattern（density は findings ではなく後述の density 配列に出る）
  • matched - 実際にマッチした表層文字列
  • base - ヒットした辞書キー
  • suggest - 置換候補の配列
  • snippet - 該当行のテキスト
  • note - 補足（contextual に多い）
  • allowed_by_profile - contextual のみ。true なら現プロファイルで許容
• density - 密度レポート（多用 / 共起）
  • 比率版: ratio, threshold, words（語ごとの出現数）
  • 共起版: cooccurrence（同居した語）, snippet

3. 書き換えの適用

ティアごとに方針を変えて、該当ファイルを Edit ツールで直接書き換える。

always（文脈不問）

確認なしで置換する。suggest の中から文脈に最も自然なものを選ぶ。 適切な候補がなければ、語の意図を保ったまま平易な表現に言い換える。

contextual（文脈依存）

• allowed_by_profile == true → 原則そのまま（技術的に正当な用法）。 ただし明らかに空虚な賛辞・誇張（例: "seamless experience" のような中身のない強調）であれば置換する。
• allowed_by_profile == false → note を踏まえて置換する。ヘッジ（「〜と思われます」等）は、根拠があるなら言い切りに直す。

density（多用 / 共起）

同じ語の多用や、複数の冗長語の共起を解消する。語を削る・言い換える・文を再構成するなど、密度を下げる方向で最小限に直す。 ただし ratio が高くても words の合計出現が少ない（散文が短く分母が小さい）場合や、該当語が contextual で許容（allowed_by_profile == true）の単発語だけの場合は「多用」ではないため書き換えず、報告に留める。

pattern（構造パターン）

特定の語ではなく「形」を捉えた検出（全角括弧の補足など）。matched は正規表現に一致した範囲、note に再構成の指針がある。 note に従って文を組み替える。例えば後付けの理由・限定を表す全角括弧は本文へ展開し、用語の初出注記やスコープ表記のような短く独立した注は残す。機械置換ではないため、文意とニュアンスを保つことを最優先する。

共通ルール

• コードの意味を変えない。識別子・API 名・設定キー・コマンド・固有名詞には触れない（スクリプトが除外済みだが、念のため確認する）。
• suggest は意味の参考であって字面どおり挿入するものではない。書き換えは対象テキストの言語（lang）に合わせる。lang と suggest の言語が食い違う場合（例: 英語コメントに日本語 suggest が付く pattern ヒット）は、suggest の意味を汲んで周辺と同じ言語で平易に言い換える。
• 1 ファイルずつ、最小限の差分で適用する。周辺の文体は保つ。
• 置換して文意が通らない / ニュアンスが変わる場合は適用せず、判断保留として報告する。
• 同一行に複数ヒットがある場合はまとめて直す。語尾の冗長表現（「〜できる形になります」等）は無理に元の構文を残さず、一文に統合して平易化してよい（体言止めの解消を含む）。

4. 結果の報告

以下を簡潔に報告する。

• 修正件数（ティア別）
• ファイルごとの主な変更（before → after を数件）
• 適用を見送った項目とその理由（contextual 許容、文意不通など）
• 密度レポートで対応した箇所

5. 辞書へのワード追加

ユーザーが「今後 X を Y に直して」「この語も対象にして」と指示した場合、${CLAUDE_SKILL_DIR}/rules.toml の該当セクションに 1 行追記する。

• 常に直す語 → [en.always] / [ja.always] に "語" = ["置換候補", ...]
• 技術文脈だけ許す語 → [en.contextual] / [ja.contextual] に "語" = { suggest = ["置換候補"], allow_in = ["technical"], note = "" }（キーは必ずダブルクォートで囲む。〜・空白入りキーが無引用だと TOML が壊れる）
• 多用だけ抑える語 → [en.density] / [ja.density] の words に追記

追記後、必要なら同じ対象に対して再スキャンを実行する。日本語の語頭ワイルドカードは 〜（例: "〜と思われます"）で表す。

禁止事項

• 書き換えにあたり、レビュー署名や生成ツールの宣伝文言を本文へ加えない。
• 辞書に存在しない語を勝手に「AI らしい」と判断して大量に書き換えない。判断は辞書 + note の範囲に留め、迷う語は報告して辞書追加をユーザーに委ねる。