audit-docs

ドキュメント監査

「ドキュメントは今も実態と一致しているか？」を確認する、まず読む監査です。調査結果のレポートを作成し、ドキュメントを黙って書き換えることはありません。

ターンの契約 — ターンを終了する前に確認する

✓ The AUDIT DOCS fixed-format report was printed, ending in `Decision: PASS | FAIL`
✓ No doc was rewritten without explicit --fix / user go-ahead
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

チェックが入っていない項目がある状態でターンを終了しようとしていますか？そのターンはまだ完了していません。先に未完了の項目を完了してください（能力の低いモデルはドキュメント末尾の作業を忘れがちなため、このリストを最初に置いています）。

使用するタイミング

• リリースやマイルストーンの前、複数の機能や修正をマージした後、またはドキュメント一式がコードやイシューと乖離している可能性がある場合。

ステップ 0 — プロジェクトを確認する（必ず最初に実行）

エージェントガイドの ワークフローの規約 と ドキュメントマップ に従い、そのうえでこのスキルに必要なもの（ロードマップ、修正インデックスとテンプレート、機能フォルダーの構成）を読みます。マップには、確認すべきリンクと不変条件が示されています。

チェック項目

以下を実行して、それぞれの指摘事項を収集してください（パス／行番号／課題番号を引用してください）。

1. ロードマップと機能フォルダーの対応。 すべての docs/features/<NN>-<slug>/ がロードマップに記載されており、ロードマップのすべての項目にフォルダーがある（または「予定」と明記されている）こと。
2. 機能の依存関係。 SPEC の Depends on／Branch フィールドが有効であること、依存関係の循環がないこと、順序がロードマップと一致していること。
3. 修正インデックスの健全性。 すべての項目がオープンな課題と未マージのブランチに対応していること。課題がクローズ済み、または PR がマージ済みの項目（削除されているべきもの）を指摘してください。インデックスにないオープンな修正ブランチも指摘してください。
4. ドキュメントマップのリンク切れ。 マップが参照するすべてのファイルが存在すること。「予定、未作成」の項目には、ドリフトと誤認されないようフラグを付けてください。
5. ドキュメント内リンク切れ。 相対リンク／アンカーが実在するファイル／セクションを指していること。
6. 課題への参照。 #N を参照する受け入れ条件／既知の問題の行が、注記なしに長期間クローズされている課題を指していないこと。
7. 言語と命名規則。 成果物がプロジェクトのドキュメント言語で書かれていること（このリポジトリでは英語）。ファイル／ディレクトリ名が規則に従っていること（例：TS ファイルは kebab-case、コンポーネントは PascalCase）。
8. 不変条件タグ。 プロジェクトで不変条件／決定 ID（例：INV-／D-／KI-）を使っている場合、参照されている ID が記載どおりに存在することを抜き取り確認してください。
9. done 行の PR リンク整合性。 ロードマップの行および修正インデックスの項目で、ステータスが done のものすべてに、リンク付きの PR 参照（done · [#<pr>](<pr-url>)）があること。done のみの行については、Forge で PR を検索し（gh pr list --state all --head feat/<NN>-<slug> またはタイトルで検索）、行の更新案を提示してください。PR がまったく見つからない done は重大度 HIGH です（その単位が完了処理されていない可能性があります）。

ワークフロー規律（チェック 10～14） — 実行担当者のスキルでは書き込み時にこれらを適用します。この監査では実際に守られていたことを検証します。各チェックは機械的に行います。推測せず、指定されたコマンドを実行してください。

10. フェーズの命名。 grep -rnE '\bS[0-9]+\b|\bStep [0-9]' docs/features/*/{PLAN,TASKS,progress}.md の結果が空であること — 計画では「フェーズ」として P1、P2、… のみを使います。該当があれば LOW（名称を変更）とし、実行担当者の引数が引き続き解決可能であることも確認してください。
11. フェーズごとのドキュメント規律。 M/L の機能のうち in-progress／done のものすべてについて、完了したフェーズが TASKS.md でチェック済みであること、progress.md に完了したフェーズごとにエントリーが1つあること、（現行テンプレートに基づいて計画された機能では）最終フェーズの最後に文字列どおりの完了処理タスク（PR を開いて URL を出力する、ロードマップの行にリンクする、リンクを含むコミットをプッシュする）があること。タスクが未チェックの done 機能、または progress.md に記載のないフェーズは HIGH です。
12. Forge に対するブランチと PR の規律。 done の単位すべてについて、その PR が存在し、デフォルトブランチを対象とし、本文が空でなく、単位が課題起点の場合（SPEC が課題を参照している場合）に Closes #<n> を含んでいること。また、最近のデフォルトブランチの履歴（git log --first-parent）を調べ、機能／修正に関する変更が PR なしで直接コミットされていないか確認してください。該当する場合は HIGH です。
13. 生成ドキュメントの出典（ドキュメントマップに Docs site ブロックがある場合のみ。ない場合は n/a と記載）。 指定されたコンテンツディレクトリを調べ、孤立ページがないか確認してください。それぞれについて、(a) source-unit がロードマップまたは修正インデックスに存在すること — 該当がなければ孤立（low：削除または帰属の変更を提案）、(b) 単位の PR がページの updated 日付より後にマージされ、ページの対象パスに触れるコミットを含んでいること — 該当するページは古い（LOW：提案）。指摘ごとにページのパスと単位を引用してください。
14. コミット形式と依存関係の規律。 単位のブランチからコミットを抜き取り確認し、<type>(<scope>): <summary> の Conventional Commits 形式に従っていること（違反は LOW）。in-progress／done の行すべてについて、Depends on: の依存関係の上流がマージ済みであること。未マージの依存先に基づいている単位は、decisions.md にユーザー強制の上書き（--force）が記録されていない限り HIGH です。記録されている場合は LOW に引き下げます（リスクを文書化）。

プロジェクトに存在する構成に合わせてリストを調整してください。存在しない構成のチェックは省略し、その旨を記載してください。

プロセス

1. grep、ファイルの読み取り、forge CLI を使って調査し、チェックを実行します （Workflow の規約に従います。例では gh を使用します）。

2. 指摘レポートを作成します — 次の内容を正確に返してください（出力形式は固定です）。

   AUDIT DOCS — scope: <docs tree / roadmap / fix index / issues checked>
   
   | # | Check (1-14) | Finding | Sev | Evidence | Proposed fix |
   |---|-------------|---------|-----|----------|--------------|
   | 1 | <which>     | <what>  | high|low | <path:line / #issue> | <smallest action> |
   
   Checks run: <n>/14 (skipped: <which + why — absent structures only>)
   Summary: <1-2 sentences>
   Decision: PASS | FAIL   (FAIL if any high-severity finding is open)
   

   重大度：high = 誤解を招く、または壊れている、low = 見た目上の問題。 この凡例で定義されているのは high と low のみです。

3. 依頼があった場合のみ修正します。 明示的に --fix を指定するか、ユーザーから許可を得た場合は、リスクの低い修正を適用します（マージ済みの fix-index 行の削除、リンク切れの修正、ロードマップの未登録項目の追加、done のみの行への検証済み PR リンクの追加）。判断が必要なものはユーザーに委ねます。

ガードレール

• まず読み取りを行い、依頼なしにドキュメントを一括で書き換えないでください。
• 実際の不整合と、意図的に「予定／延期」とされている項目を区別してください — 意図的なトレードオフをエラーとして報告しないでください。
• 変更は最小限にとどめ、ドキュメントの範囲内に限定してください。コードや動作は変更しないでください。

移植性（Claude Code 以外のエージェント向け）

ワークフローが契約です。Claude Code の機能は利便性のためのものです。エージェントに機能がない場合は、その機能が可能にする手順を省略せず、代替手段を適用してください。

• スラッシュコマンドメニューがない場合 — このスキルで /<skill> と記載されている箇所では、そのスキルの SKILL.md を開き（エージェントにスキルがインストールされている場所を参照）、新しい会話で内容に忠実に従ってください。引き継ぎではクリーンなコンテキストが前提となります。
• スキルごとの model:／effort: がない場合 — どのスキルもティアを固定していません。ティアは自分で選択してください。これらはほとんどが機械的なドキュメント間チェックなので、中位のモデルで十分です。詳細な監査には、最も高性能なモデルを使用してください。

他のスキルとの関係

• unit-lane（監査対象のドキュメントを作成するスキル）および triage-issue（fix index の正確性を保つスキル）を補完します。
• 単独でいつでも実行できます。先に実行が必要なスキルはありません。

完了条件

• 重大度順の指摘レポートが作成され、承認されたリスクの低い修正があれば適用されています — 実際に延期されている項目はそのままにし、延期項目として明記されています。

• 最後に → Next: ブロックが出力されています。

  → Next: apply the approved low-risk fixes, then re-run /audit-docs to confirm clean
    · real drift (not cosmetic) → /triage-issue   · a concrete defect → /unit-lane --fix <n>
    · already clean → nothing to do