diagnostic-issue-resolver

診断と問題の解決

症状を体系的に収集し、自動診断と的を絞った修正を通じて、よくあるテキスト読み上げの問題を診断して解決します。

このプラグインにはTelegramボットはもうありません（2026-09-24に廃止）。そのため、「ボットが応答しない」はこのスキルが扱う症状ではありません。

プラットフォーム：macOS（Apple Silicon）

---

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターが変わってしまった、または回避策が必要だった場合は、後回しにせず、すぐにこのファイルを修正してください。実際に再現できる問題がある場合にのみ更新してください。

このスキルを使用するタイミング

• 読み上げホットキーを押しても何も起きない、または前の選択範囲が読み上げられる
• 音声がおかしい、遅すぎる、速すぎる、または二重に再生される
• Kokoro エンジンのエラーやタイムアウトが発生する
• ロックファイルが解除されずに残る
• MLX の Metal アクセラレーションが機能しない

---

要件

• /tmp/kokoro-tts.log と /tmp/tts_errors.log へのアクセス（スクリプトのログ）
• ~/.local/share/kokoro/ へのアクセス（ローカルの Kokoro エンジン）
• http://[::1]:8780 の claude-tts-companion に接続するための curl

---

既知の問題一覧

問題	考えられる原因	診断	修正
ホットキーが無反応	バインド先がバージョン付きのパスになっている、またはホットキーツールに権限がない	押した直後に tail -20 /tmp/kokoro-tts.log を実行	~/.local/bin/tts_read_clipboard_wrapper.sh にバインドし、アクセシビリティを許可する
前の選択範囲が読み上げられる	コピーが反映される前にクリップボードを読み取っている	ログに古いテキストが表示される	tts_kokoro.sh ではなくラッパーを使用する（NSPasteboard の changeCount が変わるまで待機します）
音声が出力されない	古い TTS ロック	stat /tmp/kokoro-tts.lock /tmp/tts_kokoro.lock	tts_stop.sh
最初の単語が遅い	Companion が停止中で、Supertonic にフォールバックしている	curl -s --max-time 2 "http://[::1]:8780/health"	claude-tts-companion を起動する、またはフォールバックを許容する
速度キーを押しても何も起きない	速度設定時に Companion に接続できなかった	grep speed: /tmp/kokoro-tts.log | tail -3	Companion の起動後にもう一度押す
Kokoro がタイムアウトする（試聴時）	初回のモデル読み込み	~/.cache/huggingface/ を確認	ダウンロードが完了するまで待つか、kokoro-install.sh --install を再実行する
ロックがいつまでも解除されない	ハートビートプロセスが終了した	stat /tmp/kokoro-tts.lock と pgrep -x afplay	ロックが30秒以上古く、かつ音声プロセスがない場合は、tts_stop.sh を実行する
MLX アクセラレーションが遅い	Python または依存関係が正しくない	python -c "from mlx_audio.tts.utils import load_model; print('MLX OK')"	kokoro-install.sh --upgrade で再インストールする
音声が二重に再生される	2つのエンジンが動作している、または2回の押下が競合している	複数の afplay プロセスがないか確認する	tts_stop.sh を実行してから、1回だけ押す

---

ワークフローのフェーズ

フェーズ 1：症状の収集

AskUserQuestion を使って、ユーザーにどのような問題が起きているかを確認します。主な質問：

• 何が起きましたか？（無音、テキストが正しくない、速度が正しくない、音声が二重になる、エラー通知）
• いつから起きていますか？（アップグレード後、チェックアウトの移動後、突然、常に）
• 何をしていましたか？（ホットキーでの読み上げ、速度キー、音声の試聴、スクリプトの手動実行）

フェーズ 2：自動診断

症状に応じて、次のチェックのうち該当するものを実行します：

# Lock state (both locks)
for f in /tmp/kokoro-tts.lock /tmp/tts_kokoro.lock; do
  ls -la "$f" 2>/dev/null && stat -f "%Sm" "$f" || echo "No $f"
done

# Audio processes
pgrep -la afplay; pgrep -la say

# Which engine the last presses used, and any errors
tail -30 /tmp/kokoro-tts.log 2>/dev/null
tail -20 /tmp/tts_errors.log 2>/dev/null

# Primary engine
curl -s --max-time 2 "http://[::1]:8780/health" || echo "companion down"

# Local Kokoro health
~/.local/share/kokoro/.venv/bin/python -c "from mlx_audio.tts.utils import load_model; print('MLX-Audio OK')"

# Links the hotkeys call
ls -la ~/.local/bin/tts_*.sh

フェーズ 3：根本原因の分析

診断結果を上記の既知の問題一覧に照らし合わせます。よくあるパターン：

• ロックファイルが存在する + mtime が 30 秒を超えている + afplay がない = 古いロック
• 押すたびにログに engine=supertonic と表示される = コンパニオンが停止
• 押した後にログが何も表示されない = ホットキーがスクリプトを実行していない（バインドまたは権限）
• from mlx_audio.tts.utils import load_model に失敗する = MLX-Audio の破損
• afplay の PID が複数ある = 競合状態

フェーズ 4：修正の適用

既知の問題一覧にある対象の修正を適用します。まずは常に、最も影響の少ない修正を試してください。再生関連の問題には tts_stop.sh を使うと安全にリセットできます。

フェーズ 5：検証

修正を適用した後、問題が解決したことを確認します：

# Same path a hotkey takes
echo "Diagnostic test complete" | pbcopy && ~/.local/bin/tts_read_clipboard_wrapper.sh; echo "exit=$?"

# Local engine
bash "$(cc-plugin-root tts-tg-sync)/scripts/kokoro-install.sh" --health

---

TodoWrite タスクテンプレート

1. [Symptoms] Collect symptoms via AskUserQuestion
2. [Triage] Map symptoms to likely causes
3. [Lock] Check both TTS locks (mtime, PID, stale detection)
4. [Engine] Check the companion and the Supertonic fallback via /tmp/kokoro-tts.log
5. [Kokoro] Verify Kokoro venv and MLX-Audio availability
6. [Fix] Apply targeted fix for identified root cause
7. [Verify] Run the wrapper and the health check to confirm resolution

---

変更後のチェックリスト

• 根本原因を特定し、記録した
• 修正を正常に適用した
• ヘルスチェックに合格した
• テスト音声が正しく再生される
• 古いロックや孤立プロセスが残っていない

トラブルシューティング

このスキルはトラブルシューティング用のスキルです。標準の診断で問題を特定できない場合：

1. デバッグログを有効にして Supertonic のパスを再実行します：DEBUG=1 TTS_ENGINE=supertonic ~/.local/bin/tts_read_clipboard_wrapper.sh。次に /tmp/tts_debug.log を読み込みます（Kokoro のパスは /tmp/kokoro-tts.log にのみログを記録します）
2. システム音声を確認します：afplay /System/Library/Sounds/Tink.aiff（失敗する場合は TTS ではなく、macOS のオーディオの問題です）
3. 各エンジンを順に強制して実行します：TTS_ENGINE=kokoro … および TTS_ENGINE=supertonic …
4. tts_generate.py を使って Kokoro の生成を手動で実行し、ローカルエンジンを切り分けます
5. それでも解決しない場合は、clean-component-removal を実行してから full-stack-bootstrap を使い、完全に削除して再インストールします

---

参考ドキュメント

• よくある問題 -- 既知の問題ごとの詳細な診断手順
• ロックのデバッグ -- ロック機構の詳細
• 進化ログ -- このスキルの変更履歴

実行後の振り返り

このスキルの実行が完了したら、タスクを終了する前に振り返ります：

0. 自分の位置を確認します。 — 編集する前に、この SKILL.md の正式なパスを見つけます（このスキル名で Glob を実行）。すべての修正対象はこのファイルと同階層の references/ のみです。他のドキュメントは対象にしないでください。
1. 何が失敗しましたか？ — 原因となった指示を修正します。再発する可能性がある場合は、アンチパターンとして追加します。
2. 予想以上にうまくいったことは何ですか？ — 推奨プラクティスとして取り入れます。理由も記録します。
3. 何が現状とずれていましたか？ — 現状に合わなくなったスクリプト、参考資料、外部依存関係はすぐに修正します。
4. 記録します。 — すべての変更について、きっかけ、修正内容、根拠を進化ログに記録します。

先延ばしにしないでください。次回の実行では、ここに残した状態が引き継がれます。