compound-docs

compound-docs Skill

目的： 解決した問題を自動で文書化し、カテゴリ別に整理して検索可能な組織内ナレッジを構築します（問題の種類は enum で検証されます）。

概要

このスキルは、解決を確認した直後に問題の解決方法を記録し、今後のセッションで検索できる構造化ドキュメントを作成します。

整理方法： 単一ファイルのアーキテクチャです。各問題は、症状カテゴリのディレクトリにある 1 つの Markdown ファイルとして記録されます（例：docs/solutions/performance-issues/n-plus-one-briefs.md）。ファイルにはメタデータと検索性のために YAML フロントマターを使用します。

---

<critical_sequence name="documentation-capture" enforce_order="strict">

7 ステップのプロセス

### ステップ 1：解決の確認を検出する

次のフレーズの後に自動で呼び出します：

• 「うまくいきました」
• 「修正されました」
• 「今は動いています」
• 「問題は解決しました」
• 「これで直りました」

または手動で： /doc-fix コマンド

文書化するのは重要な問題のみです：

• 複数回の調査が必要だった
• 時間を要する複雑なデバッグだった
• 解決方法が自明ではなかった
• 今後のセッションに役立つ

次の問題は文書化しません：

• 単純なタイプミス
• 明白な構文エラー
• すぐに修正できる些細な問題

### ステップ 2：コンテキストを収集する

会話履歴から抽出します：

必須情報：

• モジュール名：問題が発生したモジュールまたはコンポーネント
• 症状：観察されたエラーや動作（エラーメッセージの正確な内容）
• 調査の試行：うまくいかなかったことと、その理由
• 根本原因：実際の問題に関する技術的な説明
• 解決方法：問題を解決した変更（コードや設定）
• 予防策：今後同様の問題を避ける方法

環境の詳細：

• Rails のバージョン
• ステージ（0～6 または実装後）
• OS のバージョン
• ファイルや行の参照

必須要件： 重要なコンテキスト（モジュール名、正確なエラー、ステージ、または解決手順）が不足している場合は、ユーザーに質問し、ステップ 3 に進む前に回答を待ちます：

I need a few details to document this properly:

1. Which module had this issue? [ModuleName]
2. What was the exact error message or symptom?
3. What stage were you in? (0-6 or post-implementation)

[Continue after user provides details]

### ステップ 3：既存のドキュメントを確認する

docs/solutions/ を検索し、類似の問題がないか確認します：

# Search by error message keywords
grep -r "exact error phrase" docs/solutions/

# Search by symptom category
ls docs/solutions/[category]/

類似の問題が見つかった場合：

次に、選択肢を提示します：

Found similar issue: docs/solutions/[path]

What's next?
1. Create new doc with cross-reference (recommended)
2. Update existing doc (only if same root cause)
3. Other

Choose (1-3): _

ユーザーの回答を待ち、選択された操作を実行します。

それ以外の場合（類似の問題が見つからない場合）：

ステップ 4 に直接進みます（ユーザーとのやり取りは不要です）。

### ステップ 4：ファイル名を生成する

形式：[sanitized-symptom]-[module]-[YYYYMMDD].md

サニタイズのルール：

• 小文字にする
• スペースをハイフンに置き換える
• ハイフン以外の特殊文字を削除する
• 適切な長さに切り詰める（80 文字未満）

例：

• missing-include-BriefSystem-20251110.md
• parameter-not-saving-state-EmailProcessing-20251110.md
• webview-crash-on-resize-Assistant-20251110.md

### ステップ 5：YAML スキーマを検証する

重要： すべてのドキュメントに、enum による検証を含む、検証済みの YAML フロントマターが必要です。

<validation_gate name="yaml-schema" blocking="true">

スキーマに照らして検証します： schema.yaml を読み込み、yaml-schema.md で定義されている enum 値に基づいて問題を分類します。すべての必須フィールドが存在し、許可された値と完全に一致することを確認します。

検証に失敗した場合はブロックします：

❌ YAML validation failed

Errors:
- problem_type: must be one of schema enums, got "compilation_error"
- severity: must be one of [critical, high, medium, low], got "invalid"
- symptoms: must be array with 1-5 items, got string

Please provide corrected values.

ゲートの適用： YAML フロントマターが schema.yaml で定義されたすべての検証ルールに合格するまで、ステップ 6（ドキュメントの作成）に進んではいけません。

</validation_gate>

### ステップ 6：ドキュメントを作成する

problem_type からカテゴリを判定します： yaml-schema.md（49～61 行目）で定義されているカテゴリーマッピングを使用します。

ドキュメントファイルを作成します：

PROBLEM_TYPE="[from validated YAML]"
CATEGORY="[mapped from problem_type]"
FILENAME="[generated-filename].md"
DOC_PATH="docs/solutions/${CATEGORY}/${FILENAME}"

# Create directory if needed
mkdir -p "docs/solutions/${CATEGORY}"

# Write documentation using template from assets/resolution-template.md
# (Content populated with Step 2 context and validated YAML frontmatter)

結果：

• カテゴリーディレクトリ内に単一のファイルを作成
• Enum 検証により、一貫した分類を保証

ドキュメントを作成します： assets/resolution-template.md の構成に、ステップ 2 で収集したコンテキストと、ステップ 5 で検証した YAML フロントマターを反映します。

### ステップ 7：相互参照と重要なパターンの検出

ステップ 3 で類似する問題が見つかった場合：

既存のドキュメントを更新します：

# Add Related Issues link to similar doc
echo "- See also: [$FILENAME]($REAL_FILE)" >> [similar-doc.md]

新しいドキュメントを更新します： ステップ 6 ですでに相互参照が含まれています。

該当する場合はパターンを更新します：

これがよくあるパターン（類似する問題が 3 件以上）の場合：

# Add to docs/solutions/patterns/common-solutions.md
cat >> docs/solutions/patterns/common-solutions.md << 'EOF'

## [Pattern Name]

**Common symptom:** [Description]
**Root cause:** [Technical explanation]
**Solution pattern:** [General approach]

**Examples:**
- [Link to doc 1]
- [Link to doc 2]
- [Link to doc 3]
EOF

重要なパターンの検出（任意の事前提案）：

この問題に、重要である可能性を示す自動判定の指標がある場合：

• 重大度：YAML で critical
• 複数のモジュール、または基礎段階（ステージ 2 または 3）に影響する
• 解決策が直感的ではない

その場合、意思決定メニュー（ステップ 8）に次の注記を追加します：

💡 This might be worth adding to Required Reading (Option 2)

ただし、決して自動的に昇格させないでください。意思決定メニューのオプション 2 からユーザーが決定します。

重要なパターンを追加するためのテンプレート：

ユーザーがオプション 2（必読事項に追加）を選択した場合は、assets/critical-pattern-template.md のテンプレートを使ってパターン項目を構成します。docs/solutions/patterns/critical-patterns.md にある既存のパターンに基づいて、連番を付けます。

</critical_sequence>

---

<decision_gate name="post-documentation" wait_for_user="true">

記録後の意思決定メニュー

ドキュメントの作成に成功したら、選択肢を提示し、ユーザーの応答を待ちます：

✓ Solution documented

File created:
- docs/solutions/[category]/[filename].md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other

応答への対応：

オプション 1：ワークフローを続行する

• 呼び出し元のスキル／ワークフローに戻る
• ドキュメント作成は完了です

オプション 2：必読事項に追加する ⭐ 重要なパターンの主要な追加方法

次の場合にユーザーが選択します：

• システムが異なるモジュールで同じミスを複数回起こした
• 解決策は直感的ではないものの、毎回従う必要がある
• 基礎となる要件（Rails、Rails API、スレッド処理など）

実行内容：

1. ドキュメントからパターンを抽出する
2. コード例を使って ❌ 誤りと ✅ 正しい例の形式にする
3. docs/solutions/patterns/critical-patterns.md に追加する
4. このドキュメントへの相互参照を追加する
5. 確認メッセージを表示する：「✓ 必読事項に追加しました。すべてのサブエージェントはコード生成の前にこのパターンを確認します。」

オプション 3：関連する問題をリンクする

• 次のように尋ねます：「どのドキュメントをリンクしますか？（ファイル名を入力するか、説明してください）」
• docs/solutions/ 内のドキュメントを検索する
• 両方のドキュメントに相互参照を追加する
• 確認メッセージを表示する：「✓ 相互参照を追加しました」

オプション 4：既存のスキルに追加する

記録した解決策が既存の学習スキルに関連する場合に、ユーザーが選択します：

実行内容：

1. 次のように尋ねます：「どのスキルですか？（hotwire-native など）」
2. 更新するリファレンスファイル（resources.md、patterns.md、examples.md のいずれか）を特定する
3. 適切なセクションにリンクと簡単な説明を追加する
4. 確認メッセージを表示する：「✓ [skill-name] スキルの [file] に追加しました」

例：Hotwire Native の Tailwind バリアントの解決策の場合：

• hotwire-native/references/resources.md の「Project-Specific Resources」に追加する
• 解決策のドキュメントへのリンクを hotwire-native/references/examples.md に追加する

オプション 5：新しいスキルを作成する

解決策が新しい学習分野の始まりにあたる場合に、ユーザーが選択します：

実行内容：

1. 次のように尋ねます：「新しいスキルの名前は何にしますか？（例：stripe-billing、email-processing）」
2. python3 .claude/skills/skill-creator/scripts/init_skill.py [skill-name] を実行する
3. この解決策を最初の例として、初期リファレンスファイルを作成する
4. 確認メッセージを表示する：「✓ この解決策を最初の例とする新しい [skill-name] スキルを作成しました」

オプション 6：ドキュメントを表示する

• 作成したドキュメントを表示する
• 再度、意思決定メニューを提示する

オプション 7：その他

• 何をしたいか尋ねる

</decision_gate>

---

<integration_protocol>

統合ポイント

呼び出し元：

• /compound コマンド（主要なインターフェース）
• 解決策が確認された後、会話中に手動で呼び出す
• 「うまくいった」「直った」などの確認フレーズを検出して起動することもできます

呼び出し先：

• なし（ターミナルスキル。他のスキルには委譲しません）

引き継ぎ時の要件： ドキュメント作成に必要なすべてのコンテキストが、呼び出し前に会話履歴に含まれている必要があります。

</integration_protocol>

---

<success_criteria>

成功基準

次のすべてを満たした場合、ドキュメント作成は成功です。

• ✅ YAML frontmatter が検証済み（必須フィールドがすべて揃い、形式が正しい）
• ✅ ファイルが docs/solutions/[category]/[filename].md に作成されている
• ✅ 列挙値が schema.yaml と正確に一致している
• ✅ 解決策のセクションにコード例が含まれている
• ✅ 関連する問題が見つかった場合、相互参照が追加されている
• ✅ ユーザーに選択メニューを提示し、操作が確認されている

</success_criteria>

---

エラー処理

コンテキストが不足している場合：

• 不足している詳細をユーザーに尋ねます
• 重要な情報が提供されるまで進めません

YAML の検証に失敗した場合：

• 具体的なエラーを表示します
• 修正した値での再試行を提示します
• 有効になるまで処理をブロックします

類似する問題の判断が難しい場合：

• 複数の候補を提示します
• 新しいドキュメントの作成、既存ドキュメントの更新、重複としてのリンクからユーザーに選んでもらいます

モジュールがモジュールのドキュメントに記載されていない場合：

• 警告しますが、処理はブロックしません
• ドキュメント作成を続行します
• 「記載がない場合は、[Module] をモジュールのドキュメントに追加してください」と提案します

---

実行ガイドライン

必ず行うこと：

• YAML frontmatter を検証する（ステップ 5 の検証ゲートに従い、無効な場合はブロックする）
• 会話から正確なエラーメッセージを抽出する
• 解決策のセクションにコード例を含める
• ファイルを書き込む前にディレクトリを作成する（mkdir -p）
• 重要なコンテキストが不足している場合は、ユーザーに尋ねて返答を待つ

絶対に行わないこと：

• YAML の検証を省略する（検証ゲートでは処理がブロックされます）
• 曖昧な説明を使う（検索しにくくなります）
• コード例や相互参照を省略する

---

品質ガイドライン

優れたドキュメントに含まれるもの：

• ✅ 正確なエラーメッセージ（出力からコピー＆ペースト）
• ✅ 具体的なファイル名と行番号への参照
• ✅ 観察可能な症状（解釈ではなく、実際に確認したこと）
• ✅ 失敗した試行の記録（誤った対応を避けるのに役立ちます）
• ✅ 技術的な説明（「何を」だけでなく「なぜ」も記載）
• ✅ コード例（該当する場合は変更前と変更後）
• ✅ 予防策（早期に検出する方法）
• ✅ 相互参照（関連する問題）

避けること：

• ❌ 曖昧な説明（「何かがおかしかった」）
• ❌ 技術的な詳細の欠如（「コードを修正した」）
• ❌ コンテキストの欠如（どのバージョンか？ どのファイルか？）
• ❌ コードの羅列だけ（動作する理由を説明する）
• ❌ 予防策がない
• ❌ 相互参照がない

---

シナリオ例

ユーザー：「うまくいきました！ N+1 クエリが解消されました。」

スキルの起動：

1. 確認を検出：「うまくいきました！」をトリガーに自動起動
2. コンテキストを収集：
   • モジュール：Brief System
   • 症状：Brief の生成に 5 秒以上かかり、メールスレッドの読み込みで N+1 クエリが発生
   • 失敗した試行：ページネーションを追加（効果なし）、バックグラウンドジョブのパフォーマンスを確認
   • 解決策：Brief モデルに includes(:emails) を使ったイーガーローディングを追加
   • 根本原因：イーガーローディングがなく、メールスレッドごとに個別のデータベースクエリが発生
3. **既存の問題を確認：**類似する問題は見つかりませんでした
4. ファイル名を生成：n-plus-one-brief-generation-BriefSystem-20251110.md
5. YAML を検証：

   module: Brief System
   date: 2025-11-10
   problem_type: performance_issue
   component: rails_model
   symptoms:
     - "N+1 query when loading email threads"
     - "Brief generation taking >5 seconds"
   root_cause: missing_include
   severity: high
   tags: [n-plus-one, eager-loading, performance]
   

   ✅ 有効
6. ドキュメントを作成：
   • docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md
7. **相互参照：**不要（類似する問題がないため）

出力：

✓ Solution documented

File created:
- docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other

---

今後の機能強化

フェーズ 7 の対象外ですが、今後の候補：

• 日付範囲による検索
• 重大度による絞り込み
• タグベースの検索インターフェース
• 指標（よくある問題、解決までの時間）
• 共有可能な形式へのエクスポート（コミュニティでのナレッジ共有）
• コミュニティの解決策のインポート