MockInterviewer/interview-agent/.agents/skills/livekit-agents/references/freshness-rules.md

Freshness Rules for LiveKit Development

This document provides detailed guidance on maintaining accuracy when building with LiveKit Agents. These rules exist because model training data becomes outdated immediately, and LiveKit's SDK evolves rapidly.

The Core Problem

Coding agents (Claude, GPT, etc.) are trained on historical data. This training includes:

• Old versions of LiveKit documentation
• Outdated code examples from blogs and tutorials
• Previous SDK versions with different APIs
• Community answers that may no longer be accurate

When an agent "knows" something about LiveKit, that knowledge may be months or years out of date.

Verification Requirements

Before Writing Any LiveKit Code

1. Identify what needs verification

   • Method names and signatures
   • Configuration options and their types
   • Import paths and module structure
   • Default values and behaviors

2. Query the documentation

   • Use MCP to search for the specific feature
   • Read the current documentation, not cached knowledge
   • Look for version notes or recent changes

3. Cite your source

   • Note which documentation page informed the implementation
   • If something cannot be verified, explicitly state this

During Implementation

When writing code, verify:

Element	Why It Changes	How to Verify
Import statements	Module restructuring	Search docs for current import paths
Method signatures	API evolution	Look up method in API reference
Configuration keys	Naming conventions change	Check configuration documentation
Default behaviors	Defaults are tuned over time	Read parameter documentation
Event names	Event systems evolve	Check events/callbacks documentation

After Implementation

Before presenting code to the user:

• Confirm all APIs used are documented
• Verify example patterns match current best practices
• Check for deprecation warnings in documentation

What Cannot Be Verified

Some things legitimately cannot be verified against documentation:

• User's specific environment or configuration
• Integration with user's existing codebase
• Business logic and application requirements

When providing guidance on these topics, clearly distinguish between:

• "According to LiveKit documentation..." (verified)
• "Based on your requirements..." (application-specific)
• "This may need adjustment..." (uncertain)

Red Flags: When to Stop and Verify

Pause and verify against documentation when:

1. Writing from memory - If you're typing an API call without having just looked it up, verify it
2. "I think" or "I believe" - Uncertainty about LiveKit APIs requires verification
3. Complex configurations - Multi-option configurations are likely to have evolved
4. Error handling - Exception types and error formats change
5. Newer features - Recently added features have the highest drift risk

Communication with Users

When Verified

According to the LiveKit Agents documentation, the correct approach is...
[implementation]

When Partially Verified

The workflow structure follows LiveKit's documented patterns. However, I could not
verify [specific detail] against current documentation. Please confirm this matches
your SDK version.

When Unverified

I cannot verify this implementation against current LiveKit documentation. This is
based on general patterns and may require adjustment. I recommend:
1. Checking the official documentation at [link]
2. Testing this implementation before relying on it

MCP Server Unavailable

If the LiveKit MCP server is not installed or accessible:

1. Inform the user immediately - They should know verification isn't possible
2. Recommend installation - Point to https://docs.livekit.io/mcp
3. Proceed with caution - Clearly mark all LiveKit-specific code as unverified
4. Suggest manual verification - User should check docs before using the code

Do not pretend to have verified something when MCP access was unavailable.

Version Awareness

LiveKit Agents has distinct versions with potentially different APIs:

• Python SDK (livekit-agents)
• Node.js/TypeScript SDK (@livekit/agents)

Each has its own release cycle and API surface. When working with LiveKit:

• Determine which SDK the user is using
• Search documentation specific to that SDK
• Do not assume API parity between Python and Node.js versions

Examples of Drift

These examples illustrate why verification matters:

Configuration Changes

Old tutorials might show:

agent = VoiceAgent(config={"model": "gpt-4"})

Current API might be:

agent = VoiceAgent(llm=SomeLLMClass(...))

Method Renames

What was once:

agent.start_session()

Might now be:

agent.start()

Import Restructuring

Previous:

from livekit.agents.voice import VoiceAgent

Current:

from livekit.agents import VoiceAgent

None of these changes are predictable from training data. Only live documentation reflects current state.

Summary

1. Default to distrust - Assume any LiveKit knowledge from memory is outdated
2. Verify actively - Use MCP to check documentation before implementation
3. Communicate uncertainty - Tell users when something cannot be verified
4. Cite sources - Reference documentation when providing verified information
5. Recommend MCP - If unavailable, make installation a priority