tough-tongue/toughtongue-skills / skills/ttai-session-analyst
ttai-session-analyst
VerifiedTurns Tough Tongue AI sessions into evidence-backed reports. Reads sessions, scores, report cards, strengths, weaknesses, and transcripts from practice roleplays, AI phone calls, and meeting-bot calls for a Scenario, person, or date range, then writes team performance, Scenario health, or individual coaching reports with action items. Can also fill in missing analysis (ttai:analyze_session) after the user confirms. Use when the user asks "how is my team doing?", "top improvement areas for scenario X", "lowest-scoring sessions", "coaching report for Priya", or "session trends this month". Not for changing a Scenario, rubric, or prompt (ttai-agent).
Session Analyst
Pull sessions → aggregate per Scenario → write an evidence-backed report → optionally hand it to the user's deck, email, or docs tools.
Practice runs, AI phone calls, and meeting-bot joins all land as sessions.
Read-only by default. The only write is ttai:analyze_session, and it needs
explicit confirmation.
Hard rules
- Guide first. In a fresh conversation, call
ttai:read_guideunless its guide is in context. Some clients show tools asmcp__ttai__<name>. Thettai-agentskill holds the full tool catalog and entity model. - Scope first. For organization data, call
ttai:get_workspace_infoand pass anorganizations[].idasorg_idon every call. Never pass a slug. Omitorg_idfor personal scope. - Typed list first. Default to
ttai:list_resourceswith typesessions. Add a legacy filter (user_email,from_date/to_date,hasLearning,is_org) only when you need a person, a date window, learning flags, oranalytics_url— those switch to the enriched legacy list. Typed rows carryduration_secondsonce completed, anduser_metadatawhen set. - Count cheaply. For a count, call
ttai:list_resources(sessions)withlimit: 1, include_total: true. Never page through results just to count. - Request only needed fields. The typed list returns IDs, status, and timestamps unless
you ask for
participant,evaluation,transcript,extraction,recording, orprocessingininclude_fields. - Transcripts come only from
include_fields: ["transcript"]onttai:list_resources(sessions)(withfilters: {ids}) orttai:get_resource(sessions). The legacy enriched list never returns them. - One rubric per aggregate. Report-card topics and weights come from each Scenario's rubric. Aggregate per Scenario. Compare Scenarios qualitatively.
- Confirm before writing. Before
ttai:analyze_session, state the Scenario ID and session IDs and wait for a yes. See references/reprocess.md. - Scenario faults go to
ttai-agent. This skill diagnoses. It never edits a Scenario. - Privacy. Coaching reports name people. Confirm the audience before sending
per-person results to a group. Request
recordingininclude_fieldsonly when the user needs it.
Workflow
1. Scope
- Resolve the workspace:
ttai:get_workspace_info→org_id, or personal. - Resolve the Scenario. Reuse an ID already in context. Otherwise make one
ttai:list_resources(scenarios, query)call with the title, take the ID, and continue by ID. - Pin down the population: Scenario(s), date window, people, and how many sessions. When the window is vague, use the last 30 days and say so.
2. Pull
Every read below is ttai:list_resources or ttai:get_resource with type
sessions unless named; filters go in filters. Parameters and limits:
references/data-model.md.
- Recent sessions for a Scenario — list:
scenario_ids,include_fields: ["participant", "evaluation"],limit≤ 100, follownext_cursor. - Counts by status — list:
scenario_ids,statuses,limit: 1,include_total: true. - One person or a date window — list (legacy): one
scenario_idsvalue,user_email,from_date/to_date,is_org: truefor org-wide,limit≤ 500; page withnext_cursor. Rows carryanalytics_url,duration, andextraction_results. - Scenario-learning flags — list (legacy):
hasLearning: "issue". - Transcripts for chosen sessions — list:
ids,include_fields: ["transcript", "evaluation"]. - Full detail for one session — get:
id,include_fields: ["participant", "evaluation", "transcript"]. - Recording URL — get:
id,include_fields: ["recording_url"]returns the enriched record (transcript, recording URL, scenario overview). - Review links —
analytics_urlcomes on legacy-list rows; filter that list by person or window and match IDs. - Usage, minutes, member activity —
ttai:get_workspace_info(sections: ["usage"]),start_date/end_date(org-wide for EDIT+ org roles). - Phone call or bot outcomes —
ttai:list_resources(bots)(kinds,include_fields: ["failure"]) →session_idper record.
Notes:
- Legacy
from_date/to_datefilter onupdated_at, not creation time. Mention this when the window edge matters. - Sessions without
evaluation_results.final_scoreare unanalyzed. Exclude them from score math and report the count. Fill them in only if the user needs completeness (step 5).
3. Aggregate
Compute per Scenario:
- Score distribution. Mean, median, and range of
evaluation_results.final_score(0–10, already weighted by the rubric). State the analyzed count and the excluded count. - Per-topic breakdown. Group
report_card[]bytopicand average itsscore(0–10) across sessions. Show each topic'sweight(percent of the final score). Low score on a high-weight topic is the top improvement area. - Recurring weaknesses.
weaknessesandimprovement_results(improvement_areas,action_items) are markdown text. Cluster them into themes and count sessions per theme. Name a theme by its behavior ("pitches price before discovery"), not a category ("communication"). - Trend. Weekly buckets when the window spans 3+ weeks. Per-person averages for team views.
- Evidence. For each top theme, pull 1–2 transcripts for chosen IDs and quote the shortest excerpt that shows it. Reports without evidence read as opinion.
Fewer than ~10 analyzed sessions → report observations, not statistics, and say so.
4. Report
Use the matching template in references/report-templates.md:
- Team performance: "how is my team doing?"
- Scenario health: "is this Scenario working?"
- Individual coaching: one person, at most three focus areas
- Pattern map: "what do prospects actually say?" — counterpart moves, red
flags, and persona pools from transcripts, handed to
ttai-agentfor a Scenario build
Every report states the population and window, the score summary, the top 3–5
improvement areas with evidence, concrete actions, and analytics_url links for
sessions worth a human review.
5. Fill gaps (only on request)
Missing analysis → confirm IDs, ttai:analyze_session per session, poll.
Steps, polling, failure handling, and why external calls are not ingested
here: references/reprocess.md.
6. Distribute (optional)
Hand the report to the user's deck, email, or docs tools: one improvement area per slide or section, evidence quote included.
Recipes
- "Top 5 improvement areas for Scenario X, last 50 sessions."
ttai:list_resources(sessions)(scenario_ids,limit: 50,include_fields: ["evaluation"]) → per-topic averages and weakness themes → pull transcripts for 1–2 sessions per theme → Team performance report. - "The 5 lowest-scoring sessions and what went wrong." Collect the
population (typed list with
evaluation, or legacy for a date window) → sort byfinal_scoreascending → take 5 → transcripts viaids→ separate Scenario faults from user-skill gaps → Scenario faults go to thettai-agentskill with the diagnosis and transcript quotes. - "How did priya@example.com do this month?"
ttai:list_resources(sessions)(user_email,from_date= first of month,is_org: truein an org) → per-topic averages and trend → Individual coaching report with actions drawn fromimprovement_results.action_items. - "Is this Scenario working?" Status counts via
include_total(count oldactivesessions as abandoned) →ttai:list_resources(sessions)withhasLearning: "issue"for flagged transcripts → Scenario health report.
Pitfalls
- Status ≠ processing. Session
status:active,completed,archived,terminated(use for completion rates).post_session_status.state:idle,running,failed. - Stale
active. The legacy list reports anactivesession older than 40 minutes asterminated. Typed reads return the stored status, so abandoned sessions can still readactivethere. - Math on numbers. Use
scoreandfinal_score;score_strandoverall_scoreare display text. - Typed-list scope.
ttai:list_resources(sessions)returns other people's sessions only when the caller holds EDIT or higher on the Scenario (passscenario_ids) or in the selected organization. Otherwise it returns only the caller's own. An empty page can mean missing permission. - Advanced filters are REST-only.
meta_*and$gte_created_at-style filters are rejected over MCP (Unsupported argument). Typed rows returnuser_metadata; filter on it after fetching.
Key Files
- references/data-model.md: tools, parameters, limits, response fields, score scales, status values
- references/report-templates.md: team, Scenario health, coaching, and pattern-map formats
- references/reprocess.md:
ttai:analyze_sessionbackfill, confirmation and polling
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |