| 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 レビューで指摘される前に問題を解消する。
手順:
- 対象ファイルを読み込む
- 各チェック項目を検査する
- 問題を種別・重大度（高/中/低）・ファイル:行番号で一覧表示する
- 修正方針を提示してユーザーに確認を求める
/doc-fix <問題番号|説明>
/doc-audit で検出した問題を修正する。
手順:
- 対象ファイルと修正内容を確認する
- 修正を適用する
- 修正後に同種の問題が残っていないか再確認する
- コミットメッセージ案を提示する（実際のコミットはユーザー確認後）
/pr-sync <PR番号>
PR概要（Summary・Test plan）と実際のコミット差分を照合し、乖離を検出・更新する。
コミットを重ねるうちに概要が古くなった場合や、PR作成後に方針が変わった場合に使う。
手順:
- まず「
/pr-sync <PR番号> を実行するか？ はい・いいえ」で確認する
はい の場合のみ、gh pr view <PR番号> --json body で現在の PR 概要を取得するgh pr diff <PR番号> または git log <base>..HEAD --oneline で実際の変更内容を確認する- 以下の観点で乖離を検出する:
- Summary に書かれた変更が実際の diff に存在するか
- Summary に書かれていない重要な変更が diff に含まれていないか
- Test plan のチェック項目が現在の変更内容と対応しているか
- ファイルパスや件数などの具体的な記述が現状と一致しているか
- 乖離箇所を列挙してユーザーに確認を求める
- 確認後、
gh pr edit <PR番号> --body "..." で更新する
推奨タイミング: PR 作成直後、および追加コミットのたびに実行する。
