citation-fixer

Citation Fixer Skill

規約： すべての修正で準拠すべき正規の引用形式については、conventions/quality.md を参照してください。

出力ルール： すべてのリンクは決定論的でなければなりません（LLM が組み立てるのではなく、API データから構築します）。_output-rules.md を参照してください。

契約

このスキルでは、以下を保証します。

• すべての brain ページをスキャンし、引用の準拠状況を確認します。
• 引用がない場合は、具体的な場所とともに指摘します。
• 不正な形式の引用を標準形式に合わせて修正します。
• (v0.25.1) URL のないツイート／投稿の参照を X API 経由で解決し、決定論的な https://x.com/<handle>/status/<id> リンクを追加します。
• スキャン数、修正数、残件数を含めて結果を報告します。

フェーズ

1. ページをスキャンします。 ページを列挙してそれぞれを読み、インラインの [Source: ...] 引用があるか確認します。
2. 問題を特定します。
   • 引用のない事実
   • 日付が抜けている引用
   • ソースタイプが抜けている引用
   • 形式が正しくない引用
   • (v0.25.1) x.com URL のないツイートの参照
3. 形式の問題を修正します。 不正な形式の引用を conventions/quality.md に準拠するように書き換えます。
4. (v0.25.1) ツイートの参照を解決します。 X API 統合を介して解決します。
5. 結果を報告します。 ページのスキャン数、見つかった引用数、修正した問題数、解決したツイート数、残っている不備を集計します。

ツイート解決パイプライン（v0.25.1 拡張）

リンク切れのツイート参照ごとに、以下の手順に従います。実際の API 呼び出しは、ホストで設定されている X 統合を介して行います（一般的な形式は、handle／search-all エンドポイントを含む recipes/x-api/ 配下のレシピです）。

ステップ 1：リンク切れの参照を特定する

ページをスキャンし、URL のないツイート参照を示すパターンを探します。

• tweeted、posted、said on X、RT、retweet、X post などの語を含む
• ツイートのように見える引用文を含む（短く印象的で、引用符から始まることが多い）
• [Source: ... X/Twitter ...] はあるが、x.com URL がない
• リンクなしでエンゲージメント指標（いいね数、インプレッション数）に言及している

ステップ 2：検索可能な内容を抽出する

リンク切れの参照ごとに、以下を抽出します。

• ハンドル（記載されている場合：@<username>）
• 引用文（利用できる場合）
• おおよその日付（周辺のタイムライン項目に記載されていることがよくあります）

ステップ 3：実際のツイートを検索する

ホストの X API 統合を使用します。検索クエリの形式：

# Handle + quoted text:
from:<handle> "<exact quote fragment>"

# Quoted text only:
"<exact quote fragment>"

# Original of a retweet:
"<exact quote>" -is:retweet

ステップ 4：検証してメタデータを抽出する

候補が見つかったら、以下を行います。

• テキストが引用された断片と一致することを確認します。
• ツイート ID、投稿者のハンドル、エンゲージメント指標（いいね数／RT 数／インプレッション数）を取得します。
• URL を構築します：https://x.com/<handle>/status/<tweet_id>。

ステップ 5：brain ページに反映する

リンク切れの引用を、適切な引用に置き換えます。

変更前：

"<quote fragment>" [Source: <some hand-wavy attribution>]

変更後：

"<full verified quote>" — <N> likes, <N> RTs, <N> impressions
[Source: [X/<handle>, YYYY-MM-DD](https://x.com/<handle>/status/<tweet_id>)]

一括モード

多数のページを確認する場合：

対象ページを見つける

# Pages mentioning tweets but with no x.com links
for f in $(find . -name "*.md" -not -path "./node_modules/*"); do
  refs=$(grep -ci "tweet\|posted\|x post\|RT\|retweet\|said on X" "$f")
  links=$(grep -c "x.com/.*/status/" "$f")
  if [ "$refs" -gt 2 ] && [ "$links" -eq 0 ]; then
    echo "$f"
  fi
done

優先順位

1. 最近作成／更新されたページ — 新しいリンク切れの参照は、文脈が新しいうちに解決するのが最も簡単です。
2. アクセス頻度の高いページ（他のスキルから頻繁に読み書きされるページ）。
3. その他すべて — 時間をかけて一括で整理します。

レート制限

• X API：ホストのプラン上限を守り、過剰な呼び出しを行わないでください。
• 1 回のバッチ実行につき約 50 ページを目標にします。
• 1 ページあたり 1～3 回の API 呼び出し（検索＋検証）。
• 10～20 ページごとにバッチコミットし、途中で失敗しても進捗が失われないようにします。

出力形式

Citation Audit Report
=====================
Pages scanned:        N
Citations found:      N
Issues fixed:         N
Tweet links resolved: N
Remaining gaps:       N (pages with uncitable facts)

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または notice ブロックが発生した場合は、エージェント運用者プロトコルに従ってください。このスキル固有の対応：

• put_page がバッチ処理の途中で revision_conflict を返した場合：そのページを再読み込みし、引用の修正だけを再適用して続行します。以前読み込んだ内容で上書きしてはいけません。
• 引用元に対する get_page が page_not_found を返した場合：推測したスラッグに書き換えず、レポートでその引用を解決不能として記録します。
• バッチコミットが中断された場合：コミット済みのページは修正済みのままです。最初からやり直さず、最後にコミットしたページから再開します。

アンチパターン

• ❌ 出典のない事実について、引用を捏造しないでください。フラグを付けてください。
• ❌ 引用のない事実を削除しないでください（フラグを付け、削除しないでください）。
• ❌ ページ全体の文脈を読まずに引用を修正しないでください。
• ❌ まずサンプルで品質を確認せずに、一括修正しないでください （conventions/test-before-bulk.mdを参照）。
• ❌ ツイートIDを推測してツイートのURLを組み立てないでください。必ず X APIを使用してください。リンクは決定的に生成してください。

統合

このスキルは、次の方法で呼び出せます。

• 手動 — 「このページの引用を修正して」
• バッチ cron として — リファレンスが壊れているページを毎週チェック
• 他のスキルから — enrichまたはmedia-ingestは、出力を検証するため、コミット前にcitation-fixerを呼び出せます

メトリクス

定期的なバッチとして実行する場合は、~/.gbrain/citation-fixer-state.jsonの下に小さなJSONファイルを作成し、状態を追跡してください。

{
  "last_run": "2026-04-15T...",
  "pages_scanned": 0,
  "citations_fixed": 0,
  "tweet_links_resolved": 0,
  "citations_unresolvable": 0,
  "pages_remaining": 1424
}

出力形式

スキルの出力形式は、上記の本文セクション（「出力」、「Brainページ形式」など）に記載されています。ここに記載されているセクション見出しは、準拠テスト（test/skills-conformance.test.ts）のために存在します。