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 作成直後、および追加コミットのたびに実行する。