provenance

プロベナンススキル

ナレッジアーティファクトの系譜をソースまでたどります。

実行手順

/provenance <artifact> を指定した場合：

ステップ 1：アーティファクトを読む

Tool: Read
Parameters:
  file_path: <artifact-path>

プロベナンスメタデータを確認します：

• ソース参照
• セッション ID
• 日付
• 関連アーティファクト

ステップ 2：ソースの連鎖をたどる

# Check for source metadata in the file
grep -i "source\|session\|from\|extracted" <artifact-path>

# Search for related transcripts using ao
ao search "<artifact-name>" 2>/dev/null

ステップ 3：CASS でセッションのトランスクリプトを検索する

CASS を使って、このアーティファクトについて話し合われた時期を確認します：

# Extract artifact name for search
artifact_name=$(basename "<artifact-path>" .md)

# Search session transcripts
cass search "$artifact_name" --json --limit 5

CASS の検索結果を解析して、以下を確認します：

• アーティファクトが作成された、または話し合われたセッション
• 参照のタイムライン
• ワークスペースごとの関連セッション

CASS の JSON 出力フィールド：

{
  "hits": [{
    "title": "...",
    "source_path": "/path/to/session.jsonl",
    "created_at": 1766076237333,
    "score": 18.5,
    "agent": "claude_code"
  }]
}

ステップ 4：系譜の連鎖を構築する

Transcript (source of truth)
    ↓
Forge extraction (candidate)
    ↓
Human review (promotion)
    ↓
Pattern recognition (tier-up)
    ↓
Skill creation (automation)

ステップ 5：プロベナンスレポートを作成する

# Provenance: <artifact-name>

## Current State
- **Tier:** <0-3>
- **Created:** <date>
- **Citations:** <count>

## Source Chain
1. **Origin:** <transcript or session>
   - Line/context: <where extracted>
   - Extracted: <date>

2. **Promoted:** <tier change>
   - Reason: <why promoted>
   - Date: <when>

## Session References (from CASS)
| Date | Session | Agent | Score |
|------|---------|-------|-------|
| <date> | <session-id> | <agent> | <score> |

## Related Artifacts
- <related artifact 1>
- <related artifact 2>

ステップ 6：ユーザーに報告する

ユーザーに以下を伝えます：

1. アーティファクトの系譜
2. 元のソース
3. 昇格の履歴
4. セッションの参照（CASS から取得）
5. 関連アーティファクト

孤立したアーティファクトを見つける

/provenance --orphans

ソース追跡情報のないアーティファクトを見つけます：

# Files without "Source:" or "Session:" metadata
for f in .agents/learnings/*.md; do
  grep -L "Source\|Session" "$f" 2>/dev/null
done

古くなったアーティファクトを見つける

/provenance --stale

ソースが変更されている可能性のあるアーティファクトを見つけます：

# Artifacts older than their sources
find .agents/ -name "*.md" -mtime +30 2>/dev/null

主なルール

• すべての知見にはソースがあります ― そのソースをたどります
• 昇格を追跡します ― 階層が変更された理由を把握します
• 孤立したアーティファクトを見つけます ― 追跡されていない知識を整理します
• 系譜を維持します ― プロベナンスによって信頼性が高まります
• CASS を使用します ― アーティファクトについて話し合われた時期を確認します

例

アーティファクトの系譜をたどる

ユーザーの入力： /provenance .agents/learnings/2026-01-15-auth-tokens.md

実行内容：

1. エージェントがアーティファクトを読み取り、ソースメタデータ（セッション ID、日付、参照）を抽出します
2. エージェントが cass search "auth-tokens" --json --limit 5 でセッションのトランスクリプトを検索します
3. エージェントが CASS の検索結果を解析し、起点となったセッションとタイムラインを確認します
4. エージェントが forge → learnings → patterns の昇格履歴をたどります
5. エージェントが系譜の連鎖を構築し、レポートを Markdown に書き込みます
6. エージェントがアーティファクトの階層、出典、関連アーティファクトを報告します

結果： トランスクリプトから現在の階層までのプロベナンスの連鎖全体が示され、アーティファクトの作成、議論、昇格の時期を確認できます。

孤立したアーティファクトを見つける

ユーザーの入力： /provenance --orphans

実行内容：

1. エージェントが .agents/learnings/ と .agents/patterns/ をスキャンし、ソースメタデータのないファイルを探します
2. エージェントが各ファイルから「Source:」または「Session:」フィールドを grep で検索します
3. エージェントがプロベナンス追跡情報のないファイルを一覧表示します
4. エージェントが孤立したアーティファクトの数を報告し、ソース参照の追加を推奨します

結果： 追跡されていない知識が特定され、遡及的な系譜の記録やアーカイブが可能になります。

トラブルシューティング

問題	原因	解決策
ソースメタデータが見つからない	プロベナンス追跡の導入前にアーティファクトが作成された	CASS を使って起点となったセッションを遡及的に特定し、Source フィールドを手動で追加します
CASS で検索結果が返されない	セッションがインデックスに登録されていない、またはアーティファクト名が一致しない	セッションのトランスクリプトが存在するか確認し、より広い検索語を試します
古くなったアーティファクトの確認に失敗する	find コマンドが利用できない、または権限エラーが発生している	代替手段として `ls -lt .agents/
系譜の連鎖が不完全	アーティファクトのメタデータに昇格が記録されていない	git の履歴またはセッションのトランスクリプトから再構築し、不足箇所を記録します