 

## Revision history

3 revisions · same URL since v1 

v1

**First draft.** Problem, goals, typeahead + mention-pill requirements.

Jul 2 · Sarah Chen, drafted with Claude Code

v2

**Added notification rules** (batching, dedupe, muted threads) after Priya's comment on §5.

Jul 9 · Claude Code, prompted by Priya Sharma

**Priya, Jul 8:** "What happens if I'm @-mentioned in a thread I muted? If the answer is 'you get an email anyway' this feature is dead on arrival."

v3

**Scoped out cross-org mentions** per security review SEC-2214; resolved OQ-2, added guest-notification rule.

Jul 16 · Claude Code, per Michael Torres's review — current

Review comments land on this page; the agent revises in place and logs the change here.

Highlight what changed in v3 5 changes vs v2 

## 1Problem

Teams review shared artifacts in comment threads, but there is no way to pull a specific teammate into a thread. Today the workaround is copying the artifact link into Slack with "can you look at the pricing table?" — which splits the discussion across two tools and loses the anchor to the exact element being discussed.

Evidence · internal dogfood, Jun 2026

Of 214 comment threads opened on shared artifacts in June, **41% waited more than 24 hours** for a reply from the person who could actually answer — and in 29 of those threads someone typed a teammate's name in plain text, expecting it to notify them. It didn't. 

People already believe mentions exist. We are shipping the behavior they assume is there: type @Priya in a comment, Priya gets notified, the thread keeps its anchor to the element under discussion.

## 2Goals & non-goals

### ✓Goals

* Pull the right person into a thread in one action, without leaving the artifact.
* Mentioned person is notified in-app within 60 seconds.
* Zero notification spam: batching, dedupe, and mute are respected from day one.
* Mentions survive comment edits and thread resolution.

### ✕Non-goals

* A full notification inbox or activity feed (separate track, H2).
* Presence, typing indicators, or read receipts.
* Mentioning Slack/Teams users who have no display.dev account.
* Cross-org mentions — moved to out of scope in v3, see §7.new in v3

## 3User stories

1. As a _reviewer_, I type @ in a comment and pick a teammate, so the right person sees my question without me leaving the doc.
2. As the _mentioned person_, I get one notification that deep-links to the exact thread and element, so I can answer in context in under a minute.
3. As an _artifact owner_, I can see which open threads are waiting on whom, so review doesn't stall silently.
4. As someone who _muted a thread_, I stay muted even when mentioned again in it — my attention is mine to allocate.

## 4Functional requirements

✓ agreed in review · ⧗ still open

FR-1 Typing **@** in a comment opens a typeahead of members of the artifact's org, filtered as you type. Keyboard-first: arrows + enter, escape dismisses. ✓ agreed 

FR-2 Typeahead ranks by relevance to _this artifact_: people already in the thread, then recent commenters, then org alphabetical. ✓ agreed 

FR-3 A confirmed mention renders as a pill — @David Park — stable through comment edits; deleting any character of the pill removes the whole mention. ✓ agreed 

FR-4 Each mentioned user is notified per the rules in §5\. Notification deep-links to the thread and scrolls the anchored element into view. ✓ agreed 

FR-5 Editing a comment re-notifies _only newly added_ mentions. Removing a mention never sends anything.added in v2 ✓ agreed 

FR-6 Mentioning someone who lacks access to the artifact prompts the mentioner to grant view access (or auto-grants for org-visible artifacts — pending OQ-3). ⧗ open 

FR-7 Mentions work in resolved threads; the thread stays resolved and the notification carries its resolved state.added in v2 ✓ agreed 

FR-8 Users may mention collaborators from partner orgs on artifacts shared across org boundaries.removed in v3 cut 

FR-9 Agents with an identity in the org (e.g. @claude-code) appear in the typeahead and can be mentioned; whether a mention triggers agent action is pending OQ-4. ⧗ open 

## 5Notification behavior

Whole section added in v2 after Priya's review comment. The principle: **one mention, at most one email.** In-app is immediate, email is a fallback for people who aren't looking.

__Channel matrix per event__
| Event                                                    | In-app    | Email                            |
| -------------------------------------------------------- | --------- | -------------------------------- |
| Mentioned in a new comment                               | immediate | batched ≤ 10 min                 |
| Newly mentioned via comment edit                         | immediate | batched ≤ 10 min                 |
| Mentioned in a thread you muted                          | none      | none                             |
| Reply lands in a thread where you were mentioned earlier | immediate | daily digest only                |
| Guest with link-only access is mentionednew in v3        | none      | none — pill renders, no delivery |

Dedupe rule: if the mention is seen in-app before the email batch window closes, the email is dropped. Muting a thread wins over everything — being mentioned again does not un-mute it (US-4).

## 6Out of scope

— Group mentions (@design, @everyone) — revisit after we have org groups. 

— Mention analytics ("who gets mentioned most") — no user has asked; skip. 

— **Cross-org mentions.** Security review SEC-2214 (Jul 15) flagged directory enumeration: the typeahead would let any collaborator list another org's member directory. Needs a scoped-visibility model first — deferred to the external-collaboration track.new in v3 

## 7Open questions

1. OQ-1 Should mentions work in resolved threads, or should mentioning reopen the thread? ✓ Resolved Jul 9 (v2): mentions allowed, thread stays resolved → FR-7.
2. OQ-2 Do cross-org mentions ship at launch? ✓ Resolved Jul 16 (v3): no — scoped out per SEC-2214, see §6.new in v3
3. OQ-3 Mentioning someone without access: prompt the mentioner to grant access (Priya's position — explicit is safer) or auto-grant on org-visible artifacts (David — fewer dead-end mentions)? decision: Sarah · due Jul 23, blocks FR-6
4. OQ-4 When an agent is mentioned (@claude-code fix the y-axis), does the mention itself trigger the agent, or only notify its owner? Leaning: notify-only at GA, triggering is its own PRD. decision: Sarah + David · due Jul 30, blocks FR-9

## 8Milestones

1. Jul 2✓PRD v1 drafted, review opened
2. Jul 15✓Security review complete (SEC-2214)
3. Jul 23→Spec sign-off — pending OQ-3, OQ-4
4. Aug 6·Typeahead + mention pill behind flag
5. Aug 20·Notification pipeline (batching, dedupe, digest)
6. Aug 27·Org-internal beta — dogfood on our own review threads
7. Sep 15·GA — target release