call-diagnostics

Call Diagnostics & Repair

Analyze phone call observability data, detect problems, track them across calls, and recommend systematic repairs.

Usage

python3 $CLAUDE_CONFIG_DIR/skills/call-diagnostics/scripts/diagnose.py              # last call
python3 $CLAUDE_CONFIG_DIR/skills/call-diagnostics/scripts/diagnose.py --all        # all calls + repair recommendations
python3 $CLAUDE_CONFIG_DIR/skills/call-diagnostics/scripts/diagnose.py -t           # show timeline
python3 $CLAUDE_CONFIG_DIR/skills/call-diagnostics/scripts/diagnose.py -v           # verbose (show detail)
python3 $CLAUDE_CONFIG_DIR/skills/call-diagnostics/scripts/diagnose.py --all --tracker  # generate HTML tracker + open

When to use

• After every phone call: run on latest call to detect issues
• Before making fixes: run --all to see persistent patterns and repair recommendations
• Never apply ad-hoc patches — check the repair recommendations first to understand if the problem is persistent and what the systematic fix should be

Detections

• Tool returned too fast (<10ms) — likely error/not-found
• Hallucination — Gemini claimed action state without tool verification
• Inline task via work — recording/screenshot/play delegated instead of inline
• Long delay — >30s between user request and tool execution
• Repeated failures — same tool failing 3+ times
• Timestamp lag — caller speech logged after tool that it triggered
• Wrong tool — Gemini used the wrong tool for the request
• User correction — user explicitly corrected Sutando's behavior
• Unmet expectation — user repeated a request (not understood)
• Auto-invocation — tool called without matching user request

Repair workflow

ALWAYS follow this workflow. Never skip steps.

1. Diagnose: run --all --tracker to see the full picture across all calls
2. Identify persistent problems: only fix issues that appear across multiple calls. Ignore one-offs.
3. Find root cause: ask "why does this happen?" not "how do I patch this instance?"
4. Make ONE minimal fix: prefer prompt over code, prefer removing code over adding. If >20 LOC, reconsider.
5. Deploy and track: restart servers, then monitor the next 3+ calls in the tracker
6. Verify or revert: if the issue count doesn't drop after 2-3 calls, revert and try a different approach
7. Never modify source code for call tasks: when a user asks to change something during a call (subtitle color, video edit), use runtime tools (ffmpeg, scripts), not code changes

Repair types

When run with --all, analyzes patterns across all calls and recommends:

• prompt fixes — changes to Gemini system instructions or tool descriptions
• code fixes — changes to tool implementations (retry logic, return values)
• architecture fixes — structural changes needed
• unsolvable — inherent to the platform (e.g. STT timestamp lag)

Each recommendation includes evidence (frequency, trend), priority, and specific fix instructions.

HTML Tracker

--tracker generates /tmp/call-diagnostics-tracker.html with:

1. Latest call timeline (color-coded)
2. Issue tracker table (last 5 calls, rows = specific tool issues)
3. Line chart (errors/warnings over time)
4. Repair recommendations (prioritized with evidence)