Diagnostic Issue Resolver

Platform: macOS (Apple Silicon)

When to Use This Skill

• TTS audio is not playing or sounds wrong
• Telegram bot is not responding to messages
• Kokoro engine errors or timeouts
• Lock file appears stuck
• Audio plays twice (race condition)
• MPS acceleration is not working
• Queue appears full or backed up

Requirements

• Access to

  ~/.claude/automation/claude-telegram-sync/

  (bot source)
• Access to

  ~/.local/share/kokoro/

  (Kokoro engine)
• Access to

  ~/.local/share/tts-telegram-sync/logs/

  (centralized logs)

Known Issue Table

stat /tmp/kokoro-tts.lock

rm -f /tmp/kokoro-tts.lock

pgrep -la 'bun.*src/main.ts'

cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts

~/.cache/huggingface/

kokoro-install.sh --install

TTS_MAX_QUEUE_DEPTH

stat /tmp/kokoro-tts.lock

pgrep -x afplay

python -c "import torch; print(torch.backends.mps.is_available())"

kokoro-install.sh --upgrade

pkill -x afplay

Workflow Phases

Phase 1: Symptom Collection

• What happened? (no audio, wrong audio, bot silent, error message)
• When did it start? (after upgrade, suddenly, always)
• What were you doing? (clipboard read, Telegram notification, manual TTS)

Phase 2: Automated Diagnostics

# Lock state
ls -la /tmp/kokoro-tts.lock 2>/dev/null && stat -f "%Sm" /tmp/kokoro-tts.lock || echo "No lock file"

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

# Bot process
pgrep -la 'bun.*src/main.ts'

# Kokoro health
~/.local/share/kokoro/.venv/bin/python -c "import kokoro; import torch; print(f'kokoro OK, MPS: {torch.backends.mps.is_available()}')"

# Recent errors in audit log
tail -20 ~/.local/share/tts-telegram-sync/logs/audit/*.ndjson 2>/dev/null | grep -i error

# Recent bot console output
tail -50 /private/tmp/telegram-bot.log 2>/dev/null | grep -i -E '(error|fail|timeout)'

Phase 3: Root Cause Analysis

• Lock file exists + mtime > 30s ago + no afplay = stale lock
• No bot PID found = bot crashed

• torch.backends.mps.is_available()

  returns False = MPS broken
• Multiple afplay PIDs = race condition

Phase 4: Fix Application

Phase 5: Verification

# Quick TTS test
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
  --text "Diagnostic test complete" --voice af_heart --lang en-us --speed 1.0 \
  --output /tmp/kokoro-tts-diag-test.wav && afplay /tmp/kokoro-tts-diag-test.wav && echo "OK"

# Full health check
~/eon/cc-skills/plugins/tts-telegram-sync/scripts/kokoro-install.sh --health

TodoWrite Task Templates

1. [Symptoms] Collect symptoms via AskUserQuestion
2. [Triage] Map symptoms to likely causes
3. [Lock] Check TTS lock state (mtime, PID, stale detection)
4. [Process] Check bot process and audio processes
5. [Kokoro] Verify Kokoro venv and MPS availability
6. [Logs] Check recent audit logs for errors
7. [Fix] Apply targeted fix for identified root cause
8. [Verify] Run health check to confirm resolution

Post-Change Checklist

• Root cause identified and documented
• Fix applied successfully
• Health check passes
• Test audio plays correctly
• No stale locks or orphan processes remain

Troubleshooting

1. Check the full bot console log:

   cat /private/tmp/telegram-bot.log

2. Check all NDJSON audit logs:

   ls -lt ~/.local/share/tts-telegram-sync/logs/audit/

3. Check system audio:

   afplay /System/Library/Sounds/Tink.aiff

   (if this fails, it is a macOS audio issue, not TTS)
4. Run a manual Kokoro generation outside the bot to isolate the problem
5. If all else fails, do a full teardown and reinstall using

   clean-component-removal

   then

   full-stack-bootstrap

Reference Documentation

• Common Issues -- Expanded diagnostic procedures for each known issue
• Lock Debugging -- Deep dive into the two-layer lock mechanism
• Evolution Log -- Change history for this skill