Doc Maintainer

---
name: doc-maintainer
description: AI向けマークダウンドキュメント（SKILL.md、AGENTS.md、.agent/*.md など）の健全性チェックと修正を支援するスキル。「ドキュメントの整合性を確認」「SSOT違反を探す」「スキル定義をメンテしたい」「PRの概要を更新したい」と依頼されたときに使用する。
---

# Doc Maintainer

AI向けドキュメントの SSOT 違反・表記ゆれ・構造問題を検出・修正する。PR概要とコミット差分の乖離チェックも行う。

## チェック項目（`/doc-audit` 対象）

| 種別 | 内容 | 例 |
|------|------|----|
| **SSOT違反** | 同じ内容が複数ファイルに存在する | awk スクリプトが SKILL.md と参照先 docs の両方にある |
| **パス表記ゆれ** | ファイル名のみ・短縮パス vs リポジトリルートからのフルパスが混在 | `doc-maintainer/SKILL.md` vs `.claude/skills/doc-maintainer/SKILL.md` |
| **構造問題** | 番号付きリストの途中に見出しが入る | 手順3の補足として H3 を置いてリストが途切れる |
| **無効参照** | 記述されたファイルパスや見出し名が存在しない | ExecPlan パスが archive 前のまま、削除した見出しへの参照が残る |
| **バージョン表記ゆれ** | 同一ドキュメント内でバージョン形式が混在 | `vX.X.X` と `release-1.3.0J` が同じファイルに混在 |
| **フォーマット違反** | ロードマップ項目の必須フィールド欠落 | `完了日:` 行がないタスク |
| **言語一貫性** | LLM制約ファイル内で記述言語が混在する | `codex-pr-rules.md` が英語ベースで日本語箇条書きが混在 |
| **Decision Log 齟齬** | ExecPlan の Decision Log が実装済み内容と矛盾する | 「PRマージ後に対応」と記載されているが既に実装済み |

## コマンド

### `/doc-audit [対象]`

対象ディレクトリ・ファイルを走査してチェック項目を検査し、問題を一覧表示する。

対象省略時は `.claude/skills/`、`AGENTS.md`、`CLAUDE.md`、`.agent/roadmap.md`、`.agent/PLANS.md` を対象とする。

**推奨タイミング:** ドキュメントファイルを変更したコミット前に実行し、Copilot レビューで指摘される前に問題を解消する。

**手順:**

1. 対象ファイルを読み込む
2. 各チェック項目を検査する
3. 問題を種別・重大度（高/中/低）・ファイル:行番号で一覧表示する
4. 修正方針を提示してユーザーに確認を求める

### `/doc-fix <問題番号|説明>`

`/doc-audit` で検出した問題を修正する。

**手順:**

1. 対象ファイルと修正内容を確認する
2. 修正を適用する
3. 修正後に同種の問題が残っていないか再確認する
4. コミットメッセージ案を提示する（実際のコミットはユーザー確認後）

### `/pr-sync <PR番号>`

PR概要（Summary・Test plan）と実際のコミット差分を照合し、乖離を検出・更新する。

コミットを重ねるうちに概要が古くなった場合や、PR作成後に方針が変わった場合に使う。

**手順:**

1. まず「`/pr-sync <PR番号>` を実行するか？ はい・いいえ」で確認する
2. `はい` の場合のみ、`gh pr view <PR番号> --json body` で現在の PR 概要を取得する
3. `gh pr diff <PR番号>` または `git log <base>..HEAD --oneline` で実際の変更内容を確認する
4. 以下の観点で乖離を検出する:
   - Summary に書かれた変更が実際の diff に存在するか
   - Summary に書かれていない重要な変更が diff に含まれていないか
   - Test plan のチェック項目が現在の変更内容と対応しているか
   - ファイルパスや件数などの具体的な記述が現状と一致しているか
5. 乖離箇所を列挙してユーザーに確認を求める
6. 確認後、`gh pr edit <PR番号> --body "..."` で更新する

**推奨タイミング:** PR 作成直後、および追加コミットのたびに実行する。