board-comment-style

Board comment style

Write task comments the way a colleague writes them: short, specific, done.

A board comment is read by a teammate scrolling a card, not by a grader. Nobody reads the second screen. A long comment does not prove more work happened — it buries the one line that mattered.

Your run's final message is not a comment: it becomes the run summary and, for a developer, the commit message. The rules below are about add_task_comment and comment_on_pull_request, not that message.

First: is this a comment at all?

Nothing that went WELL needs a comment. A passed review, a green build, an approved criterion, a merged pull request, a successful deploy, "moving this to human_uat" — the board already shows every one of those, in the column, the criteria, the PR field, the pipeline panel and the task history. Writing them down again is the noise that makes the comments nobody can skip impossible to find.

Comment when something needs a person or the next agent to act:

• a rejection, and exactly why (expected vs actual, file:line, the failing step);
• a failure, a blocker, a refusal you could not work around;
• a question you cannot answer from the code, numbered;
• work you did NOT do, and why;
• a risk or a follow-up somebody has to pick up.

So: verdict is "pass" → move the card and say nothing. Verdict is "fail" → the comment IS the deliverable, and it has to be precise enough to act on without a second round trip.

Never paste the pull request link or number. It is a field on the task and the board renders it next to the card; repeating it in a comment on every hand- off is the same fact three times. The same goes for the merge commit — the task records it — and for the branch name.

Length

Three to six lines is normal. Fifteen is the ceiling, and hitting it should feel wrong. A hand-off, a verdict, a status note — each is a few sentences.

If the detail genuinely doesn't fit, it isn't a comment. Put it in a task document if your role can attach one (add_task_document); otherwise cut it to the actionable lines — the evidence stays. QA: your review_criterion note on the rejected criterion already carries the per-criterion evidence; a comment repeats it only when something needs a person's decision beyond the verdict itself.

Write this

Blocked on AC3: "export streams large projects" — `GET /v1/export`
buffers the whole CSV in memory (exporter.go:88) and the 30s proxy
timeout cuts it at ~40k rows. Streaming needs the chunked writer in
internal/http — in scope for this task, or a follow-up?

Not this

## Summary
I have completed a comprehensive investigation of the issue described in
this task. Below you will find a detailed breakdown of my analysis...

## Background
This task was assigned to me in the in_progress column...

## What I Did
1. First, I began by reading the relevant files...
2. Then I examined the handler...
[continues for two screens]

The second one says less. Everything before "Blocked on AC3" is throat-clearing, and the numbered narration of which files you opened is a transcript, not a finding.

Rules

• No preamble. Never open with what the task was, what column it was in, or what you were asked to do. Everyone reading already knows — start with the finding.
• No narration of your own process. "I read X, then I searched Y, then I realised Z" is your history, not the result. Give Z.
• No headed report structure for a routine update. ## Summary / ## Background / ## Next Steps on a three-sentence message is packaging heavier than the contents.
• Name things exactly. File, symbol, command, error text, expected vs actual. One precise line beats a paragraph of description.
• Don't restate what the board already shows. The task title, the column, the assignee, the acceptance criteria, the pull request and the pipeline result are all on the card.
• Don't pad. No "I hope this helps", no "please let me know if you need anything else", no summary of the summary.
• Evidence stays, prose goes. Commands, outputs, the url and viewport of a screenshot, and reproduction steps are the valuable part — keep every one of them, and cut the sentences around them.

Where this does not apply

Structured deliverables have their own required shape and are not comments: QA's numbered expected-vs-actual failure list, a rejection note naming what failed, an analysis document, an implementation plan. Follow those formats. The rule here is about the prose you wrap around them — there should be almost none.