infrahub-reporting-issues

Infrahub Issue Reporter

概要

ユーザーが GitHub 上の正しい Infrahub エコシステムのリポジトリに対してバグレポートや機能リクエストを提出できるよう支援します。このスキルは自動提出を行いません — 完全でサニタイズ済みの issue を準備し、ユーザーのレビューゲートで停止します。提出は、ユーザーがコンテンツと提出方法の両方を明示的に承認した後にのみ実行されます。

エコシステムには 11 の候補リポジトリがあります。ほとんどのユーザーは、自分の問題がどのリポジトリに属するかを知りません。このスキルの役割は、ローカルリポジトリのコンテキストから自信を持って推測し、ユーザーに確認し、重複を検索し、対象リポジトリの受け付けフォームに合致するドラフトを作成することです。

使用するタイミング

ユーザーが次のようなことを言ったときにこのスキルをトリガーします。

• 「Infrahub でバグを見つけたと思う」
• 「この issue はどう報告すればいいですか？」
• 「機能をリクエストしたい」
• 「これはどこに提出すればいいですか？」
• 「これが動作しないので、チケットを起票したい」

ユーザーがローカルでデバッグ中であり、issue を起票する意図を表明していない場合はトリガーしないでください。起票は、このスキルを一般的なトラブルシューティングと区別するアクションです。

摩擦が Infrahub 製品 自体ではなく、Infrahub のスキル自身のガイダンス（誤っている、欠けている、または紛らわしいルール）に関するものである場合、直接トリガーしないでください。それは infrahub-reporting-skill-gaps に属し、このスキルにペイロードを渡す前に、トラッカーに既存のレポートがあるかを確認し、バグか機能かを判断します。

スキルギャップの受け付け

このスキルは、infrahub-reporting-skill-gaps から準備済みのペイロード {type, title, body, searched, issue?} を伴って直接呼び出されることもあります。その呼び出し元にとって、type は bug、feature、または docs gap であり、そのスキルの 2 段階トリアージによってすでに決定されています。

ペイロードには repo が含まれておらず、ルーティングはあなたの役割です。 その呼び出し元は意図的に宛先を指定していないため、この表がマッピングが存在する唯一の場所です。

type	リポジトリ
bug	opsmill/infrahub-skills
feature	opsmill/infrahub-skills
docs gap	opsmill/infrahub

バグまたは機能はルールファイルに関するものであり、それはスキルリポジトリに存在します。docs gap は Infrahub 自身のドキュメントに関するものであり、それはメインリポジトリに存在し、スキルのメンテナーにはそれを書く権限がありません。ステップ 4 の前にこの表からリポジトリを解決し、その後はステップ 3 が実行されたかのように続行してください。

タイトルは docs-gap の場合 bug(docs): を使用し、[skill] セグメントは付けません。これは、発信元のスキルが opsmill/infrahub のメンテナーにとって何の意味も持たないためです。そのリポジトリ自身のタイトルに関する注意事項と、これと対になる bug:/feat: の慣例については reference.md を参照してください。

searched は、呼び出し元が自身のステップ 2 ですでに検索したリポジトリを指定し、issue は任意です。issue が存在する場合、呼び出し元は既存の issue をマッチさせています。それを対象として扱い、body をコメントとしてレンダリングし、ステップ 8 で gh issue create ではなく gh issue comment で投稿してください。

ステップ 4 は searched に依存します。 searched が今解決したリポジトリと等しい場合はスキップしてください。呼び出し元はすでにその正確な検索を実行しており、繰り返すと、すでに body に書かれている答えと矛盾する 2 つ目の答えを生むリスクがあります。異なる場合は通常どおり実行してください。これが docs-gap の場合です。呼び出し元は種類を知る前に opsmill/infrahub-skills を検索しますが、docs gap は opsmill/infrahub にルーティングされるため、そのトラッカーはまだ誰も確認していません。

この方法で呼び出された場合、分類（ステップ 2）はすでに決定されているため、スキップしてください。ステップ 3 の検出ロジックも適用されません。上記の表がそれを置き換え、種類はセッション自身の証拠からすでに確定しているため、ユーザーに確認するものは何もありません。環境情報の収集（ステップ 5）もスキップしてください。これは Infrahub サーバー、SDK、OS のバージョンを収集しますが、スキル自身のガイダンスに関するレポートにも、欠落しているドキュメントに関するレポートにも当てはまりません。ステップ 6 のレンダリングには、汎用テンプレートの代わりに呼び出し元のタイトルと本文を使用してください。ステップ 7〜9 は通常どおり続行します。レビューゲート、提出方法、確認です。

ワークフロー

以下の手順を順番に実行してください。すべてのユーザー確認ステップで停止し、明示的な確認なしに先へ進まないでください。

1. 問題を把握する

ユーザーがまだ説明していない場合は、自分の言葉で問題を説明するよう依頼してください。まだ深掘りせず、まず倾听してください。言及された製品名、バージョン番号、エラーメッセージ、ワークフローの文脈を記録してください。それらは以降のすべてのステップで役立ちます。

2. 分類する

これが バグ、機能リクエスト、質問・使用上のヘルプ のどれであるかを判断してください。分類が曖昧な場合にのみ、1〜2 回の追加質問を行ってください:

• 「以前は動作していて今は動作しないのですか、それともこれまで存在しなかったものですか？」
• 「再現ケースはありますか、それとも断続的な観察ですか？」
• 「望ましい動作はどこかに文書化されていますか、それともこれは新しく求めている機能ですか？」

ユーザーがすでに使用している回避策を説明している場合は、「機能リクエスト」に傾けてください（バグに回避策がある → 実際の問題は不足している人間工学です）。ユーザーがクラッシュ、誤った出力、500 レベルのエラーを説明している場合は、「バグ」に傾けてください。ユーザーが何かのやり方を尋ねている場合は、Issue を起票するのではなく、Discord/discussions へ誘導してください — サポートの質問のために Issue を開かないでください。

3. リポジトリへルーティングする

完全な 11 リポジトリのレジストリ、検出の手がかり、テンプレートの利用可否については reference.md を参照してください。次の検出ロジックを順番に適用してください:

1. ローカルの作業ディレクトリを読み、ファイルシステムの手がかり（infrahub.toml、pyproject.toml の依存関係、galaxy.yml、.claude-plugin/plugin.json など）を確認する
2. 検出された手がかりとユーザーの発言を照合する。Ansible の手がかりがないリポジトリで Ansible プレイブックについて不満を述べているユーザーでも、それは依然として Ansible の問題です。
3. 最も具体的な一致を選ぶ。

main をデフォルトとするルール: 検出が曖昧な場合、複数のリポジトリが同等に一致する場合、ユーザーがどのコンポーネントに問題があるかについて何らかの不確かさを示している場合、または症状がプラットフォーム層に存在する可能性が高い場合 — opsmill/infrahub をデフォルトとしてください。main リポジトリは、サブリポジトリが main へ戻すよりも、受け取った Issue をサブリポジトリへ再ルーティングする方が容易です。誤った専門サブリポジトリに傾くよりも、main に傾く方が安価です。

あなたの推測を一文の根拠とともにユーザーに提示し、確認または訂正を求めてください。例:

「pyproject.toml の infrahub-sdk と、InfrahubClient に言及したエラーに基づくと、これは opsmill/infrahub-sdk-python の Issue のようです。確認できますか？」

4. 重複を検索する

常にバグと機能の両方を検索してください。利用可能な最初の方法を使用してください:

1. gh CLI — gh search issues --repo <owner/repo> "<keywords>"。キーワードはユーザーの説明と、あればエラーメッセージの文字列から抽出してください。最初の検索で何も返らない場合は、同義語で 2 回目の検索を行ってください。
2. MCP GitHub サーバー — gh がインストールされていない場合は、ユーザーの環境で利用可能な GitHub MCP ツールを使用してください。
3. 手動 — どちらも利用できない場合は、GitHub の検索 URL をユーザーに伝え、確認を依頼してください。

上位 3〜5 件の一致を、タイトル、状態（オープン/クローズ）、一行の抜粋とともにユーザーに提示してください。次のように尋ねてください:

「あなたの Issue はこれらのいずれかに該当しますか？該当する場合は、新しい Issue を開くのではなくコメントを追加します。」

一致が存在する場合は、コメントモード に切り替え、2 つの経路のいずれかを選んでください。どちらにするかをユーザーに伝えてください:

1. 補完: この発生が、既存の Issue に欠けている情報（別のトリガー、影響を受ける 2 つ目のスキルやコンポーネント、新しい障害の形など）を追加する場合。新しい情報のみをコメントし、Issue にすでに書かれていることを繰り返さないでください。
2. プラスワン: この発生が新しい情報を何も追加しない場合。メンテナーが頻度を把握できるよう、別のヒットを記録する短いコメントを投稿し、既存の説明を繰り返さないでください。

いずれの場合も、ユーザーに Issue の URL を伝えてください。そうでなければ、新しい Issue の下書きに進んでください。

5. 環境情報の収集（バグの場合のみ）

機能の場合はこのステップをスキップしてください。バグの場合は、以下だけを収集します:

• 関連する製品のバージョン — 例: Infrahub サーバーのバージョン、SDK のバージョン、Ansible コレクションの バージョン、プラグインのバージョン。
• オペレーティングシステム + アーキテクチャ（例: macOS 14 arm64、Ubuntu 22.04 x86_64）。
• コンポーネントに関連する場合は Python またはランタイムのバージョン。

以上です。収集しないでください: ファイルパス、プロジェクト 構造、ログの逐語的な内容、環境のダンプ、docker compose ps の出力、その他内部状態が漏れる可能性のあるもの。 environment-info-sanitization ルール が、issue 本文に何を記載してよく、何を記載してはいけないかを規定しています — バグセクションを作成する前に読んでください。

バージョンの確認方法:

コンポーネント	コマンド
Infrahub サーバー	infrahubctl info（Infrahub Version の行）、または compose ファイルの image: タグを確認
Python SDK	infrahubctl info（SDK Version の行）、または pip show infrahub-sdk
Ansible コレクション	ansible-galaxy collection list opsmill.infrahub
Nornir プラグイン	pip show nornir-infrahub
Helm チャート	helm list -n <namespace>
infrahub-sync	infrahub-sync --version
infrahub-backup	infrahub-backup --version
MCP サーバー	MCP クライアントの設定を確認、または pip show infrahub-mcp
VS Code 拡張機能	VS Code の拡張機能パネル
Skills プラグイン	.claude-plugin/plugin.json の version フィールド

バージョンを正確に特定できない場合は、推測したり、より広範な 検出コマンドを実行したりするのではなく、unknown と記載してください。

6. issue のレンダリング

対象リポジトリに .github/ISSUE_TEMPLATE/ ディレクトリがある場合は、対応するテンプレート（バグの場合は bug_report.yml、 機能の場合は feature_request.yml）を取得し、 そのフォームフィールドに従ってください。使用するもの:

gh api repos/<owner>/<repo>/contents/.github/ISSUE_TEMPLATE/bug_report.yml --jq '.content' | base64 -d

issue テンプレートを提供しているリポジトリ:

• opsmill/infrahub
• opsmill/infrahub-sdk-python
• opsmill/infrahub-ansible
• opsmill/nornir-infrahub

テンプレートがないリポジトリは、このスキルの templates/bug.md または templates/feature.md にフォールバックします。

タイトルの慣例: <area>: <imperative summary> の形式を使用し、72 文字以内に収め、末尾に句読点を付けないでください。例:

• SDK: InfrahubClient.create() raises on empty list payload
• Schema: hierarchical generic loses parent on rename
• Docs: clarify human_friendly_id behavior for inherited nodes

7. ユーザーレビューのゲート（必須）

レンダリングされた issue をユーザーに提示します。表示するもの:

• 対象リポジトリと URL
• 最終的なタイトル
• 本文全体（markdown）
• これが新しい issue か、既存の issue へのコメントか

質問します: 「この内容でよろしいですか？ 進める前に追加または削除したい 項目はありますか？」

このステップをスキップしないでください。 ユーザーが内容を明示的に 承認するまで、ユーザーと一緒に反復してください。

8. 投稿方法の選択

内容が承認されたら、どのように投稿したいかをユーザーに尋ねます。新しい issue とコメントではコマンドが異なります。ステップ 7 で示された内容に 一致する列を選んでください:

方法	新しい issue	既存の issue へのコメント
CLI	gh issue create --repo <owner/repo> --title "..." --body "..."	gh issue comment <number> --repo <owner/repo> --body "..."
MCP GitHub サーバー	ユーザーが持っている場合はそれを使用します。呼び出す前にツール名を確認してください。	同様に、サーバーのコメントツールを使用します。
手動	タイトルと本文をコピー＆ペースト可能な markdown として出力し、https://github.com/<owner>/<repo>/issues/new を添えます。	本文をコピー＆ペースト可能な markdown として出力し、https://github.com/<owner>/<repo>/issues/<number> を添えます。

コメントにはタイトルがありません。レンダリング結果にまだ タイトルが残っている場合、ステップ 6 で誤った成果物を構築しています。コメント本文に タイトルを貼り付けるのではなく、戻ってやり直してください。

デフォルトを決して想定しないでください — 常に尋ねてください。ユーザーが 方法を選んだら、それを実行してください。

9. 確認

送信後、ユーザーに以下を伝えます。

• Issue の URL、またはコメントとして送信した場合は そのコメントのパーマリンク（gh/MCP 送信の場合）
• 起票またはコメントした内容の一行要約
• 更新情報を受け取るために Issue を購読できるという リマインダー

ルールのカテゴリ

プレフィックス	カテゴリ	説明
env	環境情報	Issue 本文に記載できるものとできないもの

索引については rules/_sections.md を 参照してください。

参考資料

• reference.md — 検出の手がかり、説明、テンプレートの 利用可否を含む 11 リポジトリのレジストリ。 手順 3 でこれを読んでください。
• templates/bug.md — .github/ISSUE_TEMPLATE/ が ないリポジトリ向けの汎用フォールバックバグテンプレート。
• templates/feature.md — 汎用フォールバック機能テンプレート。
• rules/environment-info-sanitization.md — 送信前に伏せ字にすべきもの。セキュリティ上重要です。 すべてのバグ報告でこれを読んでください。
• ../infrahub-common/rules/workflow-information-priority.md -- スキルコンテンツが最優先。真のギャップ（例: ノードの削除）に ついて docs.infrahub.app を参照する方法

アンチパターン

• ユーザーの明示的な承認なしに送信する。 手順 7 のユーザーゲートは任意ではありません。公開リポジトリへの 不意な GitHub Issue は取り消すのが困難です。
• 症状が曖昧なときにサブリポジトリで起票する。 迷ったときは opsmill/infrahub で起票し、メンテナーに再ルーティングを 任せてください。誤ったサブリポジトリへの Issue は、全員の 作業を増やします。
• 重複を起票する。 検索で一致するものがあれば、新しい Issue を 開くのではなく、新しい情報を加えたコメントを追加するのが 既定です。
• 完全なログや docker compose の出力を貼り付ける。 これらはホスト名、IP、コンテナ名、ときにシークレットを 漏らします。v1 ではバージョン + OS にとどめてください。
• サポートの質問をバグとして起票する。「X はどうやるの？」 は Discord や GitHub Discussions に属するもので、Issues では ありません。