clean-component-removal

Clean Component Removal

Orderly teardown of TTS and Telegram bot components with proper sequencing to avoid orphaned processes and stale state.

Platform: macOS (Apple Silicon)

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

• User wants to uninstall the Kokoro TTS engine
• User wants to remove the Telegram bot
• User wants to clean up all TTS-related files
• User wants to do a full teardown before reinstallation
• User wants to remove specific components selectively

Requirements

• No special tools needed (removal uses only rm, pkill, and the install script)
• User confirmation before destructive operations

Removal Order

The removal sequence matters. Components must be torn down in this order to avoid orphaned processes or lock contention.

What Is NOT Removed (Unless Explicitly Asked)

These are preserved by default to allow easy reinstallation:

Workflow Phases

Phase 1: Confirmation

Use AskUserQuestion to confirm which components to remove. Present options:

1. Full teardown -- Remove everything (steps 1-4, ask about secrets)
2. TTS only -- Remove Kokoro venv + symlinks + temp files (steps 2-4)
3. Bot only -- Stop bot process (step 1 only)
4. Selective -- Let user pick individual steps

Phase 2: Stop Bot Process

# Check if bot is running
pgrep -la 'bun.*src/main.ts'

# Stop it
pkill -f 'bun.*src/main.ts' || echo "Bot was not running"

Phase 3: Remove Kokoro Venv

# Uses kokoro-install.sh --uninstall (removes venv, keeps model cache)
~/eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --uninstall

Phase 4: Remove Symlinks

# List existing symlinks first
ls -la ~/.local/bin/tts_*.sh 2>/dev/null

# Remove them
rm -f ~/.local/bin/tts_*.sh

Phase 5: Clean Temp Files

rm -f /tmp/kokoro-tts-*.wav
rm -f /tmp/kokoro-tts.lock

Phase 6: Optional Secret Removal

Only with explicit user confirmation:

# Show what would be removed
ls -la ~/.claude/.secrets/ccterrybot-telegram

# Remove (requires confirmation)
rm -f ~/.claude/.secrets/ccterrybot-telegram

TodoWrite Task Templates

1. [Confirm] Ask user which components to remove via AskUserQuestion
2. [Stop] Stop bot process
3. [Venv] Run kokoro-install.sh --uninstall
4. [Symlinks] Remove ~/.local/bin/ symlinks
5. [Temp] Clean /tmp/ TTS files
6. [Secrets] Optionally remove secrets (with confirmation)
7. [Verify] Confirm all selected components removed

Post-Change Checklist

• Bot process is not running (pgrep -la 'bun.*src/main.ts' returns nothing)
• Kokoro venv removed (ls ~/.local/share/kokoro/.venv returns "No such file")
• Symlinks removed (ls ~/.local/bin/tts_*.sh returns "No such file")
• No stale lock file (ls /tmp/kokoro-tts.lock returns "No such file")
• No orphan audio processes (pgrep -x afplay returns nothing)

Troubleshooting

Reference Documentation

• Evolution Log -- Change history for this skill

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
1. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
2. What worked better than expected? — Promote it to recommended practice. Document why.
3. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
4. Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.