A good fix is a language,
not a technique.

I've shipped fixes that were technically flawless and still watched a client trust us less afterward. How does a correct fix make trust go down, not up? Because it never got translated into anything they could actually evaluate. Being right and being understood turned out to be two different jobs, and only one of them is optional.

01  ·  The fix that's correct and still lands wrong

A client calls because a system is on fire. We find the actual cause, six layers down from where they thought to look, and fix it properly instead of patching the symptom they described. Then we explain it back using the vocabulary we used to find it: connection pool exhaustion, a retry storm, a race on a shared cache key. The client nods, pays the invoice, and quietly starts shopping for a vendor who can tell them what happened in words they can repeat to their own boss.

Nobody's dishonest in that exchange. But a fix explained only in the fixer's language reads, to the client, exactly like a fix they're being asked to take on faith.

02  ·  The translation is not a summary, it's a different fix

The instinct is to write a plain-English paragraph after the technical write-up and call that the translation. It rarely works, because a summary of a technical explanation is still organized around the technical explanation. The client's actual questions are usually different ones entirely: will this happen again, what did it cost, whose call was it, and what do they tell their board. Answering those four, specifically, is the real translation. The technical write-up can live in the appendix.

$ incident summarize --audience=engineer,client --id=inc-5512
[engineer] root cause: unbounded retry loop against a rate-limited
  third-party API, exhausted the shared connection pool at peak load
[client] will it happen again: no — we added a circuit breaker
[client] what it cost: 40 minutes of checkout downtime, ~$3,100 in
  lost orders, no data loss
[client] whose call: ours — a retry policy we shipped without a cap
# same incident. the client version has zero jargon and still answers
# every question their board is actually going to ask.

03  ·  How we actually do this

1. 01Open with the four questions, not the root cause. Will it recur, what did it cost, whose call was it, what do you tell your board — in that order, before a single technical term.
2. 02Borrow the client's own vocabulary, not ours. If they call it "the checkout thing," the write-up calls it "the checkout thing" too, with the technical name in parentheses once, not as the headline.
3. 03Show the decision, not just the fix. What we chose not to do, and why, tells a client more about our judgment than the diff does.
4. 04Let the technical write-up exist, just not first. The engineers on their side still get the real detail. It's an appendix, not the pitch.

04  ·  Correct is the floor, not the deliverable

A fix nobody can repeat isn't finished, it's just correct, and correct alone has never been what kept a client through the next incident. The work isn't done when the system is fixed. It's done when the client can tell the story of the fix in their own words, to someone who wasn't in the room.