di-agent-bug-report

DI Agent バグレポート — IBM watsonx.data 統合セッション

現在の AI エージェントのセッションを Markdown レポートに記録します。エージェントが watsonx.data 統合フローを作成、実行、または管理していた際に何がうまくいかなかったのか（または何がうまくいったのか）を、watsonx.data 統合スキルの作成者がデバッグできるようにします。このスキルは特定のエージェントに依存しません。特定の AI ランタイム、モデル、セッションファイルのレイアウトを前提にしないでください。

使用するタイミング

• 手動： ユーザーが明示的にバグの報告を求めるか、バグレポートを提出した場合は、確認を求めずにそのまま進めます。

• 自動（提案のみ、決して黙って実行しない — セッションにつき 1 回）： ループ検出ルールが発動した場合、エージェントは必ずこのスキルを提案します。厳密な発動ルール：

  1. ループ検出ルール（主なトリガー）。 ツール呼び出しのたびに、呼び出したツール名を記録する呼び出しログを継続的に管理します。同じターン内で、エージェントが同じツール、または同じ順序のツールの並びを 3 回以上連続して呼び出し、各試行で同じエラー、同じ失敗ステータス、または出力に意味のある変化がなかった場合、「繰り返し」とみなします。このような 3 回目の繰り返しを検出したら：
     • 直ちに停止します。4 回目の試行を行わないでください。
     • バグレポートを提案します：「<tool(s)> を同じ結果（<one-line error/symptom>）で 3 回呼び出しました。バグレポートを作成しますか？（はい／いいえ）」
     • 続行する前に、明示的な返答を待ちます。
     • 該当する例：
       • compile_datastage_flow を 3 回呼び出し、毎回同じコンパイルエラーが返された場合。
       • create_job → run_job → get_job_run_logs を 1 つの単位として 3 回連続で実行し、各サイクルで同じ失敗が発生した場合。
       • いずれか 1 つの MCP ツールを 3 回連続して呼び出し、エラーメッセージが同一、または出力の構造に変化がなかった場合。
     • 該当しない例：
       • 入力やパラメーターに意味のある違いがある 3 回の呼び出し（エージェントが実際に異なる方法を試している場合）。
       • エラーではなく、空でも正常に完了した結果が返された場合。
  2. セッションごとに提案は 1 回のみ。 自動提案を行ったことを記録し、その後の失敗にかかわらず、セッションの残りの期間は自動提案を再度行わないでください。ユーザーは引き続き手動でスキルを呼び出せます。この上限は自動実行にのみ適用されます。
  3. 質問したら、返答を待つ。 短い提案メッセージを 1 回送信し、ユーザーが肯定的に返答した場合にのみワークフローを実行します。ユーザーが断るか返答しない場合は、ファイルを作成しません。受諾、拒否、無視のいずれの応答でも、セッションごとの 1 回限りの提案枠を消費します。

次のいずれかに該当する場合、そのセッションは watsonx.data 統合関連とみなされます。

• 名前が di-agent- で始まるスキルが使用された。
• Agentic Data Integration MCP サーバーに属する MCP ツールが呼び出された（名前空間付きツール名のサーバープレフィックスで識別します。例：mcp__ibm-agentic-data-integration__*）。
• ユーザーが watsonx.data 統合フローまたはジョブの作成／編集／実行／デバッグを依頼した。

引数

• --name <filename> (省略可能) — 出力ファイル名を上書きします。agent/bug_reports/ の下に書き込みます。ベース名のみ指定できます。.md がない場合は追加されます。パス区切り文字と .. は拒否します。省略した場合は、既定の名前を使用します（不変条件 3 を参照）。

不変条件

1. watsonx.data との統合のみを対象とします。（上記のシグナルに基づき）セッションが watsonx.data との統合に関連しない場合は、ファイルを書き込まず、スキップを示すメッセージを1行だけ出力して終了してください。まず検出し、その後に判断してください。
2. 書き込み前に、すべての PII をマスキングしてください。 ユーザーのテキスト、アシスタントのテキスト、トランスクリプトの項目、エラー文字列に対して、ファイルへの書き込み前に、書き込み後ではなく、編集処理を適用してください。スキル名、ツール名、エラーメッセージ、スキーマ名／カラム名、ユーザー ID、プロジェクト ID、アセット ID、フロー ID、ジョブ ID、公開データセット名はデバッグに必要なため、編集しないでください。
3. 呼び出しごとに1ファイルとします。 デフォルトのパス：ibm-watsonx-data-integration-agent-skills/agent/bug_reports/watsonx_di_agent_bug_report_<YYYY-MM-DD>_<HH-MM-SS>_<session_name>.md。<HH-MM-SS> はローカル時刻の24時間表記で、<session_name> はユーザーの最初の意図を要約した、AI が生成する短いスラッグです。小文字、ハイフン区切り、ASCII の英字／数字のみ、6語以下とし、埋め草としてスキル名を使わないでください。--name が指定された場合は、代わりに .../bug_reports/<filename>.md に書き込んでください。存在しない場合は bug_reports/ を作成してください。対象ファイルがすでに存在する場合は、上書き前に確認してください。
4. 会話を信頼できる情報源として使用してください。 推測ではなく、実際のメッセージとツール呼び出しからトランスクリプトを再構成してください。

ワークフロー

1. セッションメタデータを解決する

• session_date、session_time：今日の日付と現在のローカル時刻（形式は不変条件 3 に従います）。
• session_name：最初のユーザープロンプトから導出したスラッグ（規則は不変条件 3 に従います）。
• agent_session_id：ホストエージェントランタイムのセッション識別子。次の順に試してください：（1）ランタイムのアクティブなトランスクリプト／ログファイル。一般的なパターンには ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl（Claude Code）、~/.cursor/...、またはランタイムのドキュメントで案内されている任意のパスがあります。一致する <uuid>.jsonl が存在し、それが最終更新日時の最も新しいファイルである場合は、ファイル名の UUID を使用してください。（2）ホストが提供している場合は、ランタイムのイントロスペクション／whoami ツール。それでも解決できない場合は null を記録し、試した情報源を明記してください。決して捏造したり推測したりしないでください。
• session_info：watsonx.data 統合の get_session_info MCP ツールを呼び出し、その出力全体を一字一句そのまま取得してください。生のキー／値ペイロードを各フィールド1項目の箇条書きにして、generated_at のすぐ上にある Session Info セクションに記載してください。単一の ID を抽出しようとせず、ツールが返す内容をそのまま渡してください。ツールを利用できない場合、またはエラーが発生した場合は、箇条書きで **Session Info:** _tool unavailable._ と記録して続行してください。
• llm：ホストエージェントランタイムを実行している LLM の名前とバージョン（例：claude-opus-4-7、claude-sonnet-4-6、gpt-5.1）。ランタイムが独自のシステムプロンプトで示しているモデル識別子を使用してください。実行中のモデルは LLM 自身が把握しています。自己識別できない場合は、ランタイムのイントロスペクションツールまたはモデル関連の環境変数を使用してください。<name>-<version> として記録し、いずれの方法でも解決できない場合に限り null を記録してください。
• 出力ファイル名：--name の値（サニタイズして .md を付加）または不変条件 3 のデフォルト値。

2. トランスクリプトを作成する

セッションのすべての項目をまとめた、時系列順のセクションを1つ作成します。会話の順序に沿って、ユーザーメッセージ、アシスタントのテキスト応答、スキルの呼び出し、ツール呼び出しごとに番号付きの項目を1つ追加します。すべての項目で番号を共通にし、発生順に厳密に並べます。ターンとツール呼び出しは自然な順序で交互に並びます。

項目ごとの形式：

• ユーザー／アシスタントのターン — 太字の疑似見出しの直後に、PII を除去した本文を含む text フェンス付きコードブロックを置きます。逐語的に記載すること：実際のテキストを、PII の除去を除いて一字一句そのまま再現します。要約、言い換え、[X スキルを呼び出し、その後…] のような角括弧付きの説明は不可です。アシスタントのターンには、ユーザーに表示された文章のみを含め、内部推論と生のツール呼び出し JSON は除外します。アシスタントのターンにユーザー向けテキストがなく、ツール呼び出しのみだった場合は、そのターンを省略します。文章を作り足してはいけません。

  **N. turn — <User | Assistant>**
  
  ```text
  <verbatim PII-redacted text of the turn, line breaks preserved>
  

• スキルまたはツールの呼び出し — 種類、名前、ステータスを記した太字の疑似見出しに続けて、**Input:** と **Output:** の箇条書きを置きます。

  **N. <skill | tool> — `<name>` — status: <ok | error | unknown>**
  
  - **Input:** <one-line summary — never the full payload>
  - **Output:**
  
    ```text
    <result, truncated to ~2000 chars; `_No output._` if none; failure messages go here>
  

注：

• 一般的な Read／Edit／Bash の呼び出しは、watsonx のフローに含まれる場合に限り記載します。
• Description セクションでは、トランスクリプトの項目番号（entry N）を参照します。

3. 診断ツールを呼び出し、詳細な情報を収集する

必須です。 トランスクリプトに記載されたジョブ実行ステータスは、completed／failed と短い概要のみを示すため、実際に何が起きたかを診断するには不十分です。Description（ステップ 4）を確定する前に、セッションから関連する入力を取得できる場合は、以下の watsonx.data 統合 MCP ツールを呼び出します。入力が不足している場合に限り、そのツールを省略します。失敗しても処理を止めず、エラーを含む各試行をそれぞれトランスクリプトの項目として記録します。

• get_job_run_logs — 最新のジョブ実行について、完全なログストリームとイベント履歴を取得します。Description では、具体的な警告／エラー（暗黙的な型変換、パーティション数、ステージごとの in → out 行数など）を引用します。
• retrieve_datastage_flow_code — 提出されたフローの保存済み定義を取得し、実際に実行された内容（列の型、述語、結合）がレポートに反映されるようにします。

Description は、これらのツール出力に基づいて記述する必要があります。表面的な実行ステータスだけを根拠に診断してはいけません。

4. セッションを診断する

Description セクションを作成します。トランスクリプト（ステップ 2）と診断データ（ステップ 3）に基づいて分類します。

• 成功 — 行を生成。 フローが完了し、出力がソースと整合しています。
• 成功 — ソースが空のため空のまま。 ジョブは問題なく実行され、ソースのデータ行数が 0 です。結果は success とし、その旨を明記します。
• 成功 — 期待どおり出力なし。 フローのロジックにより、行が生成されないことが正当化されます（アンチ結合、フィルターなど）。結果は success とし、理由を Description で説明します。
• 失敗。 ログにエラーがある場合、空でないソースから行が気付かないうちに欠落した場合、またはエージェントがループした／ツールを誤用した／無効なフローを生成した場合です。Description で具体的な証拠を引用します。

Description は最大 5～6 文に厳密に収めてください。 結果と直接の理由、つまり何がどこで失敗したか（トランスクリプトの entry N を引用）と、その根拠となる証拠を記載します。背景説明、経緯の説明、ユーザーの依頼の言い換えは不要です。

5. Markdown ファイルを書く

ibm-watsonx-data-integration-agent-skills/agent/bug_reports/ が存在しない場合は作成し、以下のテンプレートを使って書き込みます。

書式ルール：

• ファイルの最初の行は必ず # IBM watsonx.data integration Agent Bug Report にしてください。 YAML／Markdown のフロントマター、先頭の --- 区切り、空行、シバン、H1 より前のメタデータブロックは使用しないでください。ファイルは H1 で始め、それ以外の内容を先頭に置かないでください。
• ドキュメント内のどこにも水平線の区切り（---）を挿入しないでください。 セクションの区切りには ## 見出しのみを使用してください。Markdown の --- 行は水平線として表示され、出力が見づらくなります。
• セクションの順序は固定です：Session Info → Description → Transcript。
• 見出しレベルは 2 つのみです。タイトルには #、セクションには ## を使用してください。### は使用せず、太字の擬似見出しを使ってください。
• セクションの間、およびコードフェンスの前後には空行を 1 行入れてください。末尾には改行を 1 つ付けてください。
• 複数行の出力は、言語ヒント付きのコードフェンスで囲んでください。
• フィールドラベルは太字にしてください（**Input:**、**Output:** など）。
• 空のセクションには、イタリック体の行を 1 行だけ記入してください。

テンプレート：

# IBM watsonx.data integration Agent Bug Report

**Outcome:** [success | failure]

## Session Info

- **Agent Session ID:** `[uuid or null]`
- **LLM:** `[name-version, e.g. claude-opus-4-7, or null]`
- **`get_session_info`:** [render each field returned by the tool as its own indented bullet, verbatim — e.g. `session_id`, `client_type`, etc. If the tool errored or was unavailable, write `_tool unavailable._` instead.]
- **Generated at:** [ISO-8601 timestamp]

## Description

[5–6 sentences max. State the outcome and the direct reason — what failed, where (cite transcript entries as `entry N`), and what the evidence says. No background, no fixes.]

## Transcript

**1. turn — User**

```text
[PII-redacted user message text, verbatim.]
```

**2. turn — Assistant**

```text
[PII-redacted assistant prose reply, verbatim.]
```

**3. [skill | tool] — `[name]` — status: [ok | error | unknown]**

- **Input:** [one-line summary]
- **Output:**

  ```text
  [result, truncated to ~2000 chars; `_No output._` if none. Failure message goes here.]
  ```

[...continue numbering chronologically; turns and tool calls interleave...]

6. ユーザーに確認する

書き込み後、絶対ファイルパス、結果、トランスクリプト項目数を出力してください。レポート全文は出力しないでください。

例

• watsonx.data integration 以外のセッション。 無関係な Go サービスのリファクタリング → 1 行でスキップし、ファイルは書き込みません。
• 成功したセッション（手動実行）。 エージェントが pyflow を構築して送信し、実行がポーリングの結果、成功となりました。ユーザーが記録用にバグレポートを作成 → 結果は success。
• 失敗したセッション（提案 → 承認）。 エージェントが関連する検索ツールを参照せず、ステージ／コネクターの設定を何度も推測したため、フローのコンパイルに失敗しました。エージェントがレポートを提案し、ユーザーが承認 → 結果は failure。Description には参照し損ねた検索ツールを記載します。