{"slug":"comments-and-mentions","meta":{"title":"Comments and Mentions","slug":"comments-and-mentions","kind":"pattern","summary":"A discussion attached to the record it is about, where naming someone notifies them — so context and conversation stay in the same place.","problem":"The decision about a record was made in a chat thread or an email that nobody can find six months later. The record shows the outcome and none of the reasoning, so the next person re-litigates it or repeats the mistake.","family":["coordinate"],"data_shape":["record"],"principles":["minimize-distance","orientation"],"interaction":["editing","feedback"],"density":"medium","complexity":"medium","status":"stable","visibility":"public","use_when":["Decisions about a record need discussion, and the reasoning matters later.","More than one person touches the record.","The conversation currently happens in chat or email and gets lost."],"avoid_when":["One person works alone. A notes field is simpler and enough.","The discussion is really about the process, not this record — that belongs somewhere shared.","The record is high-volume and low-stakes; a comment box on every row is noise nobody reads."],"alternatives":[{"slug":"activity-timeline","when":"You need the record of what changed, not a discussion about it."},{"slug":"assign-owner","when":"The real need is to make someone responsible, not to talk about it."}],"ask_leo":"Add comments to this record.\n\n- Put the comment thread on the record itself, below the detail, so the\n  context is on screen while people write.\n- Typing @ offers people to mention, and mentioning someone notifies them with\n  a link straight to this comment. That is the entire coordination mechanism —\n  without it, comments are a diary nobody reads.\n- Show who wrote each comment and when, and keep them in chronological order.\n- Allow editing your own comment for a short window, and mark it as edited.\n  Never allow silent editing, and never allow editing someone else's.\n- Deleting a comment leaves a visible tombstone that says a comment was\n  removed and by whom. A thread that can be silently rewritten cannot be\n  relied on in a dispute.\n- Interleave comments with the record's activity events in one chronological\n  thread if you have both, so cause and discussion sit together.\n- Let people who are not mentioned follow the record, and always notify the\n  owner.\n- Never notify someone for their own action.\n","related":[{"title":"Activity Timeline","url":"/patterns/activity-timeline","summary":"The system half of the same thread — what changed, alongside what was said."},{"title":"Assign an Owner","url":"/patterns/assign-owner","summary":"Who gets notified by default, and who is accountable for acting on a comment."}]},"body":"## Anatomy\n\n```\n  ┌─ Comments ────────────────────────────────────────────┐\n  │ Dana · 3 days ago                                     │\n  │ @priya the labour hours on level 3 look high — can    │\n  │ you check against the timesheets before we send?      │\n  │                                        ↑ notifies Priya\n  │ Priya · 2 days ago                            (edited)│\n  │ Checked. 48 hours is right, two crews for three days. │\n  │                                                       │\n  │ ⌁ Dana changed the amount from $8,400 to $8,900       │  ← activity,\n  │   2 hours ago                                          │    interleaved\n  └───────────────────────────────────────────────────────┘\n```\n\n- **On the record**, so the thing being discussed is visible while discussing it.\n- **Mention notifies.** This is the whole pattern. Comments without mentions are\n  a diary.\n- **Edits are marked, deletions leave a tombstone.** A thread that can be\n  silently rewritten is worthless in exactly the situation you kept it for.\n- **Interleaved with activity**, so \"why did the amount change\" and \"the amount\n  changed\" are adjacent.\n\n## Why it works\n\nIt puts the reasoning next to the record. The alternative is not \"no\ndiscussion\" — the discussion always happens. The alternative is that it happens\nin a channel with no connection to the record, and is therefore unfindable at\nexactly the moment someone needs it.\n\nMentions are what make it a coordination tool rather than an archive. A comment\nthat nobody is told about is a message in a bottle; @-naming someone turns the\nrecord into the place work gets asked for, which is what pulls conversation out\nof chat.\n\n## The retention argument\n\nComments accumulate the *why* behind decisions, and that turns out to be the\nmost valuable and least reproducible content in an internal system. Anyone can\nreconstruct what a record says; almost nobody can reconstruct why it says that.\n\nThis is also why the integrity rules matter more than they seem. Silent editing\nand silent deletion are cheap to allow and quietly destroy the one property that\nmakes the thread worth keeping.\n\n## Getting it wrong\n\n- **Comments with no mentions**, so nothing is ever seen in time.\n- **Silent edit or delete**, which makes the thread untrustworthy.\n- **Notifying people about their own actions**, which trains everyone to ignore\n  notifications.\n- **A separate \"internal notes\" and \"comments\" split with no clear rule**, so\n  people put things in the wrong one and something private reaches a customer.\n- **Comments on high-volume records nobody reads**, which is noise disguised as\n  collaboration.\n- **No link back from the notification**, so being mentioned means going to find\n  the record yourself.\n\n## Exemplars\n\n**GitHub issues** are the reference: the discussion, the activity and the record\nare one thread, and years later the reasoning is still attached to the code it\nproduced.\n\n**Linear** interleaves comments and property changes in one timeline, which is\nthe detail that makes \"why did this move to blocked\" answerable in one glance.\n\n**Google Docs comments** show the strongest version of proximity — the comment\nis anchored to the exact text it is about, which is as close as this pattern can\nget.\n\nThe extractable rule: **comments preserve the why, and mentions are what make\nanyone read them.** Build the mention, or you have built an archive.\n"}