dogfood

Dogfood スキル

VCS プロバイダー

このスキルでは、Exarchos MCP アクション（create_issue など）を通じて VCS 操作を行います。 これらのアクションは、適切な VCS プロバイダー（GitHub、GitLab、Azure DevOps）を自動的に検出して処理を振り分けます。 gh／glab／az コマンドは不要です。MCP サーバーがプロバイダーへの振り分けを処理します。

概要

Exarchos MCP ツールの使用状況を振り返って分析します。MCP サーバー自身のセルフサービス機能を主要な診断手段として利用し、API、ビュー、プレイブック、ランブックを内省的に使って障害を診断します。

これは、以前のトランスクリプトのみを使ったトリアージに対応する、ランタイム内のイベントソース型の手法です。エージェントは exarchos_workflow feedback を通じてリアルタイムに摩擦レポートを登録し、それらは共有の meta/feedback ストリームに取り込まれます。Dogfood はこのストリームを第一級の入力（ステップ 1h）として読み込みます。各 feedback.recorded イベントは、問題が発生した瞬間にすでに記録されている、エージェントが報告した摩擦シグナルであり、事後に再構成されたものではありません。

異なる 3 種類の障害モードには、コードの変更、ドキュメントの更新、スキルの指示の改善という、それぞれ異なる修正が必要です。これらを混同すると、労力が無駄になります。

プラットフォーム非依存性

docs/designs/archive/2026-03-09-platform-agnosticity.md に記載のとおり、MCP サーバーは自己完結型でプラットフォームに依存しないコアです。デバッグトレースは会話の内省ではなく、すべて MCP ツールに依存するため、どの MCP クライアントでも機能します。会話のスキャンは補助的なものです。

診断用セルフサービスツール： HSM の検証には describe(topology)、遵守状況の確認には describe(playbook)、イベントスキーマ／カタログの比較には describe(eventTypes, emissionGuide)、スキーマ／ゲートのメタデータには describe(actions)、ステップの適合性確認には runbook(phase)、ヘルスメトリクスには pipeline／convergence／telemetry ビューを使用します。

トリガー

次の場合にこのスキルを有効にします。

• ユーザーが /dogfood または dogfood を実行する
• ユーザーが「このセッションで何がうまくいかなかったか」や「失敗を確認して」と尋ねる
• ユーザーがワークフロー実行のエラーをトリアージしたい
• 学びを記録するためにワークフローセッションを終了する

プロセス

ステップ 1：MCP セルフサービスによるデバッグトレース

MCP サーバー自身のセルフサービス機能を照会し、根拠に基づく診断状況を構築します。これは主要な調査方法であり、あらゆる MCP クライアントが利用できるのと同じツールを使用します。

1a. アクティブなワークフローを特定する

exarchos_view を action: "pipeline" とともに使用して、フェーズとタスク数を含むアクティブなワークフローの集約ビューを取得します。このビューはデフォルトでリポジトリのスコープ内（呼び出し元のリポジトリのみ）です。レスポンスで unscopedTotal が page.total より大きい場合、他のリポジトリのワークフローは非表示になっています。リポジトリをまたいだ全体の一覧を確認するには、scope: "all" を指定して再照会します。

$ARGUMENTS でワークフローまたは機能 ID が指定されている場合は、そのワークフローにスコープを絞ります。指定されていない場合は、終端状態ではないすべてのワークフローを確認します。

1b. ワークフローの状態とトポロジーを調べる

関連するワークフローごとに、次の操作を行います。

1. 状態を読む — exarchos_workflow get を実行し、現在のフェーズ、タスク、レビュー、ゲートの結果を取得します。
2. トポロジーを読む — exarchos_workflow describe(topology: "<workflowType>") を実行し、HSM 定義を取得します。エージェントによるフェーズ遷移の試みを、有効な遷移と比較します。無効な遷移の試みは、ドキュメントの問題（スキルが誤った経路を指示した）またはユーザーエラーです。
3. ガードの前提条件を確認する — workflow.guard-failed イベントについては、トポロジーで該当するガードを調べ、満たされていない前提条件を把握します。

1c. プレイブック遵守状況の確認

exarchos_workflow describe(playbook: "<workflowType>") を使用して、フェーズのプレイブックを取得します。実行された各フェーズについて、プレイブックの tools、events、transitionCriteria、guardPrerequisites、humanCheckpoint、compactGuidance を、エージェントが実際に行ったこと、およびスキルのドキュメントで規定されている内容と比較します。

プレイブック違反は診断に役立つ重要な情報です。

• エージェントが逸脱し、スキルのドキュメントがそのように指示していた場合 → ドキュメントの問題（スキルとプレイブックが矛盾）
• エージェントが逸脱し、スキルのドキュメントがプレイブックと一致していた場合 → ユーザーエラー
• プレイブックが誤っている（無効なツールやイベントを指定している）場合 → コードのバグ

1d. イベントログの分析

exarchos_event query(stream) をワークフローのイベントストリームに対して使用します。次の点を確認します。

• 拒否されたイベント — エージェントが試行したにもかかわらずログに存在しないイベント（会話中のエラーと照合します）
• 欠落したイベント — プレイブックの events フィールドおよび exarchos_event describe(emissionGuide: true) と比較します。モデルが出力するイベントの欠落は、ドキュメントの不備またはユーザーエラーを示します。
• 順序の異常 — 順序の誤り、重複、またはタイムラインの空白
• スキーマの不一致 — describe(eventTypes: [...]) を使用して、正式な JSON Schema を取得します。実際のペイロードをスキーマと比較し、意味的に誤ったフィールドがないか確認します。

1e. Orchestrate のアクションとゲートの分析

1. スキーマの検証 — exarchos_orchestrate describe(actions: [...]) を使用して、正式なスキーマを取得します。エージェントのパラメーターをスキーマと比較し、古くなったスキルのドキュメントや即興の対応を検出します。
2. ゲートのメタデータ — Describe の出力には { blocking, dimension, autoEmits } が含まれます。エージェントが blocking／non-blocking を正しく扱ったか、期待された自動出力が発生したかを確認します。
3. ゲートの収束状況 — exarchos_view convergence で、ディメンション（D1-D5）ごとの合格率を確認します。収束率が低い場合、ゲートにシステム上の問題があることを示唆します。

1f. ランブックへの準拠状況の確認

exarchos_orchestrate runbook(phase) を使用して、関連するランブックを取得します。手順の順序、判断分岐の正しさ（decide フィールドがある手順）、onFail ディレクティブ（stop／continue／retry）への準拠、および templateVars の完全性を確認します。

1g. テレメトリの確認

exarchos_view telemetry を使用して、ツールごとのパフォーマンスを確認します。次の点に注意してください。エラー率の高さ（システム上の問題）、呼び出し回数の多さ（再試行ループ）、およびプレイブックで指定されているにもかかわらず一度も呼び出されていないツール。

1h. 摩擦のバックチャネル（feedback.recorded）

exarchos_event query(stream: "meta/feedback") を使用して、exarchos_workflow feedback 経由で送信された最近の摩擦レポートを読み取ります。これらはエージェントがリアルタイムで報告した調査結果です。エージェントが使いづらい操作に直面した際、黙って再試行する代わりに、失敗した呼び出し中にその問題を報告しています。各レポートを、あらかじめ得られた調査結果として扱います。

• message — 摩擦に関するエージェント自身の説明です。トランスクリプトから再構成するのではなく、ステップ 3 の「何が問題だったか」に反映します。
• sessionContext（workflow／action／errorCode）— レポートを、問題が発生したワークフローとアクションに関連付けます。イベントログ（1d）およびテレメトリ（1g）と照合し、サーバー側の裏付けとなる証拠を確認します。
• upstreamDelivered — configuredEndpoint が設定されているにもかかわらず値が false の場合、それ自体が調査結果となります（フェデレーションの中継に失敗）。

各レポートは引き続きステップ 4 の分類（コード／ドキュメント／ユーザー）を行います。サーバー側に該当する不具合がない feedback.recorded イベントを、自動的に退けてはいけません。呼び出しが最終的に成功していても、エージェントの摩擦は重要なシグナルです（再試行後に成功するアンチパターンを参照）。デバッグトレースで既に明らかになっている調査結果とレポートの重複を排除し、バックチャネルのレポートとトレースの証拠を別々の調査結果にせず、1つにまとめます。

ステップ 2：セッションをスキャンして失敗したツール呼び出しを確認する

クライアント側のコンテキストでデバッグトレースを補足します。会話を確認し、失敗した Exarchos ツール呼び出しを探します。

注： プラットフォームに依存するステップです（会話履歴が必要です）。イントロスペクションに対応していないプラットフォームではスキップしてください。デバッグトレースだけで十分です。

対象ツール： exarchos_workflow、exarchos_event、exarchos_orchestrate、exarchos_view、exarchos_sync

エラーの兆候： INVALID_INPUT、VALIDATION_ERROR、BATCH_APPEND_FAILED、Zod の失敗（invalid_type、invalid_enum_value、unrecognized_keys）、ENOENT、CLAIM_FAILED、SEQUENCE_CONFLICT、CAS の枯渇、再試行の連続、再試行後に成功した呼び出し。

ステップ 3：各失敗を診断する

デバッグトレースと会話のスキャン結果を統合します。各失敗について、以下を記録します。

1. 試みた内容 — アクション、パラメーター、意図
2. 問題の内容 — エラーメッセージと検証パス
3. サーバー側の証拠 — イベントログ、状態、describe の出力、ビュー
4. 信頼できる参照情報 — 正確な情報を得られるセルフサービスクエリ（プレイブック、トポロジー、スキーマ、ランブック）
5. 根本原因 — references/root-cause-patterns.md に従います
6. 修正カテゴリ — コード、ドキュメント、またはユーザーの操作

サーバー側の確認でしか判明しない不一致は、トレースのみの所見としてマークします。

ステップ 4：カテゴリに分類する

各失敗を、根本原因のカテゴリのうちちょうど 1 つに分類します。

カテゴリ 1：コードのバグ

MCP サーバー、イベントストア、またはワークフローエンジンに不具合があります。

兆候： スキーマが有効な入力を拒否する（describe で確認済み）、並行して書き込む処理がないのに CAS が失敗する、ゲートが過剰に適用される、同一パラメーターでの再試行が成功する（競合状態）、状態の破損、トポロジーとエンジンの不一致、自動発行の失敗。

対応： 再現手順、期待される結果と実際の結果、修正案を添えてバグの Issue を作成します。

カテゴリ 2：ドキュメントの問題

スキルのドキュメントに誤りや不足があるか、MCP サーバーのセルフサービス出力との同期が取れていません。

兆候： スキルのペイロードが describe スキーマと一致しない、スキルとプレイブックに食い違いがある、スキルに存在しないトポロジーパスが記載されている、イベントタイプが不足している（発行ガイドと比較）、再試行によるフィールドの発見、ランブックとスキルの矛盾、compactGuidance のずれ。

対応： ファイルと行番号、相違点、describe の出力に基づく正しい情報を添えて、ドキュメントの Issue を作成します。

カテゴリ 3：ユーザーエラー

ドキュメントと describe の出力の両方に正しく説明されている使い方に反して、エージェントがツールを誤って使用しました。

兆候： 形式の不一致（describe とドキュメントの内容が一致していることを確認済み）、無効な順序（トポロジーで確認済み）、スキルとプレイブックの両方で指定されているコンテキストの不足、正当な理由のないランブックからの逸脱。

対応： エラーが頻発する場合は、スキル改善のために記録します。

ステップ 5：レポートを作成する

references/report-template.md のテンプレートを使ってレポートを作成します。以下を含めてください。

• カテゴリ別の概要件数
• デバッグトレースの概要（調査したワークフロー、確認したイベント、実行した describe クエリ、参照したビュー）
• 各失敗の詳細な診断（信頼できるセルフサービス参照情報を含む）
• トレースのみの所見のセクション（サーバー側の確認でしか判明しない問題）
• プレイブック／ランブックへの準拠状況の概要
• 実行可能な次のステップ（バグやドキュメントの Issue の草案）

ステップ 6：Issue の作成を提案する

コードのバグとドキュメントの問題のカテゴリに分類された所見について、GitHub Issue の作成を提案します。

exarchos_orchestrate({ action: "create_issue", title: "<type>: <summary>", body: "<issue body>", labels: ["bug"] })

ユーザーの確認を得てから Issue を作成してください。まず草案を提示します。

必須の出力形式

{
  "session_summary": {
    "total_tool_calls": 0,
    "failed_tool_calls": 0,
    "failure_rate": "0%",
    "debug_trace": {
      "workflows_inspected": 0,
      "events_reviewed": 0,
      "describe_queries": 0,
      "views_consulted": [],
      "feedback_reports_reviewed": 0,
      "trace_only_findings": 0
    }
  },
  "playbook_adherence": {
    "phases_checked": 0,
    "violations": [
      {
        "phase": "delegate",
        "field": "events",
        "expected": "team.spawned, team.task.assigned",
        "actual": "none emitted",
        "bucket": "documentation_issue"
      }
    ]
  },
  "runbook_conformance": {
    "runbooks_checked": 0,
    "deviations": []
  },
  "buckets": {
    "code_bug": [],
    "documentation_issue": [],
    "user_error": []
  },
  "findings": [
    {
      "id": 1,
      "bucket": "code_bug | documentation_issue | user_error",
      "tool": "exarchos_workflow",
      "action": "update",
      "error": "INVALID_INPUT: ...",
      "root_cause": "Schema rejects null branch on pending tasks",
      "trace_evidence": "describe(actions: ['update']) shows branch as required string; event log confirms no task.updated event",
      "authoritative_ref": "exarchos_workflow describe(actions: ['update']) → TaskSchema",
      "severity": "HIGH | MEDIUM | LOW",
      "suggested_fix": "Accept nullable branch in TaskSchema",
      "issue_draft": {
        "title": "bug: workflow task schema rejects null branch",
        "labels": ["bug"],
        "body": "..."
      }
    }
  ],
  "trace_only_findings": [
    {
      "id": "T1",
      "description": "State drift: agent assumed phase was 'delegate' but server shows 'plan'",
      "evidence": "exarchos_workflow get shows phase=plan; topology confirms plan→delegate requires planReviewComplete guard",
      "authoritative_ref": "exarchos_workflow describe(topology: 'feature') → guards",
      "bucket": "documentation_issue",
      "suggested_fix": "Skill should instruct agent to verify phase via get before proceeding"
    }
  ]
}

アンチパターン

しないこと	代わりにすること
デバッグトレースを確認せず、会話だけをざっと見る	まず必ず MCP のセルフサービスツールに問い合わせます。会話の確認は補足として行います
スキーマが何を求めているか推測する	describe を使って正式なスキーマを取得します。スキーマが唯一の信頼できる情報源です
記憶を頼りにプレイブックへの準拠を評価する	describe(playbook) に問い合わせて、規定されている実際のツール、イベント、基準を取得します
確認せずにトポロジーを決めつける	describe(topology) に問い合わせて、有効な遷移、ガード、効果を取得します
スキルのドキュメントとプレイブックが矛盾しているとき、ユーザーの責任にする	スキルのドキュメントがプレイブック／describe の出力と異なる場合は、ドキュメントの問題です
重複する課題を登録する	起票する前に、既存の未解決／解決済みの課題を確認します
リトライを別々の失敗として分類する	リトライの連続した試行は、1つの指摘事項としてまとめます
リトライ後に成功した呼び出しを無視する	最終的に成功していても、これらは摩擦を示しています
Exarchos 以外の失敗を含める	対象を5つの Exarchos ツールに厳密に限定します。他の MCP の失敗は対象外です
トレースによる裏付けのない、会話だけに基づく指摘を報告する	可能な限り、すべての指摘をサーバー側の状態と照合します