thinkhard.SI

Prompt repository Engineering & code

Write a short technical design document

You need the problem, approach, alternatives and risks written up before the team builds.

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

Engineering & codeAny chat

The prompt

Score 10 of 10, Excellent

Use it when You need the problem, approach, alternatives and risks written up before the team builds.

  • {{reviewers}}
  • {{problem}}
  • {{approach_notes}}
  • {{current_system}}
  • {{alternatives}}
  • {{constraints}}
  • {{known_questions}}
Full prompt and why it works
Prompt
Write a short technical design document for the change described below. It is for {{reviewers}}, who will review it before the team starts building, so it should make the problem, the proposed approach and its risks clear enough to approve, challenge or improve after one reading.

Problem, and why it matters now:
"""
{{problem}}
"""

Proposed approach, in my notes:
"""
{{approach_notes}}
"""

Current system, as far as it matters here:
"""
{{current_system}}
"""

Alternatives I considered: {{alternatives}}
Constraints (deadline, systems we must use, compliance or performance requirements): {{constraints}}
Open questions I already know about: {{known_questions}}

Use these headings:
1. Summary: three or four sentences that someone outside the team would understand.
2. Problem and goals: the problem, two to five goals, and non-goals (what this design deliberately does not cover).
3. Proposed design: how it works, the main components and data flow, and any changes to interfaces, data or storage. Include a simple text diagram or a numbered flow if it helps.
4. Alternatives considered: each with its main trade-off and why it was not chosen, described fairly enough that a reviewer could argue for it.
5. Risks and mitigations: a table with the columns Risk, Likelihood, Impact, Mitigation.
6. Rollout and rollback: how it ships (for example behind a feature flag or in stages), how we will know it works, and how to undo it.
7. Testing and monitoring: what will be tested before release and what will be watched after.
8. Open questions: decisions the reviewers need to make or weigh in on.

Keep it between 700 and 1,200 words, in plain technical prose, and spell out any acronym the first time it appears. The document should be short enough to review in one sitting and specific enough to build from.

Use only the facts in my notes. Do not invent performance numbers, benchmarks, costs, library features or system behavior; where the design depends on something I have not given, write "Assumption:" and state it so a reviewer can check it. Do not present my preferred approach as the only reasonable one.

If the notes leave the goals or the scope unclear, say so at the top and list the questions to answer before review, rather than designing around a guess.

Variables

{{reviewers}}
Who reviews it, for example "the platform team and our staff engineer".
{{problem}}
What is wrong or missing, who it affects, and why it needs solving now.
{{approach_notes}}
Your notes on the approach you favor: components, data, interfaces, sketches in words.
{{current_system}}
The parts of today's system the change touches: services, data stores, interfaces.
{{alternatives}}
Other approaches and why you leaned away from them. Write "none yet" if you have not compared any.
{{constraints}}
Deadlines, required technologies, compliance, performance or budget limits.
{{known_questions}}
Questions you already know are open. "None" is fine.

Why it works

  • Who it's for. Writing for reviewers who must approve or challenge it in one reading decides what goes first: the problem and goals, not the implementation.
  • What to avoid. Invented benchmarks and library features are ruled out; anything the design rests on that you did not supply is labeled "Assumption:" for a reviewer to check.
  • If unsure. Unclear goals or scope are raised as questions at the top, because a design built on a guessed scope wastes the review.

How to use it

  1. Press Fill in variables 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.