athena

Athena — アクティブなナレッジインテリジェンス

Mine → Grow → Defrag サイクルを実行して、ナレッジのフライホイールを健全に保ちます。

このスキルでできること

フライホイールは学びを受動的に記録します（/retro、/post-mortem 経由）。Athena は、まだ抽出されていないシグナルを積極的に掘り起こし、既存の学びを現在のコードに照らして検証し、ドメインをまたぐ知見を統合し、古くなった成果物や重複した成果物を整理することで、ループを閉じます。

使用するタイミング： 進化サイクルの前、開発が集中した後、または毎週です。Athena は非破壊的です。既存の学びを変更せず、変更を提案します。

出力： .agents/athena/YYYY-MM-DD-report.md

実行手順

Step 1 — Mine：シグナルを抽出する

機械的な抽出を実行します。Mine は git 履歴、.agents/research/、コードの複雑度が高い箇所をスキャンし、学びとしてまだ記録されていないパターンを探します。

ao mine --since 26h                    # default: all sources, last 26h
ao mine --since 7d --sources git,agents  # wider window, specific sources

.agents/mine/latest.json を読み込み、同時変更クラスター（一緒に変更されるファイル）、孤立した調査結果（参照されていない .agents/research/ ファイル）、複雑度の高い箇所（最近編集された、CC 値の高い関数）を抽出します。

フォールバック（ao CLI がない場合）： git log --since="7 days ago" --name-only を使って、繰り返し現れるファイルのグループを見つけます。.agents/research/*.md を一覧表示し、学びから参照されているか確認します。

初期信頼度を割り当てます。 抽出した新しい学びの候補それぞれに、証拠の強さに基づいて信頼度スコアを割り当てます。

証拠	スコア	根拠
単一セッションでの観察	0.3	逸話的 — 一度確認しただけで、一般化できない可能性があります
ユーザーによる明示的な訂正、または事後検証での発見	0.5	実証済み — ユーザーによって検証されたシグナルです
2 回以上のセッションで観察されたパターン	0.6	繰り返し確認 — 偶然ではなく、実際のパターンである可能性が高いです
複数のセッションまたはプロジェクトで検証済み	0.7	強い — 自動適用しても安全です
実戦で十分に検証され、反証されたことがない	0.9	ほぼ確実 — 常に適用します

また、scope タグも割り当てます。project:<name>（プロジェクト固有）、language:<lang>（言語の規約）、または global（普遍的なパターン）です。パターンが明らかに言語またはツールに普遍的でない限り、project:<current> をデフォルトにします。

信頼度と scope を学びのフロントマターに記述します。

---
title: "Learning title"
confidence: 0.3
scope: project:agentops
observed_in:
  - session: "YYYY-MM-DD"
    context: "Brief description of observation"
---

Step 2 — 成長：LLM による統合

これは推論フェーズです。各サブステップをツール呼び出しで実行します。

フライホイールの健全性診断： σ（一貫性）、ρ（速度）、δ（減衰）を計算し、脱出速度の状態を報告します。測定コマンドと修正アクションについては、references/flywheel-diagnostics.md を参照してください。

2a. 主要な学びを検証し、信頼度を調整する

.agents/learnings/ から最も新しいファイルを5つ選択します。それぞれについて：

1. 学びのファイルを読みます（confidence と scope のフロントマターを含む）
2. 関数またはファイルパスが記載されている場合は、Read を使ってコードがまだ存在するか確認します
3. 検証済み（一致）、古くなっている（変更済み）、または矛盾（反対の内容）のいずれかに分類します
4. 検証結果に基づいて信頼度を調整します：
   • 検証済みで、現在も正確：+0.1（上限 0.9）
   • 古くなっているが、一部は正しい：変更なし（要確認としてマーク）
   • 現在のコードと矛盾：-0.2（下限 0.1、削除対象としてフラグを設定）
   • 新しいプロジェクトでパターンを検証：+0.15
   • 30日以上参照されていない：-0.05（時間経過による減衰）
   • 90日以上参照されていない：-0.1（時間経過による減衰）

学びのファイルのフロントマターを、新しい信頼度スコアで更新します。

自動昇格ルール： 信頼度の調整後、学びの信頼度が**> 0.7**か確認します。そうであり、まだ MEMORY.md に記載されていない場合は、昇格させます：

1. 学びの重要な洞察を、該当する MEMORY.md のトピックファイルに追加します
2. "Promoted '<title>' to MEMORY.md (confidence: <score>)" と記録します
3. 同じパターンが信頼度 >= 0.8 で2つ以上のプロジェクトに現れる場合、スコープを project:<name> から global に昇格させます

2b. 孤立した調査結果を救出する

mine の出力に含まれる孤立した調査ファイルごとに、内容を読み、重要な洞察を2～3文で要約し、タイトルとカテゴリを付けた新しい学びの候補として提案します。

2c. ドメイン横断の統合

mine の調査結果をテーマ（例：「テストのパターン」、「CLI の規約」）ごとに分類します。調査結果が2件以上あるテーマについて、共通原則を捉えた統合パターンの候補を作成します。

2d. ギャップの特定

mine の出力トピックと既存の学びを比較します。対応する学びがないトピックはナレッジギャップです。それぞれについて、トピック、根拠、提案する学びのタイトルを列挙します。

Step 3 — デフラグ：機械的な整理

クリーンアップを実行して、古くなった成果物、重複した成果物、内容が揺れ動く成果物を見つけます。

ao defrag --prune --dedup --oscillation-sweep

.agents/defrag/latest.json を読み、孤立した学び（参照されておらず、30日以上前のもの）、類似度の高い重複ペア（内容の類似度が >80%）、揺れ動く目標（3サイクル以上にわたって改善と失敗を交互に繰り返すもの）を確認します。

代替手段： 古くなったファイルを見つけるには find .agents/learnings -name "*.md" -mtime +30 を実行します。結果パターンが交互に変化していないか、.agents/evolve/cycle-history.jsonl を確認します。

正規化の不具合をスキャンする

デフラグ中に、フライホイールの品質を低下させる構造上の不具合がないか、学びとパターンのプールをスキャンします：

# Placeholder patterns: files with only frontmatter, no content after closing ---
for f in .agents/patterns/**/*.md .agents/learnings/**/*.md; do
  [ -f "$f" ] || continue
  content_after_frontmatter=$(awk '/^---$/{n++; if(n==2) found=1; next} found{print}' "$f" | grep -c '[^ ]')
  [ "$content_after_frontmatter" -eq 0 ] && echo "PLACEHOLDER: $f"
done

# Stacked frontmatter: multiple --- delimiter pairs (>2 occurrences of ^---$)
grep -rl '^---$' .agents/learnings/ .agents/patterns/ 2>/dev/null | while read f; do
  count=$(grep -c '^---$' "$f")
  [ "$count" -gt 2 ] && echo "STACKED_FRONTMATTER: $f ($count delimiters)"
done

# Bundled multi-learning files: more than one ## Learning heading
grep -rl '^## Learning' .agents/learnings/ 2>/dev/null | while read f; do
  count=$(grep -c '^## Learning' "$f")
  [ "$count" -gt 1 ] && echo "BUNDLED: $f ($count learnings in one file)"
done

# Duplicated headings within a file
for f in .agents/learnings/**/*.md .agents/patterns/**/*.md; do
  [ -f "$f" ] || continue
  dupes=$(grep '^## ' "$f" | sort | uniq -d)
  [ -n "$dupes" ] && echo "DUPLICATE_HEADING: $f — $dupes"
done

正規化の不具合をデフラグの出力に報告します。不具合が見つかった場合は、重大度とともに列挙します：

• PLACEHOLDER → HIGH（空の知識が検索結果を汚染する）
• STACKED_FRONTMATTER → MEDIUM（解析エラーやデータ損失の可能性がある）
• BUNDLED → HIGH（学びごとの引用追跡が機能しなくなる）
• DUPLICATE_HEADING → LOW（見た目の問題であり、抽出を混乱させる可能性がある）

これらの不具合は、次回の forge サイクルで手動確認または自動分割を行う対象としてフラグを設定する必要があります。

Step 4 — レポート

mkdir -p .agents/athena

.agents/athena/YYYY-MM-DD-report.md を作成します：

# Athena Report — YYYY-MM-DD

## New Learnings Proposed
- [title]: [summary] (source: [research file or synthesis])

## Validations
- Validated: N | Stale: N (list files) | Contradicted: N (list with explanation)

## Knowledge Gaps
- [topic]: [evidence] → suggested learning: "[title]"

## Defrag Summary
- Orphaned: N | Duplicates: N | Oscillating goals: N

## Recommendations
1. [Actionable next step]

bd が利用可能な場合は、ナレッジギャップの issue を作成します：

bd add "[Knowledge Gap] <topic>" --label knowledge --label athena

提案する学び、検証結果、ギャップ、および推奨するデフラグの対応を、調査結果としてユーザーに報告します。

スケジュール設定／自動トリガー

軽量なデフラグ（プルーニング＋重複排除、マイニングなし）は、athena-session-defrag.sh フックによってセッション終了時に自動実行されます。これにより、手動で /athena を呼び出さなくてもナレッジストアをクリーンに保てます。このフックは次のように動作します。

• session-end-maintenance.sh の後、すべての SessionEnd イベントで実行されます
• ao CLI が利用できない場合は、何も表示せずにスキップします
• ao defrag --prune --dedup のみを実行します（--oscillation-sweep やマイニングは実行しません）
• セッション終了処理を妨げないよう、タイムアウトは20秒に設定されています

Mine → Grow → Defrag の完全なサイクルを実行するには、/athena を手動で呼び出してください。

使用例

ユーザーの入力： /athena — Mine → Grow → Defrag の完全なサイクルを実行し、.agents/athena/ にレポートを出力します。

ユーザーの入力： /athena --since 7d — より広い期間（7日間）を対象にマイニングします。

Evolve 前のウォームアップ： /evolve の前に /athena を実行し、最新の検証済みナレッジベースを用意します。

トラブルシューティング

問題	原因	解決方法
ao mine が見つからない	ao CLI が PATH にない	ステップ1の手動フォールバックを使用します
孤立した調査結果がない	すべての調査結果がすでに参照されている	2b をスキップして、統合に進みます
マイニングの出力が空	最近のアクティビティがない	--since の期間を広げます
オシレーションスイープの結果が空	振動している目標がない	健全な状態です。対応は不要です

参考ドキュメント

• references/confidence-scoring.md
• references/knowledge-synthesis-patterns.md
• references/flywheel-diagnostics.md