The CVSO test
Every page is judged against one question: would a respected County Veterans Service Officer be comfortable handing this to a walk-in client? CVSOs and VSO accredited representatives are the primary distribution channel for VBN. They are also the audience whose judgment we trust most. If a CVSO would wince at a sentence, the sentence is wrong, even if the underlying fact is right.
A second test, applied to anything that touches benefit amounts or eligibility: would AP, ProPublica, Stars and Stripes, or Military Times feel safe quoting this verbatim? If a sentence would only survive in a niche blog, it does not belong here.
Three modes of writing
Not every section sounds the same. We use three modes:
- Mode 1: CVSO across the desk (about 25% of content). Plain, direct, no fluff. Used for tool intros, plan summaries, and the closing section of every page.
- Mode 2: Capable explainer (about 65%). The bulk of the content. Step-by-step, with tables and numbered lists where they help. Most program guides, condition pages, and tool descriptions sit here.
- Mode 3: Reference table (about 10%). Tables, lists, contact info, deadlines, payment rates. No personality, no warmth, no second person. Used for compensation rate tables, statutes, and processing-time data.
Crisis content and mental-health pages lean Mode 3. Crisis numbers (Veterans Crisis Line: 988, then press 1) appear at the top of the page, not the bottom, and are never inside a collapsed accordion.
Conditional language
VA is the adjudicator; VBN is not. Every benefit outcome is conditional on service connection, evidence, eligibility class, and rating criteria. Our pages use "may," "can," "up to," and "if eligible" for any sentence about what a veteran will receive. We do not use bare "pays" or "covers" as outcome verbs.
Statutory facts can be stated directly ("compensation rates increase annually under 38 U.S.C. § 5312"). Math examples are fine when they read clearly as hypotheticals ("a veteran with a 50% and a 30% rating would combine to 65%, rounded to 70%, under 38 CFR § 4.25"). Promise-shaped sentences about a specific reader are not.
What we do not write
Six categories of language are banned outright. The literal banlist is in the test file at __tests__/voice-banned-phrases.test.ts and is enforced on every commit. Here is what each category covers and why it is banned.
- Marketing-bait.Phrasings that turn a benefit into an advertised product, or that promise "optimization" of an outcome only VA can determine. The for-profit unaccredited "claims consultant" industry uses this register heavily; VBN cannot afford to share linguistic territory with it.
- Adversarial-agency. Phrasings that frame VA staff as obstacles or the VA process as a bureaucratic enemy. CVSOs work alongside VA staff every day. They will not share content that attacks their professional partners. Reporters read this register as conspiratorial.
- Gaming or manipulation.Any framing that suggests preparation is a trick, hack, or insider secret. Preparation is respect for the rater's time. VBN explains the rules, not workarounds.
- Entitlement.Phrasings that imply benefits are owed, hidden, or uncollected. Benefits are awarded when the record supports them. "Eligible" and "may receive" are correct frames; possessive language is not.
- Dismissive of the process. Phrasings that treat the application or appeal process as nuisance. The process exists because VA awards benefits funded by the public.
- Us-vs-them. Anything that places VBN and the veteran on one side and VA on the other. VA is the awarder; CVSOs are the partner. VBN is the explanation layer.
Two additional categories cover patterns that are specific to veteran-benefits content:
- Imperative cliches.Sales-imperative phrasings borrowed from the for-profit industry. Where a call to action is needed, we name a concrete next step ("find a CVSO in your county") instead of using urgency cliches.
- Punctuation overreach. Exclamation marks do not appear in benefits content. Em dashes do not appear in user-facing prose. Both signal sales energy or AI-fluent prose and undermine the CVSO posture.
Per-domain rules
- Healthcare:we say "you may be eligible for VA health care based on your service." Eligibility is established by VA enrollment under 38 CFR § 17.36, not by anyone else.
- Education: we state the actual delimiting-date rule, which varies by chapter and discharge date. We do not use slogans about timing.
- Housing:we say "VA loans may not require a down payment, depending on entitlement and lender requirements." Eligibility is established by the Certificate of Eligibility from VA.
- Employment:we say "veteran preference is a factor in federal hiring under 5 U.S.C. § 2108." It is not a guarantee of being hired.
- Mental health: we do not implement clinical screeners (PHQ-9, PCL-5, etc.). Mental health pages route to clinicians and to the Veterans Crisis Line. We do not score, we do not diagnose, we do not assess.
Document patterns
Every tool, condition, or program page follows the same shape:
- Short Version. Three to five sentences at the top stating what the page is for, the key rule, and where to go next. A veteran who reads only the Short Version should know whether the rest is relevant to them.
- The guide. Mode 2 voice, structured with clear headings. Tables for rates and timelines, prose for explanations, citations for every legal claim.
- What is easy to miss. A short list of common mistakes, framed as oversights rather than as things VA hides.
- What to do. Sorted by situation. Each entry is one bolded condition followed by one to three sentences with a specific next step.
- Closing line. One or two sentences. Either restate the most important rule or restate the next concrete action.
Punctuation and formatting
- No em dashes in user-facing prose. We use colons, commas, parentheses, periods.
- No exclamation marks in benefit content, condition pages, tool intros, or call-to-action buttons.
- No ALL CAPS for emphasis. Semantic emphasis (bold, italic) is preferred.
- No dollar figures in page H1s. Money belongs in the body, after the rule that produces it.
How this is enforced
Two automated tests run on every commit and every CI build:
__tests__/voice-banned-phrases.test.tsscans every TypeScript file undersrc/app/,src/components/, andsrc/data/for the eight categories above. Failures group by category and print a recommended replacement for each violation.- A second scan checks that prose strings in
src/data/use conditional language with outcome verbs ("pays," "covers"), and that prose strings do not contain emphasis exclamation marks.
Two helper scripts support the test: scripts/vn-voice-debt.mjs generates a directory-by-directory voice-debt report, and scripts/vn-voice-changed-files.mjs runs the same scan on git-diff'd files only, suitable for pre-commit use.
Why these rules exist
VBN is not VA-accredited under 38 U.S.C. § 590438 U.S.C. § 5904†. We do not file claims, do not represent veterans before VA, and do not provide legal advice. The voice rules above keep the site clearly inside that posture: explanatory, conditional, deferential to the rater, and respectful of the CVSOs and VSO accredited representatives who are the actual representation channel for veterans.
The longer-form rationale, with before-and-after rewrite examples and a per-sentence checklist, lives in the contributor-facing document at vn-voice-prompt.md in the project repository.