---
name: dry-ssot-text
description: Use when an AI-generated document (plan / design doc / RFC / PR description) has grown long with the same concept explained in multiple places and needs consolidation to a single source of truth while preserving navigation aids like TOC, progress tables, and checklists
---

# DRY/SSOT Text Refactor

## Overview

AI が生成した長文 (plan, design doc, RFC, PR description, README 等) は、しばしば同一概念を複数箇所で繰り返す。これは読み手の認知負荷を上げ、後の修正コストを高め (3 箇所更新するうち 1 箇所を忘れる)、トークン消費を増やす。

本 skill は冗長な説明を 1 箇所に集約 (Single Source of Truth) し、他箇所はクロスリファレンスに置換する。同時に「必要重複」(TOC, checklist, progress table 等の navigation aid) は残す。

**核心原則**: 「同じ事実を 2 度書かない」だが「ナビゲーション目的の重複は別物」。

## When to Use

主条件 (どれかに該当):
- 同一概念の説明が **3+ 箇所** で発生している (文書サイズによらず)
- レビュアーから「冗長」「読みづらい」「重複多い」と指摘された

副条件 (上記に加えて以下のいずれかなら効果が高い):
- 文書が長文 (200 行+)、メンテナンスで「片方だけ更新した」状態が生じやすい
- 文書をプロジェクトのコンテキスト窓に何度もロードする (AI が後で参照する) ため、トークン効率を上げたい

**When NOT to use**:
- 重複が 2 箇所以下 (集約しても 1 箇所減るだけでメリット薄い)
- 文書が**外向きの説明資料** (顧客向けドキュメント、ブログ記事) で、各セクションが自己完結すべき場合
- API リファレンスのような **網羅的列挙が目的** の文書

## Core Pattern: 必要重複 vs 不要重複 の判定

すべての重複が悪ではない。以下の判定表に従う:

| 種類 | 例 | DRY 化するか | 理由 |
|---|---|---|---|
| **不要重複: 説明文** | 同じ設計判断を PR1/PR2/PR3 セクションで再記述 | **する** | 1 箇所更新で済むメリット > navigation コスト |
| **不要重複: 表/コード** | 同じ table が 2 箇所、片方に「再掲」と書く | **する** | 1 箇所更新で済む |
| **不要重複: 引用文** | 公式ドキュメントの同一一節を 2 箇所引用 | **する** | 引用元 1 箇所に集約 |
| **必要重複: TOC / 進捗 table** | 章立て一覧、PR 進捗表 (タイトルと状態) | **しない** | 俯瞰 navigation の機能 |
| **必要重複: checklist サマリ** | AC リストの 1 行 + 詳細は §設計詳細で詳述 | **しない** | 確認用 checklist の機能 |
| **必要重複: header + body 同名** | 「§Provider 内吸収型」の見出しと本文冒頭 | **しない** | 見出しは index の機能 |

## Workflow

### 1. 重複の特定 (Identify)

- 文書全文を Read
- 同一概念 (= 同じ事実、同じ table、同じコード片) が複数箇所で出現するパターンを列挙
- 各パターンを 上記判定表で「不要重複」「必要重複」に分類

### 2. Canonical location の決定 (Decide SSOT)

不要重複ごとに、唯一の真実源を 1 箇所に決める:

**選定ルール**:
- 文書末尾の **§設計詳細 / §参照** に専用セクションを設けて集約 (推奨、文書全体を散歩しなくて済む)
- 例外: 概念が **文書冒頭の前提知識** に該当する場合は冒頭近くに配置 (例: 「ゴール」「アーキテクチャ」)

**避けるべき配置**:
- 最初に出現する PR/章のセクション内に置く → 後の章で「§PR1 を参照」と書かれ、PR1 が更新されたとき他章の意味が崩壊
- 文書の途中の任意箇所 → 読み手が forward/backward 両方ジャンプ必要

### 3. クロスリファレンス置換 (Replace with refs)

他箇所の説明文を **markdown アンカーリンク** で置換:

```markdown
<!-- Before (各 PR セクションに同じ説明) -->
重要な設計判断: AuthGateway は単一の責務に閉じ込め、ユーザ管理や権限管理は別サービスに委譲する。

<!-- After (1 箇所に集約後の参照) -->
**設計判断**: §[重要な設計判断](#重要な設計判断) 参照
```

**置換時の注意**:
- セクション参照は必ず markdown アンカーリンク `[表示文字列](#anchor)` 形式
- 参照は **その PR セクションの冒頭近く** に置く (実装の前に設計を読ませる)
- 各 PR セクションは「スコープ 1 文 + 設計判断リンク + 実装ファイル table」の三段構造を維持し、スコープ説明まで削らない (過 DRY 防止)
- **関連が弱い PR の扱い**: PR の内容が SSOT に直結しない場合 (例: 「機能 X 削除」PR と「機能 Y の設計判断」)、**default は省略** (リンクを貼らない)。例外: 関連性が補完的に有用 (読み手の理解の助けになる) と判断した場合のみ、1 句で関連性を補足 (例: `**設計判断**: §X 参照 (新経路への完全切替の前提)`)。迷ったら省略を選ぶ (過 DRY 防止より過リンク防止を優先)
- **既存表記スタイルの維持**: 元文書の表記スタイル (散文 / list / table) は **DRY/SSOT 化のスコープ外**。「実装ファイル table」は skill 例示であって、元文書が散文ならそのまま散文で残す。表記スタイル変更は別 task として切り分ける
- **AC / checklist 内のクロスリファレンス**: 元文書が `(<参照テキスト>参照)` のような括弧書きで参照していた場合、括弧構造を保ちつつ中身をアンカーリンクに置換する (例: 元 `(Token rotation の挙動表参照)` → refactor 後 `(§[Token rotation 挙動表](#token-rotation-挙動表) 参照)`)

### 4. Dry-run レポート (推奨)

大規模文書 (300 行+) または共有前文書では、いきなり書き換えず **提案レポート** を先に作る:

```markdown
## DRY 化提案レポート

### 不要重複 (集約候補)
1. **「AuthGateway 単一責務」** (3 箇所: L40, L75, L105) → §設計詳細 に集約
2. **Token rotation 表** (2 箇所: L120-128, L145-153) → §設計詳細 に集約

### 必要重複 (維持)
1. **PR 進捗 table** (L25-32) → index 機能、維持
2. **AC checklist** (L180-200) → 確認用、維持 (詳細は §設計詳細 参照リンク追加で代替)

### 想定される行数削減
元: 250 行 → 後: 約 180 行 (28% 削減)

### 確認ポイント
- canonical location を §設計詳細 (文書末尾) に置く案で問題ないか？
- 各 PR セクションのスコープ説明 (1 文) は維持するか？

承認をいただければ書き換えを実施します。
```

### 5. 実適用 (Apply)

承認後、Edit / Write で書き換え。書き換え後に:
- `grep -c "<重複していた canonical フレーズ>" <file>` で 1 件のみヒットすることを確認 (重複の集約検証)
- 文書を冒頭から線形に読み、参照リンクが機能しているか確認
- `wc -l` で行数を確認 (**ただし行数は増減両方ありうる**。canonical セクションと参照リンクの追加で小規模文書は微増しうる。重視するのは **同一情報の重複箇所数の減少**、行数ではない)

## Quick Reference

| 操作 | コマンド / パターン |
|---|---|
| 重複検出 | `grep -nE "<重複候補フレーズ>" <file>` で出現箇所列挙 |
| 行数測定 | `wc -l <file>` |
| アンカーリンク形式 | `[表示文字列](#anchor)`。anchor は見出しを小文字 + スペースをハイフン化 |
| dry-run トリガ | 300 行+ または レビュー前 → dry-run レポート先行 |
| SSOT 配置先 | 文書末尾の §設計詳細 / §参照 章 (推奨) |

## Common Mistakes

### ❌ 過 DRY: 各セクションがリンクだらけになり線形読みが破綻

**症状**: PR セクションを開いても「§X 参照 / §Y 参照」しか書かれていない。読み手が複数セクションをジャンプしないと意味が掴めない。

**修正**: 各セクションは **「スコープ 1 文 + 設計判断リンク + 実装ファイル table」** の三段構造を維持。スコープ説明まで削らない。

### ❌ TOC / index の削除

**症状**: 「PR 進捗 table の各行が PR セクション header と重複している」と判断して table を削除。

**修正**: TOC / 進捗 table / checklist は **navigation 機能**。文章の重複でなく構造の重複なので維持。判定表 §Core Pattern 参照。

### ❌ Canonical location を本文中の任意位置に置く

**症状**: 「§PR1 の説明文中に」設計判断を置いて、後で「§PR1 参照」と書く。PR1 が将来更新されたら他章の意味が崩壊。

**修正**: SSOT は **専用セクション** (§設計詳細 / §参照 等) に切り出す。本文の説明文中に置かない。

### ❌ Dry-run なしで大規模文書を直接書き換え

**症状**: 300 行の plan を一気に書き換え、後で「この削除は意図と違う」とレビューで指摘される。

**修正**: 300 行+ の文書では必ず提案レポート先行。

### ❌ 必要重複と不要重複の判定漏れ

**症状**: 「AC リストの『§X 参照』は冗長」と判断して全削除。後で AC 確認時に毎回詳細セクションへジャンプが必要に。

**修正**: AC / checklist の 1 行サマリ + 詳細セクションリンクは **確認用 navigation aid** として必要重複。判定表 §Core Pattern で確認。

## Real-World Impact

実証例: 1074 行の plan.md を本 skill の手順で refactor → 328 行 (約 1/3 圧縮)。
- 設計判断の説明箇所: 3-5 箇所 → 1 箇所 (§設計詳細)
- Single Source of Truth セクション: 0 → 5 (4 層担保 / nil 戦略 / Single Switch / 4 象限 / rescue 拡張)
- AC リスト: 1 行 checklist + 詳細リンク table 形式に再構成
- 行数削減で約 60% のトークン節約を達成 (AI が文書を後で参照する際の累積効果)