{"id":10131,"plugin_id":"plugin_asdk_app_6a60a89a6bec81918b6155f03f66681a","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T22:56:28.654Z","digest":"9bbbedd782b65c9f5c6166a63c540432e2580f22bbe6e7a520acbff34230e8f3","against":null,"payload":{"name":"session-analyst","description":"Analyze ToughTongue AI practice-session performance and build reports via the ttai MCP server. Pulls sessions with scores, strengths, and weaknesses, aggregates patterns across a team or scenario, and produces structured reports with improvement areas and action items. Use when the user asks \"how is my team doing?\", \"top improvement areas for scenario X\", \"pull the lowest-scoring sessions\", \"build me a coaching report\", \"session trends this month\", or wants session data turned into a deck, email, or dashboard.","included_files":[{"relative_path":"references/report-templates.md","size_in_bytes":3887}],"skill_md_contents":"---\nname: session-analyst\ndescription: >\n  Analyze ToughTongue AI practice-session performance and build reports via\n  the ttai MCP server. Pulls sessions with scores, strengths, and weaknesses,\n  aggregates patterns across a team or scenario, and produces structured\n  reports with improvement areas and action items. Use when the user asks\n  \"how is my team doing?\", \"top improvement areas for scenario X\", \"pull the\n  lowest-scoring sessions\", \"build me a coaching report\", \"session trends\n  this month\", or wants session data turned into a deck, email, or dashboard.\n---\n\n# Session Analyst\n\nPull session data → aggregate patterns → produce a structured report →\noptionally hand off to slides/email tools for distribution.\n\n## Prerequisites\n\n- The **ttai** MCP server must be connected. Tool references below use the\n  `ttai:` server prefix (e.g. `ttai:list_sessions`); some agents surface\n  these as `mcp__ttai__list_sessions`. 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## Data model (what a session gives you)\n\nEach session from `ttai:list_sessions` / `ttai:get_sessions_batch` includes:\n\n- Identity: `scenario_id`, `scenario_name`, `user_name`, `user_email`\n- Lifecycle: `status`, `created_at`, `completed_at`, `duration_minutes`\n- `evaluation_results`: `final_score`, `strengths`, `weaknesses`, and\n  `report_card[]` — per-topic `{topic, score, note, weight}`\n- `improvement_results`: `improvement_areas`, `action_items`, `resources`\n- `extraction_results`: structured variables (if the scenario extracts them)\n- `transcript_url` (signed URL — fetch it for the conversation text) and\n  `analytics_url` (human-viewable analysis page)\n\n`report_card` topics are the backbone of aggregation: they are consistent\nwithin a scenario because they come from its rubric.\n\n## Workflow\n\n### Step 1: Scope\n\n1. Call `ttai:list_organizations`. Team analysis almost always needs an\n   `org_id` — pass it on every call, along with `is_org: true` on\n   `ttai:list_sessions` for org-wide data.\n2. Resolve the scenario: `ttai:list_scenarios` if the user gave a name, not\n   an ID.\n3. Confirm the window and population: which scenario(s), which date range\n   (`from_date` / `to_date`), which people (`user_email` filter), how many\n   sessions.\n\n### Step 2: Pull\n\n- `ttai:list_sessions` with `scenario_id`, date filters, and pagination\n  (`page`, `limit`). Iterate pages until you have the requested population —\n  check the page metadata rather than assuming one page is everything.\n- Sessions missing `evaluation_results`: either exclude them from scoring\n  aggregates (note the count), or backfill — call `ttai:post_process_session`\n  for each, then re-fetch after a wait and check that `evaluation_results`\n  appeared. Backfill only when the user needs completeness.\n- Deep dives (outliers, disputed scores): `ttai:get_sessions_batch` with the\n  session IDs, then fetch `transcript_url` contents for the actual\n  conversation.\n\n### Step 3: Aggregate\n\nCompute, at minimum:\n\n- **Score distribution**: mean, median, range of `final_score`; flag the\n  count of unanalyzed sessions excluded.\n- **Per-topic breakdown**: average `report_card` score per topic, weighted by\n  `weight`. The lowest topics are the improvement areas.\n- **Recurring weaknesses**: cluster `weaknesses` and `improvement_areas` text\n  across sessions into themes; count occurrences. Name each theme by the\n  behavior, not an abstraction (\"jumps to price before discovery\" beats\n  \"communication issues\").\n- **Trend**: score over time if the window is long enough (week buckets work\n  well); per-person averages for team views.\n- **Evidence**: for each top theme, pull 1-2 short transcript quotes from\n  representative sessions. Reports without evidence read as opinion.\n\nFor org-wide rollups (usage, member breakdown, time series),\n`ttai:get_analytics` with `is_org_wide: true` complements per-session\naggregation.\n\n### Step 4: Report\n\nUse the matching template from\n[references/report-templates.md](references/report-templates.md):\n\n- **Team performance report** — \"how is my team doing?\"\n- **Scenario health report** — \"is this scenario working?\" (pairs with the\n  scenario-refiner skill when the answer is no)\n- **Individual coaching report** — one person, one skill gap, action items\n\nAlways include: population and window, score summary, top 3-5 improvement\nareas with evidence, concrete action items, and `analytics_url` links for\nsessions worth reviewing by a human.\n\n### Step 5: Distribute (optional)\n\nIf the user wants a deck, email, or document, hand the report content to\ntheir connected tools (slides MCP, email MCP, docs). Keep the structure:\none improvement area per slide/section, evidence quote included.\n\n## Recipes\n\n### \"Top 5 improvement areas for scenario X, last 50 sessions\"\n\n`ttai:list_scenarios` (resolve ID) → `ttai:list_sessions` (scenario_id,\nlimit 50, org context) → aggregate report_card topics + weakness themes →\nTeam performance report → deck if asked.\n\n### \"Pull the 5 lowest-scoring sessions and find out what went wrong\"\n\n`ttai:list_sessions` (scenario_id + window) → sort by\n`evaluation_results.final_score` ascending, take 5 →\n`ttai:get_sessions_batch` → fetch transcripts → diagnose common failure\npatterns → if the fault is in the scenario (not the users), hand off to the\n**scenario-refiner** skill with the diagnosis.\n\n### \"How did [person] do this month?\"\n\n`ttai:list_sessions` (user_email + from_date) → per-topic averages, trend\nacross their sessions → Individual coaching report with action items from\n`improvement_results`.\n\n### Automated post-call coaching (webhook-driven)\n\nFor teams wiring this into pipelines (e.g. every real sales call gets a\ncoaching report): see the recipe in\n[references/report-templates.md](references/report-templates.md) —\n`ttai:create_session` ingests an external transcript against a coaching\nscenario, `ttai:post_process_session` triggers analysis, poll until\n`evaluation_results` appears, then format and send the report.\n\n## Pitfalls\n\n- **Don't average across different scenarios' report cards** — topics and\n  weights differ per rubric. Aggregate per scenario, compare qualitatively.\n- **Small samples**: below ~10 analyzed sessions, report observations, not\n  statistics — and say so.\n- **Session status**: only `completed` sessions have meaningful duration and\n  results; exclude `in_progress` and `failed` from aggregates.\n- **Privacy**: coaching reports name individuals. Confirm the audience before\n  distributing anything per-person to a group channel.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}