home / skills / terrylica / cc-skills / settings-and-tuning

settings-and-tuning skill

safe

/plugins/tts-telegram-sync/skills/settings-and-tuning

This skill helps you configure TTS voices, speed, timeouts, queue depth, and bot settings for reliable, responsive messaging.

npx playbooks add skill terrylica/cc-skills --skill settings-and-tuning

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

6.1 KB

---
name: settings-and-tuning
description: Configure TTS voices, speed, timeouts, queue depth, and bot settings. TRIGGERS - configure tts, change voice, tts speed, queue depth, tts timeout, bot config, tune settings, adjust parameters.
allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
---

# Settings and Tuning

Configure all adjustable parameters for the TTS engine, Telegram bot, and supporting infrastructure. All settings are centralized in the mise.toml SSoT.

> **Platform**: macOS (Apple Silicon)

## When to Use This Skill

- Changing TTS voice (English, Chinese, or macOS `say` voices)
- Adjusting speech speed
- Tuning TTS timeouts or queue depth
- Configuring notification rate limiting or circuit breakers
- Adjusting prompt executor throttling
- Modifying session picker limits
- Changing audit log retention

---

## Requirements

| Component   | Required    | Installation                                      |
| ----------- | ----------- | ------------------------------------------------- |
| mise        | Yes         | `brew install mise` (for env loading)             |
| Bot running | Recommended | Changes to TTS/queue settings require bot restart |

---

## Workflow Phases

### Phase 0: Read Current Configuration

Read the current mise.toml to see all active settings:

```bash
cat ~/.claude/automation/claude-telegram-sync/mise.toml
```

All configurable values live in the `[env]` section. The file is the single source of truth for the entire stack.

### Phase 1: Identify What to Change

Present the config groups to the user via AskUserQuestion. Config groups:

| Group           | Settings                                                               | Description                                     |
| --------------- | ---------------------------------------------------------------------- | ----------------------------------------------- |
| TTS Voice       | `TTS_VOICE_EN`, `TTS_VOICE_ZH`, `TTS_VOICE_SAY_EN`, `TTS_VOICE_SAY_ZH` | Voice selection per language                    |
| TTS Speed       | `TTS_SPEED`                                                            | Speech rate multiplier                          |
| TTS Timeouts    | `TTS_GENERATE_TIMEOUT_MS`, `TTS_SAY_TIMEOUT_MS`                        | Generation and playback timeouts                |
| TTS Queue       | `TTS_MAX_QUEUE_DEPTH`, `TTS_STALE_TTL_MS`, `TTS_MAX_TEXT_LEN`          | Queue limits and staleness                      |
| TTS Signal      | `TTS_SIGNAL_SOUND`                                                     | Signal sound path (empty to disable)            |
| Rate Limiting   | `NOTIFICATION_MIN_INTERVAL_MS`, `SUMMARIZER_*`                         | Notification and summarizer throttling          |
| Prompt Executor | `PROMPT_*`                                                             | Prompt execution throttling and circuit breaker |
| Session Picker  | `SESSION_*`                                                            | Session scanning and display limits             |
| Audit           | `AUDIT_RETENTION_DAYS`                                                 | Log retention period                            |
| Model           | `HAIKU_MODEL`                                                          | Claude model for Agent SDK calls                |

### Phase 2: Edit Configuration

Edit the appropriate line(s) in `~/.claude/automation/claude-telegram-sync/mise.toml`. Use the Edit tool to make precise changes to specific values.

### Phase 3: Validate and Apply

1. Verify the edited value is within the valid range (see [Config Reference](./references/config-reference.md))
2. If TTS, queue, or rate limiting settings changed, restart the bot:

```bash
# Option A: If using mise tasks
cd ~/.claude/automation/claude-telegram-sync && mise run bot:restart

# Option B: Manual restart
pkill -f "bun.*main.ts" && cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts
```

1. Confirm new settings are active by checking bot logs or testing the affected feature

---

## TodoWrite Task Templates

### Template: Settings Adjustment

```
1. [Read] Read current mise.toml configuration
2. [Identify] Present config groups to user via AskUserQuestion
3. [Select] User selects setting category to modify
4. [Edit] Update mise.toml with new values
5. [Validate] Verify values are in valid range
6. [Apply] Restart bot to apply changes (if TTS or queue settings changed)
7. [Verify] Confirm new settings are active
```

---

## Post-Change Checklist

After modifying this skill:

1. [ ] Verify all config groups in SKILL.md match current mise.toml
2. [ ] Update config-reference.md if new env vars were added
3. [ ] Test that changed settings take effect after bot restart
4. [ ] Update `references/evolution-log.md` with change description

---

## Troubleshooting

| Issue                      | Cause                            | Solution                                               |
| -------------------------- | -------------------------------- | ------------------------------------------------------ |
| Settings not taking effect | Bot not restarted                | Restart bot after changing mise.toml                   |
| mise.toml parse error      | Invalid TOML syntax              | Check for missing quotes or unescaped chars            |
| Voice not found            | Invalid voice name               | Check voice catalog (Kokoro voices are case-sensitive) |
| Speed too fast/slow        | Value out of range               | Use 0.5 to 2.0 range for TTS_SPEED                     |
| Circuit breaker stuck open | Too many failures                | Wait for breaker timeout or restart bot                |
| Timeout too short          | TTS generation slow on first run | Model warmup takes longer; increase timeout            |

---

## Reference Documentation

- [Config Reference](./references/config-reference.md) - Full reference table with all env vars, defaults, valid ranges, and component ownership
- [mise.toml Reference](./references/mise-toml-reference.md) - Hub/spoke mise architecture, secret loading, and task file structure
- [Evolution Log](./references/evolution-log.md) - Change history for this skill

Overview

This skill centralizes configuration and tuning for the TTS engine, Telegram bot, and related infrastructure using a single source of truth (mise.toml). It provides a guided workflow to inspect, edit, validate, and apply changes to voices, speeds, timeouts, queue depth, rate limits, and other bot settings. The goal is safe, auditable changes with clear restart and verification steps to make settings take effect.

How this skill works

The skill reads the mise.toml SSoT to show active env settings and groups them for user selection. It guides edits to specific env keys (voice names, TTS_SPEED, timeouts, queue limits, rate limiting, prompt executor, session picker, audit retention). After edits it validates ranges, instructs a controlled bot restart if required, and recommends verifying changes by checking logs or running a functional test.

When to use it

Change the TTS voice for English, Chinese, or macOS 'say' voices
Adjust speech rate for clearer or faster playback
Increase or decrease TTS queue depth and stale TTL to match load
Tune generation or playback timeouts to accommodate model warmup
Modify notification rate limits, circuit breaker, or prompt throttling
Update audit log retention or session picker limits

Best practices

Always read the current mise.toml before making changes to avoid race conditions
Validate numeric values against documented ranges (e.g., TTS_SPEED 0.5–2.0)
Make minimal, single-purpose edits and restart the bot only when needed
Use versioned commits or a short change log entry for each configuration change
Test changes in a low-traffic window and verify by checking logs or feature behavior

Example use cases

Switch the English TTS voice to a different macOS 'say' voice for better clarity
Lower TTS_MAX_QUEUE_DEPTH to prevent large backlogs during spikes
Increase TTS_GENERATE_TIMEOUT_MS during model warmup to avoid early failures
Enable or disable the TTS signal sound by setting TTS_SIGNAL_SOUND path
Raise NOTIFICATION_MIN_INTERVAL_MS to reduce notification spam during bursts

FAQ

Do settings take effect immediately after editing mise.toml?

Most changes require a bot restart to take effect, especially TTS, queue, and rate-limiting settings. Restart instructions are provided.

What range should I use for TTS_SPEED?

Use 0.5 to 2.0 as a safe range; values outside that range can make speech unintelligible or too slow.