Update to Tough Tongue AI

{
  "name": "scenario-refiner",
  "description": "Fix and refine live ToughTongue AI scenarios from real session evidence via the ttai MCP server. Diagnoses whether an issue lives in ai_instructions, tools_config, or strategy, then applies the smallest possible edit with ttai:update_scenario. Use when the user says \"refine the scenario\", \"fix the scenario\", \"the agent said X instead of Y\", \"it ended the call too early\", \"it skipped a step\", \"make it sound more natural\", or pastes a transcript or complaint about a live scenario.",
  "included_files": [
    {
      "relative_path": "references/runtime-behavior.md",
      "size_in_bytes": 7589
    }
  ],
  "skill_md_contents": "---\nname: scenario-refiner\ndescription: >\n  Fix and refine live ToughTongue AI scenarios from real session evidence via\n  the ttai MCP server. Diagnoses whether an issue lives in ai_instructions,\n  tools_config, or strategy, then applies the smallest possible edit with\n  ttai:update_scenario. Use when the user says \"refine the scenario\", \"fix the\n  scenario\", \"the agent said X instead of Y\", \"it ended the call too early\",\n  \"it skipped a step\", \"make it sound more natural\", or pastes a transcript or\n  complaint about a live scenario.\n---\n\n# Scenario Refiner\n\nDiagnose → plan → surgical edit → verify. Never expand tokens when you can\ntighten. The agent runs on a system prompt that is already long — every word\nyou add is a word the model has to ignore at runtime.\n\nRead [references/runtime-behavior.md](references/runtime-behavior.md) before\ndiagnosing anything about prompt assembly, tool registration, conductor, or\nsilence mechanics.\n\n## Prerequisites\n\n- The **ttai** MCP server must be connected. Tool references below use the\n  `ttai:` server prefix (e.g. `ttai:update_scenario`); some agents surface\n  these as `mcp__ttai__update_scenario`. If the tools are missing, point the\n  user at the repo README and <https://app.toughtongueai.com/developer> for a\n  `TTAI_PAT` token.\n\n## Workflow\n\n### Step 1: Gather evidence\n\n1. Call `ttai:list_organizations`; pass `org_id` on subsequent calls if the\n   scenario belongs to an organization.\n2. Fetch the scenario with `ttai:get_scenario` (needs the scenario ID — find\n   it via `ttai:list_scenarios` if the user only gave a name). Read the\n   **entire** `ai_instructions`, plus `strategy`, `tools_config`, and\n   `session_analysis`.\n3. Get the failure evidence:\n   - If the user pasted a transcript or complaint, use that.\n   - Otherwise pull sessions: `ttai:list_sessions` filtered by `scenario_id`\n     (and date range), pick the relevant ones (e.g. lowest scores), then\n     `ttai:get_sessions_batch` for details. Fetch `transcript_url` contents\n     for the actual conversation text.\n4. Identify the exact turn where things went wrong. Cross-reference: what did\n   the scenario PRESCRIBE for that moment, and what did the agent actually DO?\n   Quote both in your diagnosis.\n\nIf the transcript is in another language (Hindi, Hinglish, ...), do not\ntranslate — the scenario is in the same language. Quote the original.\n\n### Step 2: Diagnose root cause\n\nClassify into one of these buckets. Each maps to a different fix location.\n\n| Symptom | Likely cause | Fix location |\n|---|---|---|\n| Agent called `end_session` too early / too late / not at all | Tool timing instruction weak, or `add_to_system_prompt: false` | `ai_instructions` end-of-call block, or `tools_config.tools.end_session` |\n| Agent took the wrong conversation branch | Branch trigger words too narrow, or path priority unclear | `ai_instructions` flow section (strengthen trigger list or add tie-breaker rule) |\n| Agent used the wrong closing line | Closing rule not bound to the path it came from | `ai_instructions` closing section (bind closings to paths explicitly) |\n| Agent skipped a prescribed step/question | \"Read-the-room\" rule too aggressive, or step ordering implicit | `ai_instructions` — make step 1 → step 2 a hard sequence with NEVER skip |\n| Agent monologued / two questions in one turn | Style rules buried | Bold/cap a single rule in the style section; do not add a new section |\n| Agent revealed AI identity or said a tool name aloud | Guardrails section missing or weak | `ai_instructions` GUARDRAILS / THINGS YOU MUST NEVER DO |\n| Agent stayed silent too long, then ended the call | `silence.silence_threshold` too low, or `silence.end_session: true` | `strategy.silence` |\n| Wrap-up fired during active conversation | Conductor `time_seconds` too low or `end_turn: true` | `strategy.conductor.messages` |\n| Wrong voice / language / accent | Voice or language config | `appearance.voice`, `appearance.language_code`, `transcribe_config` |\n| Agent said a placeholder like `{{ firstname }}` literally | Missing-context fallback not specified | `ai_instructions` CONTEXT section — add \"If blank, do X\" |\n| Robotic opening / restarts opening when interrupted | Quoted speech in `welcome_instructions` | `strategy.welcome_instructions` — rewrite in directive form |\n\nIf the cause is architectural (template selection, tool registration,\nconductor injection), open\n[references/runtime-behavior.md](references/runtime-behavior.md) and cite the\nrelevant mechanism. Don't guess.\n\n### Step 3: Plan the edit\n\nBefore calling any tool, write the edit out — old text and new text side by\nside — and check it against these principles:\n\n**Token discipline (in priority order):**\n\n1. **Replace** existing text > **tighten** existing text > **add** new text\n2. If you must add, ask: can I delete something stale to compensate?\n3. Flag the user if the total `ai_instructions` delta exceeds +50 tokens (~3 lines)\n4. Never add a \"while I'm here\" change. One issue = one edit.\n\n**Effective prompt writing:**\n\n- **Imperative voice**: \"NEVER call end_session before X\" not \"The agent\n  should not call end_session before X\"\n- **NEVER / ALWAYS / ONLY caps markers** for hard constraints\n- **One concrete example** beats three abstract rules\n- **Bind rules to triggers**: \"When customer says X → do Y\" beats \"Be empathetic\"\n- **Forbid the failure mode by name**: if the agent skipped a step, write\n  \"NEVER skip [step], even if the issue seems minor\"\n\n**Where to put a new rule inside `ai_instructions`:**\n\n- Hard prohibition → `## GUARDRAILS` or `## THINGS YOU MUST NEVER DO`\n- Conditional behavior → inside the matching phase / path\n- Tool timing → right after the prescribed closing lines\n- Tone / style → the style rules block near the top\n\n### Step 4: Apply via `ttai:update_scenario`\n\n1. Send **only** `id` plus the fields you changed — partial updates are\n   supported, and untouched fields must not be re-sent (avoids clobbering\n   concurrent edits).\n2. For an `ai_instructions` edit: apply your surgical replacement to the full\n   fetched string and send the complete updated field. Verify no collateral\n   changes (whitespace, adjacent bullets).\n3. Pass `org_id` if the scenario belongs to an organization.\n\n### Step 5: Verify and report\n\n1. Re-fetch with `ttai:get_scenario` and confirm the change landed as planned.\n2. Conclude with exactly this structure:\n   - **Diagnosis** (1-2 sentences) — what went wrong and why\n   - **Change** — field + before/after summary\n   - **Token delta** — estimate (e.g. \"+38 tokens, under the 50-token threshold\")\n   - **Reminder** — the change applies to **new sessions only**; running\n     sessions keep their compiled system prompt\n\n## Quick recipes\n\n### \"Agent ended the call too early\"\n\n1. Search `ai_instructions` for `end_session`. Is there an explicit\n   \"ONLY after closing line AND customer farewell\" rule?\n2. If not, add a 3-4 bullet rule block right after the closing templates.\n3. Check `tools_config.tools.end_session.tool_settings.disconnectDelaySeconds`\n   — too low (< 8) on emotional calls feels abrupt.\n\n### \"Closing line was generic instead of path-specific\"\n\nStrengthen the closing section with: \"Based on the path you actually took\nabove, pick the matching closing — never substitute a generic 'thank you'.\"\n\n### \"Scenario scores dropped after a change\"\n\nPull sessions before and after the change date with `ttai:list_sessions`\n(`from_date` / `to_date`), compare `evaluation_results`, and check whether the\nprior edit introduced the regression before adding anything new.\n"
}