Skip to content

Add a notification copy style guide - #1303

Merged
johnpooch merged 1 commit into
mainfrom
claude/diplicity-notifications-arch-j1qwzq
Aug 31, 2026
Merged

Add a notification copy style guide#1303
johnpooch merged 1 commit into
mainfrom
claude/diplicity-notifications-arch-j1qwzq

Conversation

@johnpooch

Copy link
Copy Markdown
Owner

What this PR does

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

Adds .claude/rules/backend/notification-copy.md, scoped by frontmatter to service/notification/registry.py so it loads when a spec is edited, and referenced from .claude/rules/backend/index.md. It states the rules a spec author follows:

  • The title is the game name; an event that needs naming goes in the body's first clause.
  • 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 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 recorded exception with a stated reason, not a per-spec judgement call.

Per the guidance rule in CLAUDE.md, it states rules and points at the registry rather than inventorying the specs. References are by file and symbol rather than file:line, so they do not go stale as the registry moves.

Two facts are asserted from the code rather than assumed. get_email_body() defaults to get_body() and notification_email interpolates that same string into both the hidden preview div and the visible paragraph, which is why the guide requires the body to stand alone. Both tap handlers return early without a link — the notificationclick handler in packages/web/public/firebase-messaging-sw.js and the message listener in packages/web/src/messaging-native.ts — which is why a linkless push is a dead notification.

The guide does not rule on the channel_message truncation, since that interacts with the shared email preview text. It does state the email-subject convention, which all five specs declaring Channel.EMAIL already follow.

Rewriting the existing specs to match is #1283, and the linkless-push fix is #1284; neither is in this PR.

Closes #1282

Checklist

  • This PR does one thing — no unrelated fixes, refactors, or drive-by cleanups bundled in
  • For PRs of any significant complexity: I ran /review-pr against this PR in Claude Code and addressed (or responded to) its findings
  • Tests cover the change
  • Screenshots embedded in the PR description for any visual changes (see CLAUDE.md)

Documentation only — two markdown files under .claude/rules/, no code changed, so there is nothing to test and no visual change to screenshot. /review-pr has not been run against this branch.


Generated by Claude Code

The 23 specs in service/notification/registry.py disagree on title,
capitalisation, tense, grammatical person and actor naming, with 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.

Adds .claude/rules/backend/notification-copy.md, scoped to registry.py
and referenced from the backend rules index. It states the rules a spec
author follows — game name as the title, Title Case titles and sentence
case bodies, calls to action as fields, present perfect, second person
only for the recipient, one actor helper with one anonymity check, no
placeholder strings, and link omission as a recorded exception — and
points at the registry rather than inventorying the specs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FTSUJGBPgDacmsi1kyi1ze
@johnpooch
johnpooch merged commit 6c76840 into main Aug 31, 2026
24 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Write a notification copy style guide

2 participants