gbrain-advisor

gbrain Advisor

規約： skills/conventions/brain-first.md を参照してください。このスキルは脳の先回り型の声として、よりよく運用する方法を所有者に伝えます。

契約

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

• 読み取り専用です。 gbrain advisor は変更を加えません。既存の脳の状態から、優先順位を付けたアクションの一覧を算出します。
• 表示するだけで、実行しません。 調査結果をユーザーに表示し、修正を実行する前に確認を求めます。すべての判断はユーザーが行います。
• しつこさには上限があります。 定期的な実行では、変化した項目または重大な項目だけを提示します。無視された低重要度の項目を毎回繰り返しません。

実行するタイミング

• ユーザーから「この脳をもっと活用するにはどうすればいいですか？」と尋ねられたときに、必要に応じて実行します。
• 以下の cron レシピを使って、毎週実行します（アイドル状態の脳にも「よりよく運用する方法」を通知します）。
• 毎月、アドバイザーはバックアップ対象範囲の判定結果も提示します（gbrain backup status — git リモートが設定されていないナレッジリポジトリを確認します）。警告があれば伝えてください。

実行方法

gbrain advisor --json

終了コードは重要度の判定基準（E2）です。0 は問題なし、1 は警告、2 は重大です。JSON ペイロードは { version, generated_at, worst, findings: [...] } です。各 finding には以下が含まれます。

• severity — critical | warn | info
• title — 重要な理由を示す1行の説明
• fix.command_argv — 修正に使う正確なコマンド（構造化された argv）
• fix.dispatch_id — --apply で安全に実行できる修正の場合に設定されます

調査結果への対応

1. 重要度の高い順に調査結果を確認します。

2. 上位1〜3件を、ユーザーのチャンネルや話し方に合わせて要約します。critical の項目（保留中のマイグレーションなど）を最初に伝えます。

3. 各項目について、fix.command_argv を示し、実行するかどうかを確認します。

4. ユーザーが同意し、調査結果に fix.dispatch_id がある場合は、明示的な確認を伴ってローカルで実行できます。

   gbrain advisor --apply <dispatch_id>
   

   --apply はローカルでのみ実行され、修正を構造化された argv として（シェルを介さずに）実行する前に確認を求めます。dispatch_id のない調査結果は自動実行できません。ユーザーの同意後に、該当する fix.command_argv を手動で実行してください。

5. ユーザーの承認なしに修正を実行してはいけません。

Cron レシピ（週次チェック）

cron-scheduler スキルを使って、週次ジョブを設定します。プロンプトは簡潔にしてください。ジョブでは、このスキルを読み込んでアドバイザーを実行するだけです。

• スケジュール： 週1回、静穏時間を尊重した時間帯（例：月曜日の現地時間09:00）。
• ジョブのプロンプト： Read skills/gbrain-advisor/SKILL.md and run gbrain advisor --json. If anything is critical or new since last run, ping me with the top items and the exact fix commands. Ask before fixing.
• 冪等性： アドバイザーは読み取り専用なので、二重実行されても問題ありません。

アドバイザーはローカルに実行履歴を記録するため、実行のたびにすべてを再掲するのではなく、前回の実行から新たに追加された項目をユーザーに伝えられます。

出力形式

アドバイザーの調査結果をユーザーに提示するときは、重要度を先に示し、ひと目で確認できるようにします。

🧠 gbrain checkup — 2 things worth your attention

CRITICAL  Schema migrations are pending.
          Fix: gbrain apply-migrations --yes   (want me to run it?)

WARN      gbrain 0.44 is available (you're on 0.43).
          Fix: gbrain upgrade

• 調査結果ごとに1つのブロックを使い、重要度の高い順に並べます。
• 修正に使う正確な fix コマンドを必ず示し、実行前に確認を求めます。
• 緊急性の高い項目がなければ、「脳の状態は良好です」と1行で伝えます。不要な作業を作り出してはいけません。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または notice ブロックについては、エージェント運用者プロトコルに従ってください。このスキル固有の対応は以下のとおりです。

• critical の調査結果（保留中のマイグレーションなど）には、gbrain apply-migrations --yes のような修正が含まれます。実行前にユーザーに確認してください。dispatch_id のない調査結果は自動実行できません。
• gbrain advisor が脳にアクセスできない場合（GBRAIN_DB_ACCESS マーカー）は、「調査結果なし」と報告せず、db-repair スキルに引き継いでください。

アンチパターン

• 確認せずに修正を実行する。 アドバイザーは契約上読み取り専用です。ユーザーから明示的な許可を得ずに、--apply（または任意のfixコマンド）を実行しないでください。
• 生のJSONをそのままユーザーに見せる。 調査結果をユーザーに伝わる表現にし、重要な点から伝えてください。
• 無視された軽微な項目を実行のたびに再度指摘する。 「前回の実行以降の新しい項目」の差分を使い、ユーザーが以前に対応しなかったことを尊重してください。
• infoをcriticalと同じように扱う。 ブロックして対応を求めるのはcriticalの調査結果（保留中のマイグレーション）のみにしてください。infoは控えめに注意を促すものです。
• ワークスペースのインストール状態を確認するためにMCPのadvisor opを呼び出す。 MCP経由でアドバイザーが返すのはbrain-stateのシグナルのみです。未インストールのスキルに関する調査結果の確認はローカルCLIの役割です。