solo-audit

/audit

ナレッジベースの品質上の問題（フロントマターの欠落、リンク切れ、タグの不整合、孤立ファイル、網羅性の不足）を監査します。Markdown を多く含むあらゆるプロジェクトで動作します。

手順

1. $ARGUMENTS から対象範囲を解析します（省略可）。指定されている場合は、その範囲（例：「タグ」、「フロントマター」、「リンク」）に焦点を当てます。空の場合は、全体を監査します。

2. すべての Markdown ファイルを検索します： Glob を使って、一般的なコンテンツ以外のディレクトリ .venv/、node_modules/、.git/、archive/、.archive_old/ を除外し、すべての .md ファイルを検索します。

3. フロントマターを監査します： まず既存ファイルのサンプル（先頭の 10～20 件）を確認し、使用されているフロントマターのスキーマ（存在するフィールド、type と status で一般的な値）を特定します。次に、各 Markdown ファイルについて以下を確認します。

   • YAML フロントマターがある（--- で始まり、閉じる --- がある）
   • 必須フィールドがある：title、tags（および KB 全体で一貫して使われているその他のフィールド）
   • type と status の値（使用されている場合）が、検出したスキーマと一致している
   • tags が空でないリストである フロントマターがないファイルと、不完全または無効なフロントマターがあるファイルを記録します。

4. リンクを確認します： 内部リンク切れを探します。

   • Markdown リンク \[.*\]\(.*\.md\) を Grep で検索し、各リンク先ファイルが存在するか確認します。
   • プロジェクトにリンク確認用スクリプト（例：scripts/check_links.py）がある場合は、それも実行します。

5. タグの一貫性を監査します： Grep を使って、すべての .md ファイル内の tags: セクションを検索します。以下を確認します。

   • 類似したタグ（例：「ai」、「AI」、「artificial-intelligence」）
   • 1 回だけ使われているタグ（誤字の可能性があります）
   • 使用頻度が非常に高く、範囲が広すぎる可能性のあるタグ すべての一意なタグと使用回数を一覧にします。

6. 孤立ファイルを確認します： 他のファイルの related: フィールドで参照されていないファイルを特定します。存在するものの、他のファイルから一切相互参照されていないファイルは、孤立している可能性があります。

7. コンテンツの品質： アイデアや機会に関すると思われるドキュメント（検出した type フィールドまたはディレクトリの場所に基づく）を見つけ、以下を確認します。

   • draft 状態のまま 30 日を超えているドキュメント
   • 類似する他のドキュメントにある重要なメタデータフィールドが欠けているドキュメント
   • コンテンツが非常に少ない（フロントマターを除いて 100 語未満）ドキュメント

8. 網羅性の不足： 各ディレクトリのコンテンツを確認します。

   • 空またはほぼ空のディレクトリにフラグを立てます。
   • ファイルが 1～2 件しかないディレクトリを探します（コンテンツの追加が必要な可能性があります）。

9. レポートを出力します：

   ## KB Audit Report
   
   **Date:** [today]
   
   ### Summary
   - Total .md files: X
   - With frontmatter: X (X%)
   - Without frontmatter: X
   
   ### Frontmatter Issues
   | File | Issue |
   |------|-------|
   | path | Missing field: type |
   
   ### Broken Links
   [list of broken references]
   
   ### Tag Analysis
   - Total unique tags: X
   - Single-use tags: [list]
   - Potential duplicates: [list]
   
   ### Orphaned Files
   [files not referenced anywhere]
   
   ### Content Quality
   - Stale drafts (> 30 days): [list]
   - Missing metadata: [list]
   - Low-content files: [list]
   
   ### Coverage
   [directory analysis]
   
   ### Recommendations
   1. [specific action]
   2. [specific action]
   3. [specific action]
   

注意点

1. 1 回だけ使われているタグが、必ずしも誤字とは限りません — 1 回しか使われていないタグも、意図的な場合があります（例：特定のイベントを表す event-2026）。フラグは立てますが、文脈を確認せずに自動で統合しないでください。
2. 孤立ファイルが意図的なアーカイブの場合もあります — 3-inbox/ または 4-opportunities/ 内のファイルは、設計上単独で存在することがよくあります。方法論または原則のディレクトリにある孤立ファイルのみフラグを立ててください。
3. フロントマターのスキーマはディレクトリごとに異なる場合があります — 0-principles/ では type: principle、3-inbox/ では type: capture を使用します。スキーマはディレクトリごとに検出し、全体で単一のスキーマを強制しないでください。
4. related: フィールドだけでは参照を網羅できません — 有効な相互参照の多くは、YAML の related: 配列ではなく、インラインの Markdown リンク [text](path.md) として存在します。両方を確認してください。
5. 空のディレクトリがプレースホルダーの場合もあります — 5-active-projects/ や 6-companies/ は、設計上空のまま（自動化によってコンテンツが追加される）かもしれません。フラグを立てる前に registry.yaml または Makefile を確認してください。

よくある問題

Markdown ファイルが見つからない

原因： 間違ったディレクトリで実行しているか、すべてのファイルが除外されています。 対処法： ナレッジベースのルートにいることを確認してください。手順 2 の除外パターンを確認してください。

1 回しか使われていないタグが多すぎる

原因： ドキュメント間でタグの付け方に一貫性がありません。 対処法： 使用頻度の高いタグ一覧から標準タグを選びます。整理後に再度監査を実行してください。

フロントマターの検証エラー

原因： YAML の構文に問題があります（引用符がない、インデントが誤っているなど）。 対処法： --- の区切りがあることを確認してください。type: と status: の値は、検出された KB のスキーマに一致させてください。