ormus-solutions/librecopy-claude-code/style-guide-patterns

# Bad rule: too abstract
Use active voice.
 
# Good rule: with domain-specific example
Use active voice.
 
Do: "The SDK throws `AuthenticationError` when the token expires."
Don't: "An `AuthenticationError` is thrown when the token has expired."
 
Why: Active voice identifies the actor (the SDK), which is what developers
need to know when debugging.
 
Automated: `.vale/styles/Custom/ActiveVoice.yml` (error level)

# .vale/styles/Custom/Terminology.yml
extends: substitution
message: "Use '%s' instead of '%s'"
level: warning
action:
  name: replace
swap:
  "(?i)login": "sign in"
  "(?i)log in": "sign in"
  "(?i)whitelist": "allowlist"
  "(?i)blacklist": "blocklist"
  "(?i)sanity check": "quick check"

## Voice (Never Changes)
 
Our voice is: **clear, direct, technically honest**.
 
-Clear: We eliminate ambiguity before it reaches the reader.
-Direct: We say what we mean without hedging or softening.
-Technically honest: We acknowledge limitations, tradeoffs, and failures.
 
## Tone (Varies by Context)
 
The same voice sounds different depending on context:
 
| Situation | Tone Adjustment | Example |
|-----------|----------------|---------|
| Tutorial | Encouraging | "You've connected to the database. Let's add your first query." |
| Error message | Empathetic + actionable | "Your API key has expired. Generate a new one in your dashboard." |
| API reference | Neutral, precise | "Returns 404 if the resource does not exist." |
| Breaking change | Direct, solution-focused | "This method is removed in v3. Use `client.connect()` instead." |
| Security advisory | Urgent, no softening | "Update immediately. Versions 2.0–2.3 are vulnerable." |

## Inclusive Language
 
These are not suggestions -- they are required replacements with automated enforcement.
 
| Avoid | Use | Automated |
|-------|-----|-----------|
| blacklist / whitelist | blocklist / allowlist | Yes (Vale substitution) |
| master / slave | primary / replica | Yes (Vale existence) |
| sanity check | quick check, confidence check | Yes (Vale substitution) |
| guys (plural) | everyone, folks, team | Yes (Vale existence) |
| dummy (value) | example, placeholder | Yes (Vale substitution) |
| he/she (generic) | they | Yes (Vale substitution) |
 
For words without automated enforcement, add to PR review checklist.

# .vale.ini addition for reading level
[*.md]
BasedOnStyles = Vale, Google, Custom
Vale.Readability = YES    # Flesch-Kincaid score

# .vale/styles/Custom/ReadingLevel.yml
extends: script
message: "Reading level (grade %s) exceeds target (%s) for audience: end-user"
level: warning
script: |
  local grade = flesch_kincaid(doc)
  local target = 8  -- Grade 8 for end-user docs
  return grade > target, grade, target

# Bad: principle without example
Use the active voice in all documentation.
 
# Good: principle + example pair
Use active voice.
Do: "The function returns the user object."
Don't: "The user object is returned by the function."
Why: Active voice reveals the subject, which matters in technical explanation.