The prompt
Score 10 of 10, Excellent
Use it when Something broke or needs a decision, and you have to explain it to people outside engineering in words they can act on.
- {{audience}}
- {{channel}}
- {{technical_notes}}
- {{confirmed}}
- {{reader_action}}
- {{next_update}}
Full prompt and why it works
Prompt
Explain the technical problem below to {{audience}}, who are not engineers, so that they understand what happened and what it means for them, and can make any decision or tell customers what they need to. It will go out as {{channel}}. The technical facts, as the engineers wrote them: """ {{technical_notes}} """ What is confirmed, and what is not yet known: {{confirmed}} What the readers need to decide or do, if anything: {{reader_action}} When the next update will come: {{next_update}} Write it in this order: 1. What happened, in one or two sentences, described by what users or customers saw rather than by what failed inside the system. 2. The impact: who was affected, how, and since when, using confirmed facts only. 3. What we are doing about it, and when the next update comes. 4. Choices or trade-offs, if there is a decision to make: each option with its cost, time and risk in business terms. 5. What readers should do or tell customers, if anything. Keep it under 250 words. After it, add a short list headed "Terms I replaced" that pairs each technical term from the notes with the plain words you used, so an engineer can check that nothing became wrong in translation. Use plain words and no acronyms. For example, instead of "the database connection pool was exhausted", write "the system ran out of connections to its database, so new requests had to wait and many failed". That example shows the form only. Use at most one comparison to everyday life, and only if it is accurate. Do not guess at the cause, the fix date or the number of people affected; where the notes do not confirm one, write "not yet known". Do not blame a person, a team or a vendor, and do not play the problem down with words like "minor" or "small" unless the facts show its size. The tone should be calm and direct, like a colleague who knows the details and respects the reader's time. If the notes contradict each other, or a fact the readers will certainly ask about is missing, list it after the explanation under "To confirm with engineering" rather than filling it in.
Variables
- {{audience}}
- Who will read it, for example "the sales team" or "the executive team".
- {{channel}}
- For example "a Slack message in the company channel" or "an email to account managers".
- {{technical_notes}}
- The engineers' description: what failed, the cause if known, the fix, the timeline.
- {{confirmed}}
- For example "confirmed: checkout failed for 40 minutes; not known: how many orders were lost".
- {{reader_action}}
- For example "decide whether to email affected customers" or "nothing, for awareness".
- {{next_update}}
- For example "by 3 pm Eastern today".
Why it works
- Who it's for. It starts from what users saw and what the readers must decide, rather than from what failed inside the system.
- What good looks like. A list of replaced terms lets an engineer confirm that the plain version is still accurate.
- If unsure. Unconfirmed causes, dates and counts read "not yet known", and contradictions go to a list for engineering.