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

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:

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

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.