thinkhard.SI

Prompt repository Engineering & code

Explain a technical problem to people who are not engineers

Something broke or needs a decision, and you have to explain it to people outside engineering in words they can act on.

Registry no.
ENG-044
Collection
Engineering & code
Laid out for
Any chat model
Score
10 out of 10
Blanks to fill
6
Added

Engineering & codeAny chat

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.

How to use it

  1. Press Fill in blanks and type your details into each blank. What you type stays in this browser.
  2. Copy the filled prompt into the AI tool you already use, such as ChatGPT, Claude or Gemini, or open it in the Grader or the Prompt Tester here.
  3. Before you rely on it, try it on three or four real examples. The Prompt Tester runs them all at once and shows which ones go wrong.
Use it from code

Get this prompt as JSON from the free REST API, with your own text in the blanks, or let an AI assistant fetch it through the MCP server. No key.

curl -s https://thinkhard.si/api/v1/prompts/explain-technical-problem-to-non-engineers

With the MCP server added to Claude, ChatGPT, Cursor or VS Code, call get_prompt with {"prompt": "explain-technical-problem-to-non-engineers"}, or just ask for it by name.