docs-refactor

name	docs-refactor
description	?
user-invocable	true
disable-model-invocation	false
metadata	{"description":".docs/ 全体を走査して重複・古い情報・命名揺れを検出し、人間が書いた部分（--- より上）を保護したまま整理する","author":"shigurenimo","dev":true,"tags":["docs","refactor"]}

.docs/ リファクタリング

.docs/ 配下を定期的にリファクタする。重複・古い情報・命名揺れを排除し、人間が書いた部分は壊さない。

このスキルは「保守的に残す」ではなく「積極的に削除提案する」姿勢で動く。古い・重複・低価値なファイルが残っていると docs 全体の信頼性が落ち、誰も読まなくなる。

使い方

/docs-refactor              # 全体監査して提案
/docs-refactor {path}       # 特定ディレクトリだけ監査
/docs-refactor import {src} # 外部資料を取り込んで既存docsと統合

人間/Claude 分離の規約

.docs/ のドキュメントは「人間が書いた内容」と「Claude が整理した内容」を --- 区切りで分離する。

# タイトル

## 人間メモ

（事業責任者・チームが議論で決まった追記・修正をここに書く）

---

## Claude整理

（Claude が分析・整理した内容）

• 上が人間、下が Claude。
• 人間が書いた部分は絶対に上書きしない。
• 整理時は下のセクションだけを書き換える。
• 区切りがない既存ファイルに追記するときは、新規にこの構造を導入することを提案する。

削除を積極的に提案する基準

以下に該当するファイルは「削除候補」として強く提案する。残す価値があるかをユーザーに必ず確認するが、デフォルト姿勢は削除。

即座に削除提案するもの

• 参照先のファイルが既に存在しない壊れた索引（broken refs）
• より詳細・最新の同名ドキュメントが他にある（要約版が冗長）
• 同じ事実を別表現で書いた複数ファイル（英日2言語版なら日本語を残す）
• 数字や件数が古くて事実と異なる（例「Notion 課題DB 42件」が現在 64件など）
• 既に他のドキュメント（index.md / metrics.md / backlogs/index.md など）に内容が取り込まれていて、原本の存在意義がない
• 自動生成された Notion frontmatter だけが残った薄いファイル
• 一時的なミーティング前提資料（合意済みなら本体ドキュメントに集約され、原本は不要）
• 環境固有のシェルコマンド集（gdate / ローカルパス前提のもの）
• コードを grep すれば取得できる情報（ルート一覧・関数一覧・enum 一覧など）
• 「解析日」「作成日」「調査日」が半年以上前で、参照価値が確認できないもの

判断を保留して質問するもの

• ADR（decisions/）— 履歴的価値があるため、明示の承認なしに削除しない
• VOC 生データ（signals/ / feedbacks/）— 後から再分析する価値が高い
• ER 図・ドメインモデル — コードと並走する補足。最新性は劣るが構造把握には有用

触らないもの

• 人間メモ（--- より上）
• ユーザーが「これは残す」と明示したファイル
• index.md / glossary.md の本体（中身を整理することはあるが削除はしない）

同時にチェックする劣化シグナル

ファイル個別の判断だけでなく、全体の劣化シグナルも検出する。

• インデックスファイル（README.md / index.md）に存在しないファイルへの参照がないか
• ディレクトリにファイルが多すぎてインデックスが崩壊していないか（目安: 20ファイル超）
• notes/ などフリーフォーマットのディレクトリに、本来 decisions/ や backlogs/ に行くべき内容が混ざっていないか
• 複数の場所に同じ概念のドキュメントが分散していないか
• 「最新」「現在の」と書かれているが日付が古いもの
• 命名規則が揺れている（kebab-case と camelCase の混在、日本語/英語の混在など）

ワークフロー

1. .docs/index.md と各 products/*/index.md を読み、製品の現状を把握する
2. ディレクトリ構造を ls -R で取得し、ファイル数とサイズの偏りを見る
3. 候補ディレクトリ（重複が起きやすいのは notes/, signals/, feedbacks/）を優先して走査
4. ファイル名・1行目・主要見出しを比較して重複候補を抽出
5. 上記の「削除を積極的に提案する基準」と「劣化シグナル」に照らして判定
6. 結果を以下のカテゴリに分類してユーザーに提示
   • 削除候補（強推奨）
   • 削除候補（要判断）
   • 統合候補（複数ファイルを1つに）
   • 最新化候補（数字や事実の更新が必要）
   • 構造改善候補（ディレクトリ移動・分割）
7. ユーザーの承認を得てから削除・編集を実行
8. リンク（wiki リンクや相対パス）が壊れていないか実行後に検証
9. 関連する README.md / index.md のリスト記載も同時更新

提案フォーマット

ユーザーに提示するときの推奨フォーマット。

## 削除候補（強推奨: N件）

- {path} — {削除理由を1行で}
- ...

## 削除候補（要判断: N件）

- {path} — {残す可能性のある理由 / 削除する理由} 

## 統合候補

- {path-A} と {path-B} を {path-C} に統合（理由）

## 最新化候補

- {path} の「{古い記述}」を「{新しい事実}」に更新

## 構造改善

- {path} を {new-path} に移動（理由）

カテゴリごとに区切って、一気に大量削除を承認させない。20件あるなら5件ずつ確認してもよい。

削除実行時の注意

• 削除前に git status を確認し、未コミットの変更がないことを確かめる
• 削除と同時に index/README のリスト記載も削除する
• wiki リンク（[[slug]]）が他のファイルから参照されていないか grep で確認
• 削除する前にユーザー確認を取る。本スキルは破壊的操作を含むため、暗黙の同意で進めない

取り込み (import) モード

外部資料を取り込んで既存 docs と統合するときの手順。

1. 取り込み元の構造を把握（プロトタイピング系のコード・HTML は対象外、ドキュメントだけ）
2. 既存 .docs/ のどのディレクトリが適切か判定
3. 既存ファイルとの重複を検出
4. 取り込み先ファイルに --- 区切りを導入し、Claude セクションに新規内容を配置
5. 既存ファイルに完全に包含される内容なら取り込まずスキップを提案
6. 取り込み完了後、関連する index.md / README.md にリンクを追加
7. 取り込みによって既存ファイルが redundant になっていないか再走査して削除提案

関連スキル

• docs: .docs/ のフォーマットとルール
• signal: 顧客の声を signals/ に追加する
• backlog: バックログを backlogs/ に追加する

関連ルール

• .claude/rules/md.md ― Markdown 記述ルール（日本語、アスタリスク禁止、見出しに数字禁止、リストはハイフン）
• .claude/rules/workflow.md ― ドキュメント運用の原則（コードと矛盾したらコードを正とする等）