Comment and mention
Keep questions, clarifications, and decisions attached to the evidence they concern.
A good comment saves the next reader from reconstructing a private conversation. It shows what was noticed, why it matters, who needs to answer, and what the team decided.
Choose the right place for the discussion
Comment on the smallest object that preserves enough context:
| Comment on | Use it for | How to start |
|---|---|---|
| Highlighted content | One passage in an output, tool result, or retrieval result | On the trace detail page, select the text and choose Comment |
| Span | One operation | Hover the span in the trace tree and select Comment |
| Span field | One attribute or value | Select Comment on field next to the field in the span's details |
| Trace | End-to-end behavior involving several operations | Select Comments in the trace header |
| Prompt | A prompt-specific question or decision | Open the prompt under experiments → prompts and select the comments icon (Open comments) in its header |
| Incident | Scope, priority, investigation, ownership, or resolution | Select Comment under the incident title, or select text in the report to comment on that section |
Use the thread attached to the evidence instead of starting a parallel conversation elsewhere. Evals don't have comment threads; record reviewer reasoning in the Eval answer instead.
Anyone with access to the project can comment, including a Project Viewer.
Write a comment that can be acted on
Include three things:
- Observation: what the evidence shows.
- Expected behavior or question: why it matters or what needs clarification.
- Next person or action: who can answer, or what should happen next.
This retrieval span returned policy v2, but the request date is after its retirement date.
Expected: return only policy versions valid on the request date.
@owner: is request_date available before this tool call?Avoid comments such as “looks wrong” or “please check.” They force the recipient to rediscover the concern.
Attach the comment to the smallest span or excerpt that demonstrates the point.
Use mentions deliberately
Mention the person who owns the missing knowledge or next decision. A policy question may belong to an operations owner, while a trace-capture question belongs to an engineer.
Type @ in the comment box and pick a teammate. You can mention only people who already have access to the project, up to 50 per comment. A comment that mentions anyone else is rejected, so ask an organization owner or admin to grant project access first.
The mentioned person always gets an in-app notification under Activity → Mentions in the sidebar. Whether a mention also reaches them by Slack direct message or email depends on their Comments & Mentions row in Settings → Account → Notifications, which each person sets per project:
| Channel | Default | Requires |
|---|---|---|
| In-app | Always on | Nothing |
| Slack | On | Your organization's Slack connection, and a Slack account whose email matches the person's Neatlogs email |
| Off | Nothing |
A mention DM doesn't need the separate Receive Slack direct messages switch; that switch governs the other Slack updates.
Other people are notified differently depending on what you commented on. A comment on a trace or span also sends an in-app notification to every other member of your organization. Comments on an incident or a prompt notify only the people you mention.
Do not mention a large group merely to create urgency. Set incident Priority for operational work.
Keep replies in one thread
Reply to the original comment so the question, evidence, and answer stay together. On trace comments, use Reply, and use Add reaction to acknowledge a point when no further explanation is needed. On an incident, the comment opens beside the report; type in Reply… to continue the thread.
If the discussion moves to Slack or a meeting, summarize the material conclusion back on the Neatlogs object. Do not leave the only decision in a channel that future investigators may not be able to access.
Turn discussion into tracked work
A comment thread records discussion. An incident records a problem the team intends to own.
Move the thread into incident work when it establishes:
- a confirmed mismatch between observed and expected behavior;
- meaningful customer or business impact;
- a need for investigation or implementation;
- an owner or team that should follow up.
Incidents are created by Neatlogs, not by hand. If an incident already covers the problem, comment on it with the evidence link and the decision. Otherwise, investigate the evidence and select Track as issue on the result, as described in Flag a problem. Do not copy the entire thread when a concise summary preserves the important facts.
Close a discussion without erasing history
Comment threads have no resolve control. Close a discussion with a final comment that makes the outcome clear:
Confirmed: request_date is available but is not passed to policy retrieval.
Tracked in Linear NL-184 from the linked incident. Investigation will compare affected and successful runs.Do not delete disagreement merely to make the thread look clean. Only the author can edit or delete a comment, and only the person who started a thread can delete the whole thread.
Continue the discussion when new evidence changes the decision. State what changed.
Comment safely
- Never paste API keys, OAuth tokens, passwords, or authorization headers.
- Include only the customer data required to explain the problem.
- Prefer stable object links over screenshots.
- Distinguish quoted evidence from your interpretation.
- Avoid copying large trace payloads into external tools.
- Remember where the text goes. A trace or span comment appears in the in-app notifications of the other members of your organization, and a mention can arrive as a Slack direct message or email.
Frequently asked questions
Can I edit or delete my comment?
Yes, your own. On a trace comment, use Edit or Delete on the comment. On an incident comment, open Comment actions and choose Edit or Delete. Nobody else can edit or delete your comment, including organization owners and admins.
Does mentioning someone grant access?
No. You can mention only people who already have access to the project.
Are comments searchable?
Yes, on the trace list. The Comments column shows each trace's comment count and participants, and the Comment filter matches traces by comment text.
Should routine verdicts have comments?
Not necessarily. An Eval answer has its own reasoning field. Add a comment on the trace only when the decision is ambiguous, policy-dependent, or useful for future calibration.