infrahub-reporting-skill-gaps

Infrahub スキルのギャップレポーター

概要

Infrahub のスキルは、問題があっても気づかれないまま失敗します。ルールが欠けていてもクラッシュすることはなく、モデルが自力で正解を見つけるまでに、11 回の往復と 4 回のユーザーへの促しが発生します。このスキルは、どのルールが欠けていたのか、間違っていたのか、あるいは不明瞭だったのかを特定し、改善案を課題レポートとして作成します。このスキル自体は何も登録せず、レポートの提出先も決定しません。完全に記入済みで、機密情報を削除した下書きを準備し、 infrahub-reporting-issues に引き渡します。このスキルは、11 リポジトリのレジストリ、振り分け、同意の確認、提出方法の選択、および確認を担います。このスキルの役割は、引き渡しまでです。

使用するタイミング

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

• 「何度もやり直すことになったので、その面倒だった点を報告してもらえますか？」
• 「スキルの使いにくさを報告してください。」
• 「スキーマスキルは、なぜこれを何度も間違えたのですか？」
• 「このスキルのガイダンスには何か足りないようです。修正できますか？」

Infrahub、SDK、またはその他の opsmill/infrahub-* 製品のバグには、このスキルを起動しないでください。その場合は infrahub-reporting-issues を使用します。問題なく完了した通常の Infrahub 作業にも、このスキルを起動しないでください。

ワークフロー

次の手順を順番に進めます。ゲートとなる各手順では必ず停止し、明示的な確認を得ずに先へ進んではいけません。

1. ギャップを検出して確認する

現在の会話から始めます。過去のセッションのトランスクリプトを確認するのは、ユーザーがそれを指示した場合だけです。トランスクリプトの探索方法とシグナルの場所については、reference.md を読んでください。

次に、検出手順を順番に実施し、問題の内容が説明できた時点で停止します。

1. 検証結果。 同じ対象で、失敗から成功への遷移があったかを確認します（infrahubctl schema load、object load、check run、transform run、pytest の実行）。自己評価ではないため、これが最も強い証拠です。ただし、最初の試行より前にスキルが読み込まれていた場合に限り、証拠として扱います。
2. カバレッジの確認。 ls skills/<skill>/rules/ を実行し、トピックを grep します。これにより、該当ファイルが特定されるか、ファイルが存在しないことがわかります。
3. 修正差分。 最初に作成したバージョンと、承認されたバージョンを比較します。この差分が、言い換えではなく、提案するルール変更です。
4. セッションの形状を示すカウンター。 再試行、編集の繰り返し、同じ質問の反復、ドキュメントを探しに行ったことなどです。これらは調査を開始するきっかけにはなりますが、調査を完了させる根拠にはなりません。

カウンターだけを根拠とした下書きは、まだ提出できる状態ではありません。どの調査が空振りだったかを伝え、停止してください。rules/evidence-detection-ladder.md を参照してください。

2. トラッカーを確認する

下書きを作成する前に、opsmill/infrahub-skills を検索します。この検索はレポートの形式を決めるものであり、レポートを作成するかどうかを決めるものではありません。一致するものがあればその課題にコメントし、一致するものがなければ信頼度を明記した新しい課題を作成します。rules/workflow-tracker-first.md を参照してください。

3. トリアージ：レベル 1、振り分け

問題がスキルの不具合なのか、製品の不具合なのか、あるいはどちらでもないのかを判断します。レベル 2 と下書き作成に進むのは、スキルの不具合のみです。rules/workflow-triage-classification.md を参照してください。

3b. トリアージ：レベル 2、バグ、機能追加、またはドキュメントの不足

スキルの不具合について、次の 3 つの結果のいずれかに分類します。バグ（ルールまたはリファレンスがトピックを扱っているにもかかわらず、モデルが間違えた）、機能追加（トピックを扱うルールがなく、ドキュメントを探しに行った結果、答えが見つかったか、そのような探索自体が発生しなかった）、またはドキュメントの不足（トピックを扱うルールがなく、ドキュメントを探しに行ったものの答えは見つからず、根底にある動作仕様は確定している）です。最後の条件は単なる詳細ではなく、ゲートです。ワークフローの定義が続いている場合や、意図的にドキュメント化されていない場合、まだ文書化するものはないため、下書きは一切作成せず、その理由をユーザーに伝えて停止してください。この分類により、ステップ 6 で下書きを作成する際に使うタイトルの接頭辞が決まり、受け取り側が振り分ける際にも使われます。rules/workflow-bug-vs-feature.md を参照してください。

4. 製品に関する場合は引き継ぐ

トリアージの結果、スキルのガイダンスではなく 根本的な製品に問題がある場合は、ここで作業を止め、 スキルの問題によるイシューを作成する代わりに infrahub-reporting-issues へ引き継いでください。rules/workflow-handoff-product-bugs.mdを 参照してください。

5. 該当する成果物を特定する

問題を防ぐべきだった具体的なルールファイル、または 該当するルールがないことを明記してください。ステップ1の プローブBではすでにこのファイルを確認しています。このステップでは、その結果を 根拠として引用します。該当するファイル、 またはカバー範囲の不足を明記できないドラフトは、 まだ提出できる状態ではありません。rules/evidence-cite-the-artifact.mdを参照してください。

6. ドラフトを作成して情報を伏せる

templates/skill-friction.mdに記入してください。 ステップ3bで決定したbug:／feat:／bug(docs):のタイトル接頭辞と、 ステップ2で決定した信頼度ラベルを使用します。rules/evidence-no-customer-data.mdに従い、 ユーザーのインフラストラクチャや組織を特定できる情報を伏せてください。 これはセキュリティ上きわめて重要で、ドラフトがこのスキルの外に 出る前に必ず適用してください。

ヘッダーには3つのバージョンを記載します。すべて揃っていなければ レポートは完成していません。

1. Skills：該当するスキル自身のSKILL.mdのフロントマターにあるmetadata.version。どのリビジョンのルールに問題があったかを示します。
2. Infrahub SDK：infrahubctl infoのSDK Version行から取得します。CLIフラグまたはクライアントメソッドに関するルールが、どのバージョンを対象としていたかを示します。
3. Infrahub：同じ出力のInfrahub Version行から取得します。スキーマの読み込み、ブランチの動作、またはチェックパイプラインに関するルールが、どのバージョンを対象としていたかを示します。

../infrahub-common/rules/connectivity-server-check.mdの指示に従って infrahubctl infoを実行してください。runnerのプレフィックスが重要です。

これらがなければ、メンテナーはガイダンス自体に問題があるのか、 実行環境より古いだけなのかを判断できません。これは、ルールを書き直すべきか、 バージョンに関する注記を追加すべきかの違いになります。バージョン値だけをコピーしてください。 infrahubctl infoにはサーバーアドレスとデプロイ ID も出力されますが、 rules/evidence-no-customer-data.mdでは それらの記載を禁止しています。3つのいずれかが読み取れない場合は unknownと記載し、決して推測しないでください。

これにより、引き継ぎ用の3つのフィールドtype、title、 bodyが作成されます。対象リポジトリは含まれません。 リポジトリ名の指定はこのスキルの役割ではなく、ドラフトにも 含めてはいけません。

ステップ2で一致するイシューが見つかった場合は、代わりにコメントを 作成してください。タイトルや、問題の説明の繰り返しは不要です。 このセッションで新たに得られた根拠のみを記載してください。

7. 引き継ぐ

infrahub-reporting-issuesを 呼び出し、ペイロード{type, title, body, searched, issue?}を渡してください。 ここで、searchedにはステップ2で検索したリポジトリを指定し、 issueは一致した場合にのみ設定します。repoフィールドはありません。 このスキルは、typeに基づいて独自のレジストリから宛先を特定し、 ここから先のレビューゲート、提出方法の選択、確認を担当します。 イシューの提出やコメントの投稿を直接行ってはいけません。rules/workflow-handoff-to-reporting.mdを参照してください。

8. 結果を伝える

引き継ぎで返された内容を1行で伝え、イシュー URLが作成された場合は そのURLを記載してください。受け手はすでにユーザーへの確認を済ませているため、 これは結果の伝達であり、再確認ではありません。トラッカーが永続的な記録であり、 このスキルは独自のローカル状態を保持しません。

ルールのカテゴリ

接頭辞	カテゴリ	説明
workflow-	ワークフロー	順序とゲート：トラッカーの確認、トリアージ、引き継ぎ（製品の不具合、またはスキルの不具合の提出のためにinfrahub-reporting-issuesへ）。いずれかを省略すると、メンテナーのトラッカーにノイズが生じるか、別の不整合な提出プロセスが発生します
evidence-	根拠	提出するイシューに記載してよい内容と、記載してはいけない内容。セキュリティ上きわめて重要です。イシューの本文は公開され、取り消せません

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

関連資料

• reference.md：根拠ソースの 優先順位、トランスクリプトの検出、摩擦のシグナル。 ステップ 1 で読んでください。
• rules/evidence-detection-ladder.md： ギャップが存在することを確認する 4 つのプローブと、 カウンターだけでは決して確認できない理由。 ステップ 1 で読んでください。
• templates/skill-friction.md： ステップ 6 で記入するドラフトテンプレート。
• rules/workflow-tracker-first.md： ドラフト作成前にトラッカーを検索し、作成する内容の 確信度を明記します。ステップ 2 で読んでください。
• rules/evidence-no-customer-data.md： ドラフト作成前に何を編集・削除するか。セキュリティ上 重要なため、ドラフト作成の前に必ず読んでください。
• rules/workflow-handoff-to-reporting.md： ペイロードを infrahub-reporting-issues に引き渡します。 直接起票してはいけません。ステップ 7 の前に読んでください。
• ../infrahub-common/rules/workflow-information-priority.md -- まずスキルの内容を確認し、実際にギャップがある場合は docs.infrahub.app を参照する方法

アンチパターン

• ルールの変更案なしで起票する。 作成または編集する ファイルと、そこに記載すべき内容を示していない摩擦 レポートには、実行可能な内容がありません。症状の説明から 修正方法を逆算する作業を、メンテナーに求めるべきでは ありません。
• 該当するスキルが不明なまま起票する。 ステップ 5 で スキルとルールファイル（またはルールファイルがないこと） を特定できない場合、レポートはまだドラフトを作成できる 状態ではありません。
• 再試行回数を起票する。 往復、追加の促し、編集の繰り返しで 測れるのはセッションであり、ルールセットではありません。 スキルとは無関係な理由でも増加します。たとえば、依頼が 不明瞭である、インスタンスの動作が遅い、ユーザーが考えを 変えたなどです。これらは調査のきっかけにはなりますが、 検証者の判定またはカバレッジの確認があれば調査を終えられます。
• トラッカーを確認せずにドラフトを作成する。 ステップ 2 は 省略できません。何も確認せずに作成したレポートは、進行中の イシューと重複するか、2 人目の観察者が発見できたはずの 唯一の情報源を失わせます。
• コメントではなく重複するイシューを起票する。 既存の イシューがその摩擦をすでに扱っている場合、2 つ目のイシューを 作成すると、根拠が 2 つのスレッドに分散します。より価値が あるのはコメントです。メンテナーに必要な裏付けとなります。
• 最初の観察結果を無視する。 観察が 1 回だけでも根拠は弱い というだけで、ゼロではありません。unconfirmed と記し、 判断はメンテナーに委ねてください。何も報告しなければ、 2 人目の観察者が見つけることはありません。
• 生のエラーテキストを編集・削除せずに貼り付ける。 エラー メッセージには、顧客のインフラを特定できるファイルパス、 ホスト名、ノードの種類が含まれています。貼り付けずに、 言い換えてください。
• 引き渡さずに直接起票する。 このスキルには、同意の確認、 重複検索、独自の提出方法がありません。ここで gh issue create を実行したり、イシューを起票したと主張したりすると、 infrahub-reporting-issues が提供する唯一のレビューゲートを 回避することになり、レビューされていない投稿が重複する おそれがあります。