diagnostic-issue-resolver_skill
- TypeScript
14
GitHub Stars
1
Bundled Files
2 months ago
Catalog Refreshed
4 months ago
First Indexed
Readme & install
Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.
Installation
Preview and clipboard use veilstrat where the catalogue uses aiagentskills.
npx veilstrat add skill terrylica/cc-skills --skill diagnostic-issue-resolver- SKILL.md6.3 KB
Overview
This skill diagnoses and resolves common TTS and Telegram bot issues on macOS (Apple Silicon). It guides symptom collection, runs automated diagnostics, maps results to root causes, and applies targeted fixes with verification steps. The workflow minimizes downtime and preserves state where possible.
How this skill works
The skill inspects lock files, audio processes, bot process health, Kokoro environment status, MPS availability, and recent logs. It runs a focused set of shell and Python checks, maps outputs to a known-issue table, and recommends or executes the least-disruptive fix. Finally, it performs a verification TTS playback and a full health check.
When to use it
- No audio output from TTS
- Telegram bot is not responding to messages
- Kokoro engine errors or timeouts
- Audio plays twice or multiple audio processes detected
- MPS acceleration not available or failing
- TTS queue appears full or backed up
Best practices
- Collect symptoms first: error text, when it started, and recent changes
- Run diagnostics matching the symptom subset instead of blanket commands
- Prefer least-disruptive fixes (remove stale lock before restarting services)
- Verify fixes with a quick TTS test and a health check script
- Document root cause and steps taken to prevent recurrence
Example use cases
- Stale TTS lock prevents audio—detect stale /tmp/kokoro-tts.lock and remove it if no audio process is running
- Bot process crashed—detect missing bot PID and restart the bot under bun with --watch for development
- MPS acceleration broken—check torch.backends.mps.is_available() and run the installer to upgrade torch
- Double audio playback—detect multiple afplay processes, pkill them, and restart audio flow
- Queue backlog—inspect audit logs for queue depth and increase TTS_MAX_QUEUE_DEPTH or drain the queue
FAQ
If an audio process is active, do not remove the lock. Investigate which process owns audio playback, check recent audit logs, and identify a race condition or duplicate job creator.
How do I confirm MPS is available for Kokoro?
Run the Kokoro venv Python check: python -c "import torch; print(torch.backends.mps.is_available())" inside the Kokoro virtualenv. If False, run the kokoro installer with --upgrade to reinstall torch.
