purge-private-vocab

name: purge-private-vocab description: Detects local-plan coinages, abbreviations, and number labels in reader-facing text and rewrites them so readers without the source plan can follow. Use after generating PR description, Jira ticket, design doc, RFC, or other reader-facing text from a local plan/spec file, when readers don't share the source plan, or when the user says "造語チェックして" / "plan 用語を消して" / "PR 説明の語彙を点検して".

Purge Private Vocabulary

ローカルプランの造語・略号・番号ラベル (Single Switch, Provider 内吸収型, Critical-A, α 層, AC-12, §設計詳細 等) が plan 由来の対外文書に持ち込まれる症状を検出し、読者が plan を持たない前提で書き換える。

核心原則: 「読者が source plan を持っていない前提で読み下せるか」。書き手 (AI 自身) が plan を読んだ状態で書くと無意識に plan 内造語を持ち込む。

Task complexity tier

deep 必須前置 (Step 1 の入力収集を拡張):

1. target の文構造を直読み: **用語**: 説明 のような Label vs Body 構造かを目視確認し、Label vs Body 分離ルートの適用可否を Step 3 までに確定する
2. AC- / Critical- / RFC-* 等の ID 紐付け**: target に登場する全 ID (AC-7, Critical-A 等) を source plan / analysis ファイルから 1:1 で索引し、各 ID の元内容を「展開」または「文ごと削除」のどちらにするか Step 4 提案レポートに明記する
3. layer label (α/β/γ 層 等) の対応コンポーネント名解決: source plan から各 layer の実コンポーネント名 (Web / Service / Persistence 等) を引き、推測補完にせず実値で言い換える候補を Step 3 までに用意する。実コンポーネント名を解決できない場合 (source plan 不在等) の扱いは Q4 の層ラベル規則を SSOT とする (関係性ベースの一般表現への言い換え・捏造禁止はそちらに集約)

Core Pattern: 3 分類

Workflow

1. 入力収集

• target: 検査対象 (PR body、Jira description、design doc 等)。ファイルパス or インラインテキスト
• source plan: target の生成元 (~/.claude/plans/<topic>/plan.md 等)

両方を Read。

2. 候補抽出

target 全文から下記の検出パターンにマッチする語を全件列挙する。heuristic ヒット ≠ 要対応で、分類は Step 3 で決める (false positive を含む候補リスト):

# カタカナ造語 (型/主義/原則/論/系)
grep -oE '[ァ-ヴー一-龥a-zA-Z]+(型|主義|原則|論|系)' <target>
# section anchor
grep -oE '§[^ ,。、）]+' <target>
# アルファベット + 番号ラベル (Critical-A, AC-12 等。suffix は大文字も拾う)
grep -oE '[A-Z][A-Za-z]*-[0-9A-Za-z]+' <target>

加えて目視で拾う: 強調フレーズ (**...** / 「...」)、ギリシャ文字+層 (α/β/γ 層)、フェーズ用語 (rollout enabler 等)、数字+象限/層 (各要素が文中未説明のもの)。

パターン別の typical false positive とより広い grep 例は references/heuristics-and-pitfalls.md 参照。

3. 分類 — 決定木

各候補語を上から順に当てはめる。最初にヒットした分岐で確定:

Q1. codebase identifier / 公開規格名 / 公知の Jira/Issue ID か?
  YES → 【持ち込み可】 (例: Freee::Client, fy26q3_ebis_client, JWT, RFC 7519, XPROJ-663)
  NO  → Q2

Q2. target 自身の中で**直近に定義/展開**されているか?
     (見出し直後の本文で挙動を平易に説明、bullet で全要素列挙、等)
  YES → 【持ち込み可 (target self-contained)】
  NO  → Q3

Q3. source plan にしか定義がなく、target の読者は外部リソースで辿れないか?
  YES → Q4 (要対応)
  NO  → 【持ち込み可】 (公知用語)

Q4. 番号/層ラベルか? (`Critical-A`, `α/β/γ 層`, `AC-12`, PR チェーン番号 等)
  YES → 【要言い換えまたは削除】 出現回数に関わらず実値へ言い換え (in-line 定義ルートには載せない。Core Pattern 3 分類表と整合)。**層ラベルで source plan が無く実コンポーネント名を解決できない場合**は target 文脈から導ける関係性ベースの一般表現 (例: 「後段の処理層」) に言い換え、具体名を捏造しない (tier 非依存で適用)
  NO  → 出現回数で分岐:
    2+ 回 → 【要 in-line 定義】 (初出箇所で `用語 (= 短い説明)` を補う)。**ただし初出が見出し / title の場合**は in-line 定義が不自然なため、Label vs Body の label 書換 (平易化) ルートに倒す
    1 回   → 【要言い換えまたは削除】 (平易な日本語に書き換え、または文ごと削除)

Q1 判定: codebase identifier = git grep <語> が 1+ ヒット、公開規格 = RFC/W3C/ISO/IETF 等、公知 Issue/Jira = 公開 tracker でアクセス可。非 repo / 未マージ flag で git grep 不能時は、backtick 付き snake_case で文中に Flipper flag / class / file path と明示されている、または source plan にファイルパス/flag 記述がある語を codebase identifier とみなす。加えて Provider / Adapter / Gateway のような一般的なソフトウェア構成概念は、平易な言い換えがかえって曖昧化する場合、持ち込み可に倒してよい (読者が文脈で解せる一般語のため)。

Q2 判定: 見出し+直後本文に平易な説明があれば self-contained。ただし説明に plan 内造語がさらに混入していれば NO。迷ったら「plan 未読の同僚が target だけ読み下せるか」を音読で確認。

Label vs Body 分離 (Q2 の partial 抜けに使う既定ルート): 構造が **plan-only ラベル**: 平易な説明文… の場合、ラベルは Q4 で「要言い換えまたは削除」、本文は維持。例: **Single Switch**: Flipper の参照を 1 箇所に集約 → ラベルを **Flipper 参照の 1 箇所集約** に置換、本文は維持。

§anchor が同一 doc 内の番号のみ見出しを指す場合の中間ルート (例: §詳細6 / §4 で見出しが ## 6. サーバ通信 のように番号だけ): section は実在するので Q2 で素通しになりがちだが、番号だけでは参照先が即座に分からない。削除でも素通しでもなく、見出しの節名を併記して self-contained 化する (例: §詳細6 → 「サーバ通信 (§6)」)。参照先が target に存在しない dangling anchor のみ Q4 で文ごと削除する。

4. 提案レポート (Dry-run、書き換え前)

書き換え前に提案レポートを提示し承認を取る。Q1–Q4 のどの分岐で分類されたかを併記:

## 語彙チェック提案レポート

### 持ち込み可 (維持) — Q1 / Q2 該当
- (Q1) `fy26q3_ebis_client` (Flipper flag 名、codebase 検索可)
- (Q1) `XPROJ-663` (Jira ID)
- (Q2) `PR4-a/b/c/d` (target L12-L20 で全 PR が展開済)

### 要 in-line 定義 (2+ 回出現) — Q4 該当
1. **Single Switch** (3 箇所: L14, L42, L58)
   - 提案: 初出 L14 を `Single Switch (= Flipper 参照を 1 箇所に閉じ込める設計)` に変更

### 要言い換えまたは削除 (1 回出現または番号ラベル) — Q4 該当
1. `rollout enabler` (L18) → 「Flipper による本番経路切替を可能にする土台」に言い換え
2. `§設計詳細` (L33) → target に該当セクションなし、文ごと削除

「持ち込み可」セクションは reviewer 誤検出疑念回避のため、heuristic ヒットして Q1/Q2 で抜けた語と、heuristic 未ヒットだが疑われそうな公開語 (JWT, RFC, Express 等) を明示する。

standard / deep tier ではこの提案レポートを完全提示してから適用に進む (省略・即時 self-approve 禁止)。対話承認者がいれば承認を待ち、いない自動実行フロー (chain 実行や Stop hook 駆動) ではレポート提示自体を監査痕跡として self-approve してよい — ただし提示は飛ばさない。chain 実行 (/dry-ssot-text → 本 skill → /polish-before-commit) の「流れを止めない」圧力でレポート提示ごと省略するのが観測された失点なので、提示は必ず行う。自己承認できるのは提示の後であり、提示自体を省けるのは lite のみ。

5. 適用

承認後 (lite は Step 4 の dry-run を省略するため承認不要 — 直接適用してよい)、Edit で target に修正を適用。検証: 初出箇所のみ定義があるか / 削除した語の周辺文が文として成立しているか (主述破綻していないか) / 言い換え箇所が plan 未読でも読み下せるか 再読。

Quick Reference

Advanced

• references/heuristics-and-pitfalls.md — 検出パターン全表 + grep 例 + Common pitfalls (codebase identifier の誤書換、in-line 定義の冗長化、anchor の機械削除で文破綻、source plan 未収集、dry-run 飛ばし)

併用推奨 skill

本 skill は以下が ローカル plan を source とする対外文書を生成した直後に組み合わせると効果が高い:

• /create-pr — plan から PR description を生成 → 本 skill で語彙点検
• /create-jira-issues — plan からチケット生成 → 本 skill で description を点検
• /finalize-plan — 計画完成後、対外公開する design doc に派生させる際
• /dry-ssot-text — 同一文書内の重複集約 (本 skill とは独立した別目的)