doc-maintenance

ドキュメントメンテナンススキル

ドキュメントの記載と実装のずれを検出し、PR で修正します。全面的な書き直しや不要な変更は行いません。

使用する場面

• 定期的なドキュメントレビュー（例：毎週、またはリリース後）
• 大規模な機能のマージ後
• 「ドキュメントは最新ですか？」と聞かれたとき
• README／SPEC／PRODUCT の正確性を監査するよう依頼されたとき

対象ドキュメント

ドキュメント	パス	確認する内容
README	README.md	機能一覧表、ロードマップ、クイックスタート、「概要」の正確性、「連携するもの」一覧表
SPEC	doc/SPEC.md	「未対応」とする誤った記述がないこと、主要なモデル／スキーマの正確性
PRODUCT	doc/PRODUCT.md	基本概念、機能一覧、原則の正確性

対象外：DEVELOPING.md、DATABASE.md、CLI.md、doc/plans/、スキルファイル、 リリースノート。これらは開発者向け、または一時的なものであり、ユーザー向けの 誤解を招くリスクは低いためです。

ワークフロー

ステップ 1 — 変更点を検出する

最後にレビューした位置を確認します。

# Read the last-reviewed commit SHA
CURSOR_FILE=".doc-review-cursor"
if [ -f "$CURSOR_FILE" ]; then
  LAST_SHA=$(cat "$CURSOR_FILE" | head -1)
else
  # First run: look back 60 days
  LAST_SHA=$(git log --format="%H" --after="60 days ago" --reverse | head -1)
fi

次に、その位置以降のコミットを収集します。

git log "$LAST_SHA"..HEAD --oneline --no-merges

ステップ 2 — 変更を分類する

コミットメッセージと変更されたファイルを確認し、次のように分類します。

• 機能 — 新しい機能（キーワード：feat、add、implement、support）
• 破壊的変更 — 削除または名前変更（キーワード：remove、breaking、drop、rename）
• 構造的変更 — 新しいディレクトリ、設定の変更、新しいアダプター、新しい CLI コマンド

対象外： リファクタリング、テストのみの変更、CI 設定、依存関係の更新、ドキュメントのみの 変更、スタイル／フォーマットの変更を含むコミット。これらはドキュメントの正確性に影響しません。

判断が難しい場合は、実際の差分を確認します。「refactor: X」というタイトルの コミットでも、新しい公開 API が追加されていれば機能として扱います。

ステップ 3 — 変更の概要を作成する

次のような簡潔な一覧を作成します。

Since last review (<sha>, <date>):
- FEATURE: Plugin system merged (runtime, SDK, CLI, slots, event bridge)
- FEATURE: Project archiving added
- BREAKING: Removed legacy webhook adapter
- STRUCTURAL: New .agents/skills/ directory convention

特筆すべき変更がない場合は、ステップ 7（カーソルを更新して終了）に進みます。

ステップ 4 — 対象ドキュメントを監査する

各対象ドキュメントを最後まで読み、変更の概要と照合します。次の点を確認してください。

1. 偽陰性 — リリース済みの主要機能がまったく記載されていない
2. 偽陽性 — すでにリリース済みの機能が「近日公開」／「ロードマップ」／「予定」／ 「未対応」／「TBD」として記載されている
3. クイックスタートの正確性 — インストールコマンド、前提条件、起動手順が 現在も正しい（README のみ）
4. 機能一覧の正確性 — 機能セクションに現在の機能が反映されている（README のみ）
5. 連携情報の正確性 — 対応するアダプター／連携が正しく記載されている

構造化されたチェックリストとして references/audit-checklist.md を使用します。 各機能領域の確認箇所は references/section-map.md で確認します。

ステップ 5 — ブランチを作成し、最小限の編集を適用する

# Create a branch for the doc updates
BRANCH="docs/maintenance-$(date +%Y%m%d)"
git checkout -b "$BRANCH"

ずれを修正するために必要な編集のみを適用します。次のルールに従ってください。

• パッチは最小限にします。 不正確な記述を修正し、セクションを書き直さないでください。
• 文体とスタイルを維持します。 各ドキュメントの既存のトーンに合わせます。
• 体裁だけの変更は行いません。 事実の修正に含まれる場合を除き、誤字の修正、表の再フォーマット、 セクションの再構成は行わないでください。
• 新しいセクションは追加しません。 機能に新しいセクションが丸ごと必要な場合は、メンテナンス作業では追加せず、 フォローアップとして PR の説明に記載します。
• ロードマップ項目： リリース済みの機能はロードマップから移します。適切な既存セクションに記載がなければ、 簡潔に追記します。長い説明は追加しないでください。

ステップ 6 — PR を作成する

変更をコミットして PR を作成します。

git add README.md doc/SPEC.md doc/PRODUCT.md .doc-review-cursor
git commit -m "docs: update documentation for accuracy

- [list each fix briefly]

Co-Authored-By: Paperclip <[email protected]>"

git push -u origin "$BRANCH"

gh pr create \
  --title "docs: periodic documentation accuracy update" \
  --body "$(cat <<'EOF'
## Summary
Automated doc maintenance pass. Fixes documentation drift detected since
last review.

### Changes
- [list each fix]

### Change summary (since last review)
- [list notable code changes that triggered doc updates]

## Review notes
- Only factual accuracy fixes — no style/cosmetic changes
- Preserves existing voice and structure
- Larger doc additions (new sections, tutorials) noted as follow-ups

🤖 Generated by doc-maintenance skill
EOF
)"

ステップ 7 — カーソルを更新する

編集の有無にかかわらず、監査が正常に完了したらカーソルを更新します。

git rev-parse HEAD > .doc-review-cursor

編集を行った場合、カーソルの更新はすでに PR ブランチにコミットされています。編集が不要だった場合は、 現在のブランチにカーソルの更新をコミットします。

変更分類ルール

シグナル	カテゴリ	ドキュメントの更新が必要か
メッセージに feat:、add、implement、support が含まれる	機能	ユーザー向けの場合は必要
メッセージに remove、drop、breaking、!: が含まれる	破壊的変更	必要
新しいトップレベルディレクトリまたは設定ファイル	構造	場合による
fix:、bugfix	修正	不要（ドキュメントに記載された動作が変わる場合を除く）
refactor:、chore:、ci:、test:	メンテナンス	不要
docs:	ドキュメントの変更	不要（すでに対応済み）
依存関係のバージョン更新のみ	メンテナンス	不要

パッチのスタイルガイド

• 文章ではなく、事実を修正します
• ロードマップの項目を削除する場合は、空白を残さず、箇条書き全体を削除します
• 機能についての記載を追加する場合は、周囲の項目と形式を合わせます （例：機能が表に記載されている場合は、表の行を追加します）
• README の変更は特に最小限に抑えます。頻繁に変更すべきではありません
• SPEC/PRODUCT では、新しい記述を追加するより、既存の記述を更新することを優先します （例：「V1 ではサポートされていません」を「X 経由でサポートされています」に変更する方が、新しいセクションを追加するより望ましいです）

出力

スキルの完了時に、以下を報告します。

• スキャンしたコミット数
• 見つかった注目すべき変更の数
• 実施したドキュメント編集の数と対象ファイル
• PR リンク（編集を行った場合）
• さらに大規模なドキュメント作業が必要なフォローアップ項目