The vendor eligibility feed arrived malformed overnight. The reconciliation job rejected the batch, so roughly two hundred members will not see updated benefits until it is reprocessed. No data was lost. It will be fixed by this afternoon.
Now say that to the client.
The sentence above is accurate, complete, and — delivered as written — will produce a twenty-minute call, an escalation, and a request for a written report. Not because the situation is bad, but because of how it lands.
Communicating technical problems well is a learnable skill with a small number of rules. Here they are.
Lead with impact, not mechanism
This is the single biggest change you can make, and it inverts how engineers naturally think.
You reason causally: the feed was malformed, therefore the job failed, therefore members are stale. So you explain in that order. But your client does not care about the first two steps until they know whether the third one hurts them.
“The vendor's eligibility feed came through with a schema mismatch overnight, so the reconciliation Lambda threw on the parse step and the batch went to the dead-letter queue.”
“About 200 members will see yesterday's benefit information until this afternoon. Nothing has been lost and nobody has incorrect coverage. The cause is a bad file from the vendor and we are reprocessing it now.”
Same facts. The second one answers the questions they actually have, in the order they have them: who is affected, is it dangerous, is it being handled.
Answer the three questions before they are asked
Every stakeholder has the same three, whether or not they say them out loud.
How bad is it? Scope and severity. “200 of 40,000 members” is enormously more useful than “some members”.
Is anything lost or wrong? This is the one that causes panic. If data is safe, say so in the first two sentences — it defuses most of the anxiety immediately.
What happens next and when? A specific time, even if it is only “an update by 3pm”.
If your message does not contain all three, it will generate a reply asking for whichever is missing — and that reply will arrive with more urgency than the original issue warranted.
Never say “we cannot reproduce it”
It is often true. It always sounds like we do not believe you.
What you mean is that the failure is conditional and you have not yet found the condition. Say that instead: “It is affecting a small number of submissions rather than all of them, which tells us it depends on something specific. We have added tracking to capture the exact conditions and expect to identify the pattern within a couple of days.”
Same situation, but now it reads as a process in motion rather than a dismissal.
Give estimates as ranges with reasons
“Two days” will be remembered as a promise. When it becomes four, the problem is not the extra two days — it is that you were wrong, and now everything else you say is discounted.
What works better is naming the uncertainty explicitly:
“If it is what we think it is, two days. If the vendor has to change their export format, it depends on their timeline and I would not want to guess. I will know which by Thursday.”
Most clients are fine with uncertainty. What they cannot plan around is false certainty, and they remember which one you gave them.
Use their vocabulary, not yours
Every domain has its own words, and your clients use them fluently. Translate into those rather than making them translate out of yours.
| Instead of | Say |
|---|---|
| “The API is timing out” | “Enrolment submissions are failing for some members” |
| “A race condition in the frontend” | “If the page is used before it finishes loading, it can save the wrong plan” |
| “We need to refactor the billing module” | “Billing changes currently take two weeks each; a month of work now would bring that to two days” |
| “It is in the dead-letter queue” | “Those records are held safely and will be reprocessed” |
That third row is worth dwelling on. Technical debt is the hardest thing to fund because engineers describe it as a code quality problem. Described as a delivery-speed problem with numbers attached, it becomes a business decision the client can actually make.
When you need them to decide, give options with consequences
Do not ask a non-technical client to choose between approaches. Ask them to choose between outcomes.
Two ways forward:
A. Ship Friday as planned, without the automatic eligibility sync.
Your team enters those 200 members manually for about a week.
Roughly 3 hours of admin work.
B. Hold the release to Wednesday and include the sync.
No manual work, but the enrolment deadline moves by two days.
My recommendation is A, because the manual effort is small and
the deadline matters more to your members than to us.Give the recommendation. Clients hire you partly so they do not have to weigh technical trade-offs, and “here are two options, you decide” without a view is passing the work back.
During an incident: update on a clock
The single most useful habit is committing to an update time and hitting it, even when there is nothing new.
“Still investigating. We have ruled out the payment provider. Next update at 2pm.”
That message contains almost no information and is enormously valuable. Silence during an incident is read as loss of control, and a client who has not heard from you in ninety minutes starts phoning people. A team that updates every thirty minutes reads as being on top of it, even if progress is identical.
Say the thing you do not want to say, early
When something is going to slip, or when the mistake was yours, the temptation is to wait until you have a solution so you can deliver the bad news and the fix together.
That reliably makes it worse. Clients are generally forgiving about problems and rarely forgiving about being told late — because being told late removes their ability to manage their own stakeholders.
Say it as soon as you are confident it is true, with what you know and what you are doing. “This will not be ready Friday, here is why, here is the new date, here is what we are doing to protect the deadline after it” costs you far less than the same news on Thursday evening.
Own it without dramatising it
If it was your mistake, say so plainly once, then move to the fix. Over-apologising makes people more anxious, not less — it suggests the situation is worse than you are letting on.
“I am so sorry, this is completely our fault, we should have caught this, I understand you must be really frustrated…”
“That was our error — we missed it in review. It is fixed and deployed. We have added a check so this specific case cannot recur.”
The second is more reassuring precisely because it is calmer, and because it ends with something that makes recurrence less likely.
The template I actually use
WHAT'S HAPPENING
One sentence, in their terms, about the effect on their users.
WHO IS AFFECTED
Numbers where you have them. Say explicitly what is NOT affected.
IS ANYTHING AT RISK
Usually "no data has been lost or changed incorrectly" — say it early.
WHAT WE'RE DOING
Present tense, specific.
WHEN YOU'LL HEAR FROM US NEXT
A time. Then hit it.Five short sections, sent quickly, beats a polished report sent an hour later.
The underlying principle
Your client is not trying to understand your system. They are trying to work out whether they can trust you to handle it.
Every choice above follows from that. Impact first, because that is what they can act on. Specifics, because vagueness reads as not knowing. Ranges, because false precision destroys credibility the moment it slips. Early bad news, because late news removes their agency.
Get that right and technical problems stop damaging the relationship. Handled well, they usually strengthen it — because anyone can look competent when nothing is broken.
