Design an evidence-grounded diagnostic agent

[engkimo]

Summary

• add a detailed architecture and implementation plan for a VoxBench diagnostic agent
• define evidence-grounded claims, bounded read-only tools, deterministic analyzers, and citation validation
• design guided UI operations that can focus timeline evidence, open incidents, compare runs, and play recordings without arbitrary browser automation
• document the proposed OIDC operator authentication model and external LLM egress policy
• add a concise project memory file with agreed decisions, implementation order, and remaining environment-specific choices

Why

VoxBench already correlates SIP, RTP, pipeline, provider, runtime, configuration, and recording evidence on a shared run timeline. Operators still need specialized knowledge to interpret that evidence and navigate to the relevant points.

This design proposes an evidence-grounded diagnostic session rather than a generic chatbot. Deterministic code remains responsible for timing, packet, media, and rule calculations, while the model plans investigations, compares hypotheses, and explains supported conclusions. The same evidence references also drive a guided UI experience so the agent can show the operator what to inspect.

User and developer impact

• establishes the intended product experience before implementation begins
• separates deterministic diagnosis from model reasoning and presentation
• defines safe UI command and authorization boundaries
• provides a staged implementation sequence from internal refactoring through a read-only agent MVP
• records durable decisions for future contributors and implementation sessions

Validation

• git diff --check
• documentation-only change; no runtime tests were required

Notes

• this PR does not implement the diagnostic agent or change runtime behavior
• unrelated local screenshots and working files were intentionally excluded

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f15be276-d90e-41be-b2b1-bcab2709e7eb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}