Caleb Stacy

Verso Index

Product guidance and voice fingerprints

The Index was our content guidance, reorganized so an agent could use it. Each product had a file that held its guidance, its rules and its voice fingerprint, a set of measurements taken from the language that product had already shipped. The Agent read from those files, the Engine ran the rules and measured drafts against the fingerprint, and a content designer could challenge any line and have the change reviewed by the lead who owned it.

Question
How do we turn guidance written for people into something an agent can follow?
Problem
“Guidance” was one word for many kinds of things: hard rules, judgment calls, how to think about users, what not to do. It was written for people, much of it was subjective, and it was scattered across documents, chats and spreadsheets. We had told agents the target without giving them the means to reach it.
Solution
I sorted the guidance by kind and translated every rule with a yes or no answer into a check the Engine could run. For voice and tone, I measured the strings each product had already shipped and kept the result as a fingerprint. Every change went through the product’s lead content designer.
Outcome
Against the same targets, the Agent with its checks and a product’s fingerprint was much more accurate than agents built from a prompt file alone. Much less had to sit in a prompt, and leads approving diffs ironed out inconsistencies in the guidance over time.

One word for many kinds of guidance

A content index is a version of a team’s guidance that a language model can use. Our guidance site stayed the record of what had been decided, and the Index was the runnable form of it. The pages I started from held several kinds of guidance at once: hard rules, judgment calls, advice about users, and things to avoid. A title limit has an answer you can count. Whether a notification feels useful takes judgment, and a note about where people read it helps you make that judgment.

People handle that mix without noticing. An agent got every line the same way, as a sentence in a prompt, so we had told it the target and not the means to that end. That isn’t a criticism of the people who wrote our standards. All guidance is written for people, and we are good at closing gaps that agents can’t. Products also differ in ways a general instruction can’t capture. Instagram, Threads and Horizon all perform humor differently, so “be funny” or “don’t be funny” is enormously unhelpful by itself. An index disambiguates.

Sorting the guidance

Each product kept standards on our internal guidance site, on top of a company-wide baseline for the brand, and more sat in documents, chats, spreadsheets and internal posts. I took in the content standards for every discipline, consolidated them by product area, and cut them two ways. The first cut was by kind: deterministic rules and their subcategories, judgment calls, how to think about users, what not to do. The second asked one question of every line. Does it have a yes or no answer? The two cuts don’t line up. “Don’t use exclamation marks” and “Don’t blame the person” both prohibit something, but a script can look for a character, and blame takes a judgment about what the words imply.

Example: sorting a page of notification guidance

  • The line, as people wrote itKindWhere it went
  • Notifications should feel useful, never pushy.Judgment callStays in words
  • Keep the title less than 100 characters.RuleA check: count the characters
  • People often see these on a lock screen, mid-task.About usersStays in words
  • Don’t use exclamation marks.What not to doA check: look for the character
  • Don’t blame the person for an error.What not to doStays in words
  • Don’t be vague about what happened.What not to doMeasured against the product’s fingerprint
  • Never say “simple” or “easy.”What not to doA check: look for the words
  • Be funny when it fits the moment.Judgment callStays in words
Two cuts. The first sorts each line by kind. The second asks whether the line has a yes or no answer. Four of these lines say what not to do, and only two of them have one.

Everything with a yes or no answer became a check. I used AI to write the Python scripts that enforce those rules, and they ran on the Engine. The lines that took judgment stayed in words and kept their weight. They were what let the Agent jam with you, reason against best practices and apply the guidance in context. That left the lines about voice and tone.

Voice fingerprints

Tone turned out to be more measurable than we had assumed. A line like “don’t be vague about what happened” has no yes or no answer, but the Engine can measure how concrete a draft is and compare that with how the product usually writes. So each product got a voice fingerprint. It describes the language the product already puts in front of people, measured from its shipped strings along a set of linguistic dimensions such as how direct a request is or how concrete the words are.

Of everything in the Index, the fingerprint was the winner. A prompt file could capture the big rules at the top of a brand book, and agents built that way drifted from their product’s targets when I tested them. The fingerprint came from the strings a product had actually shipped, and against the same targets the Agent with its checks and the fingerprint was much more accurate. That gave a team an agent whose guardrails actually stay in place.

Building a fingerprint

A fingerprint measures a corpus, meaning a product’s shipped strings taken together. I built each one the same way.

  1. Gather. Meta’s codebase was very searchable. Swarms of agents ran search and Python extraction scripts over it, in searches that lasted hours, and pulled each product’s strings. That included strings assembled in code from variables, which we couldn’t query directly.
  2. Take a big slice. Plenty of dated strings contradicted each other. I gathered them en masse and took a slice big enough that the averages would offset the differences.
  3. Sort by situation. I grouped the strings by the job they did, such as errors, notifications, button labels and onboarding, so that a button label wasn’t averaged in with a notification.
  4. Measure. I ran the Engine across each group, with the same functions for every product. That kept the measurement consistent even where it wasn’t perfect.
  5. Store. For each dimension, the fingerprint kept the average and the spread around it. The files sat on the server next to the Python tools.

I started with Horizon, then ran Instagram, WhatsApp, Facebook and Meta Quest. Each product got a baseline overall and one for each kind of situation inside it, so a draft error message was held to how that product’s error messages read, and a notification to its notifications. The Engine did the measuring, and the Index kept the result beside the product’s rules, which meant the Agent got the right reference for the product and the situation it was working on. The Engine article shows a draft being compared with one.

Two fingerprints from one product: illustrative profiles

Speech actsinforms → asks

Politenessdirect → hedged

Emotional toneanalytical → emotional

Registerconversational → informational

Word originsGermanic → Latinate

Concretenessabstract → concrete

Syntaxsimple → nested

Lexical densityfewer content words → more

Rhythmuniform → varied

Readabilitydense → easy to scan

Errors: the range across shipped stringsNotificationsThe average

The same product, two situations. Errors and notifications sit in different places on the same dimensions, which is why each situation got a fingerprint of its own. These profiles illustrate the method and are not measured values for any Meta product.

One file per product

Each product got its own JSON file, a structured record the Agent could retrieve for the product it was working on. I started with Instagram, WhatsApp, Facebook, Meta Quest and Horizon, then filled out files for other products, including Threads. In a product’s file, a rule written as a sentence sat beside its check. The check is a translation. Both express the same requirement: the sentence tells the Agent what the rule means, and the check lets the Engine give a yes or no answer. The Python functions themselves ran on the server.

Example entries in a product’s file

The rule in words

The same rule as a Python check

Keep the title less than 100 characters.

len(title) < 100Counts the characters in the title.

Don’t use exclamation marks in body copy.

"!" not in bodySearches the body for the character.

Never say “simple” or “easy.”

not banned(text)Looks for any word on the product’s banned list.

Notifications should feel useful, never pushy.

No check. It stays a sentence for the Agent to apply in context.

Be funny when it fits the moment.

No check. It stays a sentence for the Agent to apply in context.

A translation, line by line. Each check says the same thing as the sentence beside it, in a form the Engine can run. Guidance that takes judgment has no translation and stays in words.

When someone started a conversation, the system detected who they were and matched them to the standards for their product space. Inside a product, the records were organized by situation, because a product doesn’t sound the same everywhere. Something like an account ban reads completely differently from an everyday notification. Under every product file sat the company-wide baseline, which gave the system a functional floor: anything that went through Verso had to map, at the very least, against Meta’s broader brand guidance.

Record structure

Each record carried an identifier and the requirement or reference itself. It also named the product and surface it applied to, its source, its owner, and whether a check could enforce it.

Terminology
A stated convention that a check can flag, such as using “reply” for a response in Threads.
Requirements
A constraint on meaning or behavior, such as avoiding unsupported promises of engagement.
Voice fingerprints
A measured reference for language in a particular product and context.
Ownership and source
The information needed to understand the record’s authority and route a proposed correction.

Different kinds of authority

The records did not all carry the same authority, and the Index kept them apart. A terminology rule could be linted. A requirement that needed interpretation could block a review even though no pattern match settled it. A voice fingerprint could advise without ever becoming a pass or fail rule.

Example draft for Threads

Leave a comment to reach more people.

Terminology record
Threads calls a response to a post a reply. A check can find the word “comment.” That finding is a fact.
Requirement record
“Reach more people” promises a bigger audience, and Threads guidance rules out unsupported promises about engagement. No pattern can find that, so someone has to read the sentence. It can still block a review.
Voice fingerprint
The Engine can compare the draft with how Threads usually writes in this kind of message. A difference is advice to look closer. It doesn’t prove a rule was broken.

One possible edit

Reply to this post.

Three records, three kinds of authority. The same draft meets a rule a check can settle, a requirement that needs a reader, and a measured reference that can only advise.

A draft could use the right term and still make a promise it shouldn’t. Finding “comment” is a different operation from deciding whether a sentence promises a larger audience. Keeping the kinds apart gave a content designer something specific to inspect when they disagreed with a recommendation.

Changes and ownership

How guidance changes were approved A designer challenges guidance. Verso prepares a proposed change. The content owner decides whether to approve, discuss, or reject it. Only the approved path updates the product record. Designer challenges guidance Verso proposes a change Content owner decides Approved Update the record Discuss or reject
Figure 3. Conversation could initiate a guidance change. The content owner’s approval governed the update.

Guidance changes, so the files had to change with it. When someone told Verso a piece of guidance wasn’t true and explained why, it wrote the change as a diff, a record of the exact edit, and tagged the product’s lead content designer. Leads already knew how to review diffs, so they approved it or started a discussion, and nobody had to prepare one by hand. Leads could read their product’s files in a dashboard, but a file only changed through an approved diff. I had an agent move each approved change into the product’s JSON, a step I could have automated and didn’t.

I built two of the tools behind this from scratch. A reader let the Agent search the standards repository, and a writer let any content designer propose a change in plain language, so the documentation evolved through conversation. Updates came from outside the conversation too. Scheduled jobs watched user research and announcements for anything that might mean a fingerprint needed adjusting, and a listener pinged the agent when something new was posted. A researcher could also submit a finding, which created a diff and filed it in the part of the Index kept for user research.

Example: a proposed change to Threads terminology

A content designer questions the rule and says why

“The post we’re quoting says ‘comment.’ Should we change the author’s words when we quote it?”

Verso writes the diff

Use “reply” for a response to a Threads post.

Use “reply” for a response to a Threads post. Keep the original wording when quoting someone’s post.

Tagged: the Threads lead content designerApproveStart a discussion

From a conversation to a reviewed change. Nobody prepares the diff by hand. Only the lead’s approval puts the new wording into the product’s file.

Coverage and maintenance

How well a product worked in Verso depended on the state of its standards. A product with solid docs was a breeze to tune. Where guidance was thin or scattered, there was a limit to what the Agent could responsibly say, and the onus was on content teams to define ownership, fill gaps and get their docs in shape. Content designers in other product areas asked to get their standards into Verso, and how fast that went depended on how developed those standards were to begin with.

I proposed two ways to help: a consolidation sprint with the people who maintained a product’s standards, or an assistant that could take the material in. Verso had a skill that could ingest a team’s guidance and create an index from it. I also designed an assistant that would interview a product’s lead content designer and draft structured standards from the answers.

Outcome

Fingerprints
Agents built from a prompt file alone drifted from their product’s targets. Against the same targets, the Agent with its checks and the product’s fingerprint was much more accurate.
Prompts
Moving the yes or no rules into checks and measuring voice left far fewer things to keep in a prompt. The model got a rich toolkit to call in place of a long list of instructions.
Guidance
Leads approving diffs turned out to be a really powerful forcing function. It drove alignment and codified guidance that had been inconsistent, and it ironed out inconsistencies over time.
Shipped language
With a product’s guidance and its shipped language held in the same form, we could also see the difference between what a product said and what its guidance said it was supposed to say.

See also

Image