gotchas-curator

name	gotchas-curator
description	Capture learnings, edge cases, and pitfalls from completed tasks and maintain Gotchas sections in Agent Skills for Memory Persistence. Use when finishing a task, resolving a bug, completing a review, or when an agent made a mistake that should be prevented in future sessions.
metadata	{"author":"coreclaw","version":"1.0"}

Gotchas Curator

タスク完了時やエージェントのミス発生時に学びを収集し、関連スキルの Gotchas セクションに反映するスキル。Harness 7軸の Memory Persistence を実践する。

収集手順

1. 対象イベントを特定:

   • エージェントのミスを修正した
   • 予期しない動作が発生した
   • ワークアラウンドが必要だった
   • レビューで改善点が見つかった
   • タスクが完了した

2. 学びを構造化:

   • 何が起きたか: 具体的な状況の説明
   • なぜ問題か: 影響範囲と深刻度
   • どう防ぐか: 具体的な対策（コマンド、ルール、チェック）
   • 関連スキル: この Gotcha を追記すべきスキル名

3. Gotcha エントリを生成:

   • 1項目 = 1〜2行で完結
   • 具体的なコマンド、ファイル名、設定値を含める
   • 汎用的な注意事項ではなくプロジェクト固有の知識を記載

4. 関連スキルの Gotchas セクションに追記

5. 重複チェック:

   • 同じ内容の既存 Gotcha がないか確認
   • ある場合は統合または詳細化

良い Gotcha の例

## Gotchas

# ✅ 具体的で実行可能
- `users` テーブルはソフトデリートを使用。クエリには必ず
  `WHERE deleted_at IS NULL` を含めること
- JWT トークンの `exp` クレームなしのトークンを許容してはならない。
  必ず有効期限を検証すること

# ❌ 汎用的で価値が低い
- セキュリティに注意すること
- テストを忘れないこと

蓄積先の優先順位

1. 関連する SKILL.md の Gotchas セクション — 最優先。スキル起動時に自動読み込みされる
2. copilot-instructions.md — プロジェクト全体に適用すべきルールの場合
3. .github/learnings/ — スキルに紐づかない汎用的な学びの場合

コンパクション耐性

Gotchas はファイルに書き出されるため、セッションのコンパクション後も保持される。 以下のものはコンパクションで失われるため、重要なものは必ずファイルに書き出すこと:

✅ 保持される	❌ 失われる
SKILL.md の Gotchas	セッション中の推論・分析
ファイルに書き出した学び	過去に読んだファイル内容
Git にコミットした変更	ツール呼び出し履歴

Gotchas

• Gotcha は「汎用的な注意」ではなく「プロジェクト固有の落とし穴」を書く。LLM は一般的な知識をすでに持っている
• 同じ Gotcha を複数のスキルに重複記載すると保守コストが増大。最も関連性の高い1箇所に書く
• Gotchas セクションが10項目を超えたら、カテゴリ分け（例: DB関連、API関連、認証関連）を検討する
• 学びの収集タイミングは「ミス発生直後」が最も効果的。タスク完了後にまとめて振り返ると詳細を忘れる
• Gotcha の追記後は対象スキルが500行以内に収まっているか確認すること

検証ループ

1. Gotcha エントリを生成
2. チェック:
   • 具体的なコマンド・ファイル名・設定値が含まれるか
   • 1〜2行で完結しているか
   • 既存の Gotcha と重複していないか
   • 追記先スキルが500行以内に収まるか
3. 不合格なら修正
4. 合格後に追記を実行