connection-doctor

name	connection-doctor
description	Diagnose enabled external connections with read-only checks and report status plus next actions. Use for 「接続チェックして」 or connection failures.

connection-doctor — 外部接続の一括診断

初心者が一番躓く「外部ツールとの繋ぎ込み」の切り分けを 1 コマンド化する skill。 ユーザーが「接続チェックして」「○○が繋がらない」と言ったら発動する。

原則

• registry を尊重する:最初に [[.codex/connections.yaml]] を読む。disabled の接続はチェックしない(未設定はその人の選択)。unconfigured は ➖ で報告し、[.codex/skills/connection-setup/SKILL.md]を案内する。全接続が unconfigured なら、個別診断より先にセットアップウィザードを提案する
• read-only:診断のみ。設定変更・トークン再発行・ファイル削除はしない(修復は提案として提示し、対応する [[Meta/connections/README.md]] のガイドへ誘導する)
• graceful degradation:1 つのチェックが失敗しても全体を続行する。タイムアウトは各チェック 30–180 秒
• secrets を表示しない:トークン値・URL 内 token は「設定あり / なし」だけ報告する。値を echo しない・会話に貼らない
• 特定の接続だけ聞かれたら(「Slack だけ見て」)、その接続のチェックのみ実行する

チェック手順

-1. registry 読み込み

.codex/connections.yaml を読み、enabled の接続だけを §1 の診断対象にする(disabled はスキップ、unconfigured は ➖ 行として表にだけ載せる)。

0. 前提レイヤー

#	チェック	コマンド / 方法	判定
0-1	vault git	git -C {vault} status --short	repo として動くか
0-2	Codex CLI(任意)	codex --version	無ければ「Level 1 未導入(任意)」として ℹ️
0-3	Hermes CLI	hermes --version	無ければ以降の接続チェックは全部スキップし、[[GETTING-STARTED.md]] Level 1 へ誘導
0-4	Hermes 応答	hermes chat -q "reply with exactly: PONG" -Q(timeout 180s)	応答があるか。LLM バックエンド設定の生死がここでわかる

Windows 日本語環境では PYTHONUTF8=1 を設定してから hermes を呼ぶ(cp932 問題 → [[.codex/skills/hermes-query/SKILL.md]])。

1. 接続レイヤー(それぞれ独立・失敗しても続行)

接続	静的チェック(設定の存在)	動的チェック(実疎通・pull)
GitHub	.hermes/.env 等に GITHUB_PERSONAL_ACCESS_TOKEN のキーが存在するか(grep -c で有無のみ)	hermes chat -q "GitHub MCP で <Code-Map 先頭の repo> の最新コミット 1 件" -Q。Maps/Code-Map.md に repo が列挙されているかも確認
Google Calendar / Tasks	~/.hermes/google_token.json の存在	[[.hermes/skills/vault-capture/google-auth/SKILL.md]] の手順で Hermes runtime Python を HERMES_RUNTIME_PY に解決し、$HERMES_RUNTIME_PY .hermes/skills/vault-capture/google-auth/scripts/authorize.py --check（AUTHENTICATED + scope 一覧）。ics 経路は calendars.local.json の存在 + fetch_calendar_ics.py --format md
Gmail	上記 --check のスコープ一覧に gmail.* が含まれるか	hermes chat -q "Gmail の未読メール件数だけ教えて" -Q
Google Drive	コネクタ経路は コア側の Drive ツールが使えるか(ツール有無で判定)。Hermes 経路はスコープ一覧に drive	コネクタ:Drive 検索を 1 回実行 / Hermes:hermes chat -q "Drive で適当なファイルを 1 件検索してタイトルだけ" -Q
Slack	.hermes/.env に SLACK_BOT_TOKEN / SLACK_USER_TOKEN / SLACK_ALLOWED_USERS のキー有無	hermes chat -q "Slack で自分の user info を users.info で確認して" -Q
Discord	.hermes/.env に DISCORD_BOT_TOKEN のキー有無 + 自作 discord-capture skill の存在	hermes chat -q "Discord bot で参加サーバ一覧を確認して" -Q
RSS	.hermes/feeds.local.yaml の存在	直近 7 日の Inbox/*/clippings/ に source: "rss: のファイルがあるか(無ければ「RSS 巡回」未実行の可能性として ℹ️)
AI 議事録	Genspark アダプタ利用時のみ:gsk が PATH にあるか(command -v gsk)。capture extension 経路なら直近の Inbox/*/mtgs/ の有無

2. パイプラインレイヤー(capture 実績)

直近 7 日の Inbox/{date}/{source}/ を走査し、source ごとの最終 capture 日を出す:

find {vault}/Inbox -mindepth 2 -maxdepth 2 -type d | sort -r | head -30

「接続は生きているのに capture が 5 日前で止まっている」のような運用の切れ目もここで見つける。

報告フォーマット

結論 → 表 → 次アクション の順。例:

## 🔍 接続診断結果(2026-07-19)

**結論**:GitHub / Google は正常。Slack は User トークン未設定(検索系のみ不可)。

| 接続 | 状態 | 最終 capture | 次のアクション |
|---|---|---|---|
| Hermes 本体 | ✅ | — | — |
| GitHub | ✅ | 2026-07-18 | — |
| Google Cal+Tasks | ✅ | 2026-07-19 | — |
| Slack | ⚠️ | 2026-07-14 | SLACK_USER_TOKEN を追加 → Meta/connections/slack.md §3.2 |
| Genspark | ➖ 未設定 | — | 使うなら Meta/connections/genspark.md |
| Notion | ➖ 未設定 | — | 使うなら Meta/connections/notion.md |

• ✅ 正常 / ⚠️ 一部問題 / ❌ 不通 / ➖ 未設定・無効(未設定はエラー扱いしない — 全接続任意が設計。disabled は表からも省略してよい)
• 各 ⚠️ / ❌ には原因の推定 + 該当ガイドの「よくある躓き」該当行を 1 行で添える
• 修復コマンドは提示するだけで実行しない(ユーザー承認後に実行)

関連

• [[.codex/connections.yaml]] — 診断対象を決める registry
• [[.codex/skills/connection-setup/SKILL.md]] — 対話式セットアップ(unconfigured の誘導先)
• [[GETTING-STARTED.md]] — 段階的セットアップ(Level 0–2)
• [[Meta/connections/README.md]] — 接続別ガイド(修復手順の誘導先)
• [[.codex/skills/hermes-query/SKILL.md]] — pull 経路の呼び出し規約
• [[.codex/rules/agent-boundaries.md]] §6 — 接続の所有マップ