Four conventions fix most of it, and none of them need a tool.

1. one channel, created at declaration#

Not the team channel. Not a thread in the team channel. A dedicated channel per incident, named predictably: inc-2026-08-29-checkout-errors.

Why it matters: the incident becomes searchable as a unit, the timeline is the channel, and people who join late can read from the top instead of asking what happened. It also means the incident does not drown the normal channel, and the normal channel does not drown the incident.

Archive it afterwards rather than deleting it. It is the primary source for the postmortem.

2. named roles, stated out loud#

Three, at minimum, posted in the channel as the first message:

IC: @priya       — decides, delegates, does not debug
Comms: @marcus   — status page, stakeholders, customer support
Ops: @sam        — hands on keyboard

The incident commander not debugging is the rule people resist and the one that matters most. The moment the IC opens a terminal, nobody is tracking the whole picture, and the incident gets longer.

For a small incident one person can hold two roles. They should still say which ones, because the alternative is everyone assuming someone else is doing comms.

3. a pinned status message, edited in place#

One message, pinned, rewritten as things change:

STATUS 14:22 — Checkout failing for ~12% of users since 13:58.
Cause: unknown. Suspect the payments deploy at 13:55.
Now: rolling back that deploy (@sam), ETA 5 min.
Impact: card payments only, wallet payments unaffected.
Next update: 14:35

Five lines: what is broken, since when, what we think, what we are doing, when the next update comes.

This single convention removes most of the noise, because it answers the question that generates the noise — "what's the current state?" — without anyone having to ask. Everyone joining reads the pin instead of scrolling.

Always include the next-update time. It is what stops people asking for updates.

4. mark the speculation#

The most common way incidents go wrong is that a guess gets repeated until it becomes the working theory, and then twenty minutes go into the wrong system.

A one-word convention fixes it:

FACT: error rate went from 0.1% to 12% at 13:58:20
FACT: the payments deploy completed at 13:55:41
GUESS: the deploy caused it
ACTION: rolling back to confirm

Facts have evidence attached. Guesses are labelled as guesses. Actions say who is doing them.

It looks pedantic for about four minutes and then it saves the incident, because somebody reading the channel can tell the difference between what is known and what somebody said.

what to keep out#

Speculation from people who are not investigating. Well-meant and it fills the channel that responders are trying to read. If you are not on a role, watch.

"Is it fixed yet?" The pinned status has the next update time.

Root-cause analysis during the incident. Restore first. The good question at 14:22 is "what makes this stop", not "why did this happen". Why is a question for Thursday.

Blame, in any form, including jokes. It is in a permanent record that a person will read afterwards.

the handoff#

Long incidents cross shift boundaries and the handoff is where context dies. It needs to be explicit and in the channel:

HANDOFF 22:00 — @priya → @dan (IC)
Ruled out: deploy (rolled back, no change), CDN (unaffected regions also failing)
Current theory: connection pool exhaustion on the orders DB
In flight: @sam is capturing pg_stat_activity every 30s → thread above
Not yet tried: failover to replica
Customers: status page updated 21:40, support has the template

Ruled out, current theory, in flight, not tried, customer state. Five lines, and the incoming IC starts with the accumulated knowledge instead of rediscovering it.

why bother#

The channel is not a side effect of the incident. During the incident it is the coordination mechanism, and afterwards it is the only complete record of what was known and when.

A channel that follows these four conventions produces a postmortem that half writes itself, and — more importantly — an incident that ends sooner, because the people fixing it spent their attention on the system rather than on the chat.

A real changelog is a small amount of work with an outsized return.

what it is for#

Deciding whether to upgrade. The single most common reason someone reads a changelog. They are on version 3.2, version 3.7 exists, and they want to know whether it is worth the risk.

Knowing what will break. The most important information you can provide, and the thing auto-generated release notes are worst at.

Debugging. "This started failing after we upgraded" — a good changelog turns that into "here is the change that caused it" in thirty seconds.

Finding out what exists. People discover features by reading changelogs. This is a real and underrated distribution channel for your own work.

why generated release notes are not enough#

A list of merged pull request titles has three problems.

It is written for the wrong audience. "Refactor connection handling" means something to the maintainer and nothing to the user. What changed for them?

It has no hierarchy. A breaking change and a typo fix appear as sibling bullets of equal weight.

It has no migration guidance. "Remove deprecated parse() method" tells you something broke. It does not tell you what to do about it.

the format#

Keep a Changelog is the established convention and it is good. The structure:

## [4.2.0] - 2026-07-22

### Breaking
- `Client.connect()` no longer accepts a positional timeout.
  Pass `timeout=` as a keyword.
      # before
      client.connect(host, 30)
      # after
      client.connect(host, timeout=30)

### Added
- `Client.ping()` for health checks without a full round trip (#412)
- Support for Unix domain sockets via `unix://` URLs (#398)

### Fixed
- Connections leaked when the handshake timed out (#405).
  If you saw file descriptor exhaustion under load, this was it.

### Deprecated
- `Client.legacy_mode` — will be removed in 5.0. Use `compatibility=`.

### Security
- Fixed a case where credentials could appear in debug logs (GHSA-xxxx-xxxx).
  Affects 4.0.0–4.1.3. Rotate credentials if debug logging was enabled.

the rules that make it useful#

Breaking changes first, always. That is what people are scanning for. Do not bury them under twelve feature bullets.

Include the migration. A breaking change without "do this instead" makes the reader open your source code. Two lines of before-and-after saves everyone time.

Describe the user-visible effect, not the implementation. Not "refactored the retry logic." Rather: "retries now use exponential backoff with jitter; if you relied on the previous fixed 1-second interval, set retry_delay=1.0."

Say who is affected. "If you use X, this changes for you. Otherwise nothing changes." Most readers can then stop reading, which is a service.

Link to the issue or pull request for anyone who wants detail. The changelog is a summary, not a substitute.

Date every release, in ISO format. Version numbers alone do not tell you whether you are two months or three years behind.

Write it as you go, not at release time. An Unreleased section at the top that each pull request adds to. Reconstructing a changelog from git history at release time is miserable and it is why changelogs get skipped.

the security section specifically#

If you fix a security issue, say so, with:

• Which versions are affected.
• What the impact is.
• Whether any action beyond upgrading is required.

That last one is the part that gets omitted and it is critical. "Upgrade to 4.2.0" is insufficient if credentials may have been exposed — the user also needs to rotate them, and they will not know unless you say so.

for internal projects#

The same file works for internal services, and the audience is your future self and the person who takes over the service.

The most valuable internal changelog entries are the ones that record a decision:

## 2026-07-14
- Switched from polling to webhooks for order status. Polling was
  costing ~40 requests/second against the vendor's rate limit and
  we were getting throttled during peaks.

Six months later, when someone asks why there is webhook infrastructure, the answer is in one place.

the return on investment#

Ten minutes per release. In exchange:

• Fewer support questions.
• Faster upgrades by your users, which means fewer people on old versions you have to support.
• Fewer surprised users after a breaking change.
• A record you can search when debugging.

There are not many ten-minute tasks with that profile.

Here is a taxonomy of comments worth writing, roughly in descending order of value.

the ones worth writing#

"This will break when X." The highest-value comment there is. A specific failure scenario the author did not consider.

"If two requests hit this concurrently, both will pass the existence check and both will insert. We saw this exact bug in the invoicing path last year."

Concrete, falsifiable, and it comes with evidence.

"This contradicts how we do it elsewhere." Consistency has real value and the author frequently does not know the precedent exists.

"orders/ uses the repository pattern for this. Worth matching, or is there a reason to differ here?"

Note the question at the end. Sometimes there is a reason and you have just learned something.

"I don't understand this." Underrated. If a reviewer with context cannot follow it, a stranger in two years will not either.

This is not an admission of inadequacy. It is a measurement of the code's clarity, and it is a measurement only a reader can take.

"What happens if this fails?" The most consistently productive question in code review. Error paths are the least-considered part of most changes and the most-exercised part in production.

"Is this the right layer?" Business logic in a controller, presentation logic in a model, a database call in a template. Structural, cheap to fix now, expensive later.

"This is good and here is why." Genuinely valuable and almost never written. Naming what worked teaches the pattern and it makes the critical comments land better, because they arrive from someone who is paying attention rather than someone who is looking for problems.

the ones not worth writing#

Anything a formatter or linter handles. If you are commenting on spacing, quotes, or import order, fix your tooling instead. A human enforcing mechanical rules is a broken process.

Style preferences without a reason. "I would have used a map here" is not a review comment, it is a preference. If there is a reason — clarity, performance, consistency with a convention — say the reason. If there is not, do not send it.

Speculative generality. "What if we later need to support multiple currencies?" Usually they will not, and building for it costs now. If you genuinely believe it, say what makes you believe it.

A redesign in a review comment. If the approach is fundamentally wrong, that is a conversation, not a comment thread. Comments are for improving an approach; a different approach needs a discussion, and doing it in review comments after the work is done is the most expensive possible time.

That failure is on the process, not the reviewer: the design should have been discussed before implementation.

how to phrase things#

Distinguish blocking from non-blocking. A convention that removes an enormous amount of ambiguity:

blocking: this deletes rows without the tenant filter
suggestion: this could use the existing helper in utils/dates
question: is the retry here intentional given the caller already retries?
nit: typo in the comment
praise: nice — this handles the empty case correctly, which the old one did not

The author knows exactly what to act on. The reviewer can leave a thought without implying it must be addressed. Both people save time.

Ask rather than assert when you are unsure. "Why does this need a lock?" is better than "this does not need a lock" when you are not certain, and it is better even when you are, because the answer might teach you something about the system.

Explain the why, not just the what. "Use a set here" is an instruction. "Use a set here — this is O(n²) on a list that can have thousands of entries" is teaching, and the author will apply it next time without being told.

Comment on the code, not the person. "This is confusing" rather than "you wrote this confusingly." Small difference, and it consistently changes how the comment is received.

the process problems that comments cannot fix#

The diff is too large. Past a few hundred lines, review quality collapses. The comment "this PR is too large, can you split it" is the most valuable one available and it is socially costly to write, which is why nobody does.

Make it a policy so it is not a personal judgment.

Review is too late. If a fundamental problem is found in review, the process failed earlier. That belongs in design.

Only one person reviews. Different reviewers see different things. For anything significant, two, with different backgrounds.

Comments arrive over three days. The author has moved on and has to reload the entire context. Batch your review into one pass, and do it within a day.

the goal#

The purpose of code review is not to find bugs — tests find bugs more reliably and more cheaply.

It is to spread understanding, maintain coherence, and catch the class of problem that automation cannot see: wrong abstraction, wrong layer, missing case, code that will confuse the next reader.

Comments that serve those are worth writing. Everything else is noise with a notification attached.

Most reports fail at this, and the cost is enormous — a round trip asking for information takes hours or days, during which the bug is not being fixed and the reporter is not being helped.

the six fields#

1. What you did. The exact steps. Not "I tried to log in" — the sequence, including things that seem irrelevant. The irrelevant thing is frequently the cause.

2. What you expected. This seems redundant and is not. A meaningful fraction of bug reports are misunderstandings, and stating the expectation surfaces that immediately. It also catches the case where the software is working as designed and the design is wrong, which is a different and often more important bug.

3. What actually happened. Specifically. The exact error text, copied, not paraphrased and not described. Screenshots for visual issues. The full stack trace, not the last line.

4. Environment. Version of the software, operating system, browser, region, account type, relevant feature flags. Half of all "cannot reproduce" outcomes are environment differences.

5. Frequency. Every time? Once? Intermittently? This changes the debugging approach completely — a deterministic bug is a logic error, an intermittent one is usually concurrency, caching, or state.

6. An identifier. Request ID, trace ID, session ID, timestamp with timezone, account ID. This is what lets an engineer find the actual event in the logs, and it converts "I have to reproduce this" into "I can look at exactly what happened."

That last one is the highest-leverage field and the one most often absent, because most products do not surface an identifier to the user.

If you build software: put a request ID on your error pages. It costs nothing and it is the difference between a bug report you can act on and one you cannot.

the title#

The title is read by dozens of people and determines whether the right person opens it.

Bad: "Login broken" Better: "Login fails with 500 for SSO users after password reset"

The pattern: what fails, for whom, under what condition.

what to leave out#

Your theory about the cause, unless you have evidence. A confident wrong theory sends the investigation in the wrong direction, and reports with a theory get debugged less carefully because the reader anchors on it.

If you do have a theory, put it at the bottom, labeled as speculation.

Emotional content. "This is completely broken and unacceptable" adds nothing and makes the reader defensive. The severity is communicated by the impact description, not by adjectives.

Multiple bugs in one report. One issue per report. Multi-bug reports get partially fixed and closed, and the remaining bugs are lost.

the minimal reproduction#

If you can produce one, it is worth ten times the rest of the report combined.

The technique: start with the failing case and remove things until it stops failing. The last thing you removed is involved.

This is work, and it is work that would otherwise be done by someone with less context than you. A minimal reproduction frequently reveals the cause to the reporter before they finish making it.

the template#

Put this in your issue template. Teams that do see a measurable improvement in report quality, because most people will fill in the fields you give them and will not invent them:

**What I did**
1.
2.
3.

**Expected**

**Actual**
(exact error text, full stack trace, screenshot)

**Environment**
- Version:
- OS / Browser:
- Account / Region:

**Frequency**
Always / Sometimes / Once

**Identifiers**
Request ID:
Timestamp (with timezone):

for the person receiving it#

The other half of this.

Reproduce before you theorize. The single most common debugging failure is building a mental model from the description and investigating that model instead of the actual behavior.

Ask for the missing field specifically. "Can you send the request ID from the error page?" gets an answer. "Can you provide more details?" does not.

Close the loop. Tell the reporter what it was. This costs a sentence and it is the reason people file good reports next time — a report that vanishes into a backlog teaches people not to bother.

the meta-point#

A bug report is a handoff of context between two people, one of whom has seen the failure and one of whom has to fix it.

Everything in a good report is in service of moving context across that gap. Everything that does not move context across the gap is noise.

A design doc that works has a different shape, and the shape follows from being honest about why you are writing it.

why you are actually writing it#

Three reasons, and they want different documents:

To think. Writing forces you to discover that your plan has a hole. This version is for you and can be messy.

To get input before it is expensive. The highest-value function. You want the person who knows the thing you do not know to tell you before you build.

To create a record. So that in two years, someone can find out why.

Most templates optimize for the third and produce documents that fail at the second. The record is only worth having if the decision was good, and the decision is good because of the input.

the format#

One page. Two if the problem genuinely needs it. Structured so a reader can stop after any section and have gotten something.

Problem. What is wrong right now, with evidence. Not "we should improve X" — what breaks, how often, who it affects. If you cannot state the problem concretely, the design is premature.

Goals and non-goals. The non-goals are the important half and almost always missing. "This does not address the reporting pipeline" prevents forty comments about the reporting pipeline.

Proposal. What you are going to build, in enough detail to disagree with. Interfaces, data shapes, the sequence of operations. A diagram if the shape is not obvious in prose.

Alternatives considered. Two or three, each with one honest sentence about why not. This is the section that gets the good comments, because it is where a reader sees the option you dismissed for a reason they know is wrong.

If your alternatives section contains obvious strawmen, experienced readers will notice and discount the whole document.

Risks and open questions. What might go wrong. What you are unsure about. This is where you ask for help explicitly, and it is where the people who know things will engage.

Rollout. How it ships, how it is verified, how it is rolled back. A design without a rollback plan is not finished.

That is it. Under a thousand words for most things.

the things that make people not read it#

Length. Past about two pages, readership drops sharply. If you need more, put the detail in an appendix and keep the main document short.

Burying the proposal. If the reader has to get through three pages of background before learning what you want to do, they will not.

No clear ask. Say what you want. "I need someone who knows the payment path to confirm the idempotency assumption in section 3" gets a response. "Please review" does not.

Passive voice throughout. "It was determined that" hides who decided and why. It also reads as evasive, because it usually is.

No deadline. "Comments by Thursday, I will start Friday" produces comments by Thursday. An open-ended review produces comments never.

the review that works#

Ask specific people specific questions. Not "posting this to the channel." Three named people, each with a sentence about why you want their input.

Give a real window. Three to five days. Long enough to fit into someone's week, short enough to stay on the top of the pile.

Timebox the meeting, if there is one. For a contentious design, a 30-minute discussion after people have read it resolves more than two weeks of comments. For an uncontentious one, do not have a meeting.

Record the decision at the top when it is made. A resolved design doc should start with "Decision: we are doing X, decided 2026-03-18, because Y." The person finding this in 2028 wants that sentence and nothing else.

the thing that makes them worth writing#

The value is not the document. It is that you discovered the flaw while writing rather than while implementing, and that someone who knew something told you before you had built the wrong thing.

If you write a design doc and nothing changes as a result, either your design was already right — possible, uncommon — or nobody engaged, and the process is theater.

Measure it that way: how many of your design docs changed the design? If the answer is none, stop writing them in this format and figure out what would actually get you input.

Both failures come from the same mistake: treating "no" as a verdict rather than as the opening of a conversation about trade-offs.

what the request actually is#

When someone asks you to build something, they are not asking for the thing. They are asking for an outcome, and the thing is their guess at how to get it.

That means the highest-value response is frequently not yes or no. It is a better guess.

"You are asking for a real-time dashboard. What decision are you going to make from it? If it is 'should we page someone,' an alert is better than a dashboard and it is a day of work instead of a month."

That is a no to the request and a yes to the outcome, and nobody experiences it as obstruction.

Ask what the outcome is before you evaluate the request. Half the time the request evaporates.

the four honest noes#

"Not this, that." The alternative approach that achieves the same outcome for less. This is the best one and it requires actually understanding the problem.

"Yes, and here is what it displaces." Not a no. A statement about capacity, which is factual and is the other person's decision to make.

"I can do that in this cycle. It means the API migration slips to next quarter. Which do you want?"

This is enormously more effective than "we do not have time," because it hands the prioritization decision to the person whose job it is, with the information they need.

"Yes, after X." A sequencing objection. "We can build this on top of the new data model. Building it on the old one means we build it twice."

"No, and here is the risk I am flagging." The real no, reserved for correctness, security, legal, or ethical problems. Use it rarely so that it lands when you do.

"I am not going to implement this the way it is specified because it stores plaintext credentials. I will implement it with a token exchange, which takes three extra days. If that is unacceptable, I want the decision documented and made by someone who can accept the risk."

That is a hard sentence to say and it is the sentence the job sometimes requires.

the ones that do not work#

"That is not possible." Almost always false, and the person will find someone who says it is. Say "that would take six months" instead, which is the real constraint and is checkable.

"That is a bad idea." Without an alternative, this is just friction.

Silence. Not responding is a no that damages trust, because it looks like you did not care rather than that you disagreed.

"Sure" followed by not doing it. The worst one. It destroys your reliability, which is the only currency you actually have.

the timing#

Say no early. The cost of a no rises with every day of planning that assumed a yes.

An objection raised in the design review is a discussion. The same objection raised two weeks before launch is a crisis, and people will remember that you could have said it earlier — correctly.

If you have doubts, voice them while they are cheap.

the part about capital#

Every no spends something. Every yes earns something. If you never say yes, your noes stop landing, because you have become the person who says no.

Deliver reliably on what you agree to. That is what makes the refusal credible when it matters. Engineers who are trusted to ship get enormous latitude to push back, and engineers who are not, do not — regardless of whether they are right.

the hardest case#

Sometimes you are overruled on something you believe is wrong, and it is not a correctness or ethics issue — it is a judgment call and someone with the authority made a different one.

Disagree and commit is the right practice here and it is genuinely hard. Say your piece once, clearly, in writing. Then build the thing well.

Do not build it badly to prove a point. Do not relitigate it in every standup. Do not say "I told you so" if it goes wrong — the written record already said it, and gloating costs you the ability to be listened to next time.

You will be wrong about some of these. That is the actual reason to commit gracefully: you are not always right, and a culture where disagreement is followed by good-faith execution is one where being wrong is survivable for everyone, including you.