# Comment, mention, and notify

**Flow key:** `comments-mentions-notifications`

## Outcome

An authorized collaborator posts one preserved comment, resolves intended mentions, and sends only eligible recipients useful deduplicated notifications.

## Actors

- Commenter
- Mentioned collaborators
- Content/notification service
- Resource owner

## Preconditions and entry points

- A shared synthetic resource exists with users of different roles and preferences.
- Mention syntax, edit/delete, moderation, and notification rules are known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Comment | `CARBON review looks good :)` | empty, multiline, emoji/kaomoji, RTL, markup/link canary, boundary length |
| Mentions | `@carbon-reviewer` | unknown, duplicate, removed, other tenant, ambiguous display name |
| Recipients | owner and mentioned reviewer | muted, unsubscribed, suspended, no access |
| Thread | new top-level comment | reply, edit, resolve/reopen, deleted parent |
| Concurrency | one post | double submit, simultaneous replies, permission revoked mid-compose |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Open the authorized resource and comment composer. | Thread scope, audience, formatting, and notification effect are clear. |
| 2 | Enter content and select a mention. | Mention resolves stable authorized identity without leaking suggestions. |
| 3 | Submit once. | One inert, correctly ordered comment persists with actor/time/version. |
| 4 | Observe thread and notifications. | Eligible recipients receive one message with permitted context and a safe link. |
| 5 | Edit, reply, resolve, or delete. | History and notification policy remain coherent. |
| 6 | Change access or recipient preferences. | Future delivery and existing content visibility update without leakage. |

## Alternate paths

- Comment without mention
- Threaded reply
- Multiple mentions
- Edit/delete
- Resolve/reopen
- Email and in-app notification

## Failure and recovery paths

- Duplicate submit/notification
- Mentioned user loses access
- Notification provider fails
- Comment commits but UI times out
- Markup/link preview is unsafe

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [in app message chat feed item](../../items/content/in-app-message-chat-feed-item.md)
- [notification and reminder](../../items/content/notification-and-reminder.md)
- [email and outbound message](../../items/content/email-and-outbound-message.md)
- [security](../../items/quality/security.md)

[Back to Productivity and collaboration flows](index.md)
