Brainforge Knowledge

STYLE-GUIDE

5 min read

Brainforge Writing Style Guide

This document defines the global writing standards for all Brainforge documents. Every document, whether internal or client-facing, should follow these rules.

AI tools (Cursor, Claude, GPT) should be instructed to follow this guide when generating content.

Punctuation and Formatting

Em Dashes

Do not use em dashes. Use commas, semicolons, colons, or restructure sentences instead.

Avoid:

  • “The project was successful—exceeding all expectations—and delivered on time.”

Preferred:

  • “The project was successful, exceeding all expectations, and delivered on time.”
  • “The project was successful. It exceeded all expectations and delivered on time.”

Emojis

Do not use emojis in client-facing documents.

Internal documents (Slack messages, casual notes) may use emojis sparingly, but formal documentation should remain emoji-free.

Hyphens and Dashes

  • Use standard hyphens (-) for compound words: “client-facing,” “real-time.”
  • Use hyphens for ranges: “Week 1-4,” “10-15 hours.”
  • Use en dashes sparingly and only when necessary for clarity.

Quotation Marks

Use straight quotes (” ”), not curly quotes (” ”).

Most code editors default to straight quotes. Avoid copying text from Word or Google Docs that may introduce curly quotes.

Lists

  • Use bullet points for unordered items.
  • Use numbered lists for sequential steps or ranked items.
  • Keep list items parallel in structure.
  • End list items with periods if they are complete sentences.
  • Do not end list items with periods if they are sentence fragments.

Tone and Voice

Active Voice

Prefer active voice over passive voice.

Avoid:

  • “The report was completed by the team.”

Preferred:

  • “The team completed the report.”

Concise Sentences

Keep sentences under 25 words when possible. Long sentences are harder to read and understand.

Avoid:

  • “In order to ensure that we are able to successfully complete the project on time, it will be necessary for all team members to provide their updates on a daily basis.”

Preferred:

  • “All team members should provide daily updates to keep the project on track.”

Filler Phrases

Avoid filler phrases that add no meaning:

AvoidUse Instead
In order toTo
It should be noted that(delete)
At this point in timeNow
Due to the fact thatBecause
In the event thatIf
For the purpose ofTo, For
With regard toAbout, Regarding
Prior toBefore

Hedging Language

Avoid vague hedging language unless justified:

Avoid:

  • “We might potentially be able to deliver this feature.”
  • “We will try to explore possible options.”

Preferred:

  • “We will deliver this feature by Friday.”
  • “We will evaluate three options and recommend one by Monday.”

If uncertainty is genuine, state the reason:

  • “Timeline depends on API access, which the client is providing by Thursday.”

Document Conventions

Dates

Use ISO format: YYYY-MM-DD.

Examples:

  • 2025-12-15
  • December 15, 2025 (acceptable in prose, but use ISO in tables and metadata)

Times

Use 12-hour format with timezone.

Examples:

  • 2:00 PM PT
  • 10:30 AM ET

Headings

Use sentence case for headings, not Title Case.

Avoid:

  • “How To Create A New Project”

Preferred:

  • “How to create a new project”

Exception: Proper nouns and acronyms remain capitalized.

Oxford Comma

Use the Oxford comma (serial comma) before “and” or “or” in lists of three or more items.

Avoid:

  • “We support Shopify, Amazon and Walmart.”

Preferred:

  • “We support Shopify, Amazon, and Walmart.”

Numbers

  • Spell out numbers one through nine.
  • Use numerals for 10 and above.
  • Use numerals for measurements, percentages, and technical specifications.

Examples:

  • “We completed three phases.”
  • “The project lasted 12 weeks.”
  • “Performance improved by 25%.”

Technical Writing

Acronyms and Abbreviations

Define acronyms on first use, then use the acronym throughout.

Example:

  • “Customer Acquisition Cost (CAC) measures marketing efficiency. CAC improved by 15% in Q3.”

Code and Technical Terms

  • Use backticks for code, file names, and technical terms: config.yaml, dbt run.
  • Use code blocks for multi-line code or commands.

File and Folder Names

  • Use lowercase with hyphens for file names: meeting-agenda-template.md.
  • Avoid spaces in file names.
  • Use descriptive names that indicate content.

Document Structure

Required Sections

Most documents should include:

  1. Title and metadata (date, author, version)
  2. Summary or overview (what is this document about)
  3. Main content (organized with clear headings)
  4. Next steps or action items (if applicable)

Heading Hierarchy

Use heading levels consistently:

  • # for document title (one per document)
  • ## for major sections
  • ### for subsections
  • #### for detailed subsections (use sparingly)

Do not skip heading levels (for example, do not go from ## to ####).

White Space

Use blank lines between sections and paragraphs. Dense blocks of text are harder to read.

Client-Facing Documents

Professional Tone

Client documents should be:

  • Clear and direct
  • Confident but not arrogant
  • Specific about deliverables and timelines
  • Free from internal jargon

Commitments

Be specific about what will be delivered:

Avoid:

  • “We will optimize your data pipeline.”

Preferred:

  • “We will reduce pipeline latency from 4 hours to under 30 minutes.”

Risks and Assumptions

State risks and assumptions explicitly. Do not hide them in footnotes or appendices.

AI-Assisted Writing

When using AI tools to generate content:

  1. Always instruct the AI to follow this style guide.
  2. Review all AI-generated content for accuracy.
  3. Check for invented information or hallucinations.
  4. Verify that the tone matches Brainforge standards.
  5. Remove any emojis or em dashes the AI may have introduced.
  6. Use the humanizer skill (/humanizer in Cursor) to remove AI writing patterns. The humanizer reinforces this guide by detecting 24 common AI patterns including significance inflation, promotional language, and sycophantic tone. See .cursor/skills/humanizer/ in the playbook.

Prompt Example

When starting a document with AI assistance, include:

“Follow Brainforge’s style guide: no em dashes, no emojis, active voice, concise sentences, ISO date format, Oxford comma. Use sentence case for headings.”

Quick Reference Checklist

Before finalizing any document, verify:

  • No em dashes used
  • No emojis in client-facing content
  • Active voice preferred
  • Sentences under 25 words
  • No filler phrases
  • Dates in ISO format (YYYY-MM-DD)
  • Oxford comma used
  • Headings in sentence case
  • Acronyms defined on first use
  • All commitments are specific and measurable
  • Risks and assumptions stated explicitly

Questions or Updates

If you have questions about this style guide or want to propose updates, discuss with the team. This document should evolve as Brainforge’s writing standards mature.

Graph View