Voice as Source of Truth

Voice as Source of Truth establishes a single, declarative definition of a brand's voice, loaded programmatically by all AI agents, eliminating the need for redundant prompt instructions in every content request.

What it is

This approach dictates that each brand within Total Ventures maintains one `voice.md` file. This file lives in the brand's root directory, typically alongside `package.json` or `vercel.json`. It's structured with YAML frontmatter for metadata—like brand name, primary tone keywords, and target audience—followed by markdown prose outlining detailed voice guidelines. This prose covers aspects like desired sentence structure, vocabulary preferences, things to avoid, and specific examples. For instance, Total Formula 1's `voice.md` emphasizes direct, analytical language with a focus on technical accuracy, while Pregnancy Power Hour's is supportive and informative.

Why I do it this way

Consistency is the primary driver. When every AI agent—whether generating social posts, email copy, or blog articles—pulls from the exact same source, voice drift is minimized. This reduces the overhead of re-stating voice parameters in every prompt, which is inefficient and prone to human error. It also simplifies updates; a single edit to `voice.md` propagates across all content streams. This aligns with a broader strategy of Docs as Source, where critical operational knowledge is codified and loaded programmatically. This method ensures that the creative output, even when generated by agents, maintains a cohesive brand identity without constant manual oversight.

How it works in practice

I built a small internal package, `@totalventures/voice`, which exposes a `loadBrandVoice(brandName: string)` function. This function reads the `voice.md` file for the specified brand, parses the frontmatter, and returns a structured object containing the voice guidelines. Every AI agent I deploy, regardless of its specific task, begins by calling this function. For example, when an agent is tasked via Queue-Driven Attention to draft a social media update for Total Formula 1, its initial step is to `loadBrandVoice('total-formula-1')`. The resulting voice object is then injected into the system prompt for Claude Code or Gemini, informing the generation process. This applies across the stack: Vercel deployments for frontend content, Resend for email campaigns, and even internal documentation generated by agents for brands like Inky, all reference their respective `voice.md` files. Changes to `voice.md` are version-controlled and subject to the same review process as code, reinforcing the idea that voice is a core asset. This also means that when I Commit Often, Push Deliberately, any voice adjustments are immediately available to all downstream processes.

Where this breaks down

While effective for maintaining broad consistency, this approach can struggle with highly nuanced or rapidly evolving conversational contexts. If a brand needs to adopt a significantly different sub-voice for a specific campaign or audience segment, the `voice.md` can become overly complex or contradictory. It also assumes that the AI models can interpret and adhere to abstract guidelines perfectly, which is not always the case; some trial and error is still required to refine the prose instructions. For very small, ephemeral projects, the initial setup overhead of a dedicated `voice.md` might outweigh the benefits, making direct prompt instructions more pragmatic in those limited scenarios.