settings-and-tuning

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)

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

• 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:

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)
2. If TTS, queue, or rate limiting settings changed, restart the bot:

# 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 - Full reference table with all env vars, defaults, valid ranges, and component ownership
• mise.toml Reference - Hub/spoke mise architecture, secret loading, and task file structure
• 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.

---

---