Skip to content

Write a notification copy style guide #1282

Description

@johnpooch

Goal

Add a rule file covering how notification copy is written, so new specs in service/notification/registry.py are consistent by default rather than by review.

Context

The 23 registered specs disagree on title, capitalisation, tense, grammatical person and actor naming. There is no written guidance, so each new spec re-decides. A player in five games receiving "Civil Disorder / France entered civil disorder" cannot tell which game it came from.

Approach

A new file under .claude/rules/backend/, referenced from index.md, stating the rules a spec author must follow:

  • Title is the game name. An event that needs naming puts it in the body's first clause, not the title.
  • Title case for titles, sentence case for bodies.
  • Calls to action are a field (email_link_text), never prose in the body.
  • Present perfect for events that just happened.
  • Second person only when the event is about the recipient; anonymised twins such as nmr_extension_applied stay third person.
  • Describe what happened, not what the player failed to do.
  • One actor-rendering helper with one anonymity check, used everywhere.
  • No placeholder strings in user-facing copy — omit the clause instead.
  • link = None is a documented exception with a stated reason, not a per-spec judgement call.

Per the guidance rule in CLAUDE.md, state the rules and point at service/notification/registry.py; do not inventory the specs.

Two items from the source discussion should not be carried in: the claim that only game_start and deadline_warning define an email subject is wrong — all five specs declaring Channel.EMAIL define one — and whether to drop the channel_message truncation depends on the email preview text, which shares the rendered body.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation, including AI guidance such as CLAUDE.md files

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions