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.