From the free book Delta: Closing the Specification Gap (Dhuri, 2026). The PDF is the canonical edition — figures, tables, and code formatting are simplified online.
H Reverse Review An AI Critiques Its Own Prompts “The most valuable thing I learned from rewriting every prompt in this book: the prompts that fail most consistently are not the ones with wrong constraints — they are the ones with no output specification. The model doesn’t know how much to generate. Tell it exactly what you want.” — Sandeep Dhuri This appendix collects the working notes I kept while writing the book. For every major prompt — generation, review, debugging, documentation — I kept a running list of what the prompt produced well, what it produced badly, and which constraint clauses turned out to matter most. The notes are deliberately specific: which output specification was missing, which negative-only constraint failed without a paired alternative, which ambiguity protocol the prompt had no answer for. The methodology is unglamorous: write, run, observe, refine, repeat. The findings were occasionally humbling. I have included them here because a book about specifying what you want from an AI tool is not done with itself until it asks the same hard questions of its own prompts. How to Use This Appendix If a prompt from this book produces inconsistent results for your team, find it in the section below. The AI’s assessment explains exactly what information the model needed that the prompt did not provide. The enhanced version adds that information.
H
163
If you are new to the book: read Section H.2 (The Ten Universal Improvements) before using any prompt. These ten additions improve the quality of every prompt in the book.
H.1 The Five Critical Gaps Found in This Book’s Prompts The audit of This edition’s prompts found five systematic gaps that appeared across every chapter. Fixing these five gaps will improve the quality of every prompt in the book. Gap 1: Zero Output Specifications The most frequent gap: prompts specify what to generate but never how to format the output. Should the model generate a complete class, a method body only, or multiple files? Without this, the model guesses — and guesses differently each time.
ANTI-PATTERN — Generation Prompt Without Output Specification AVOID: ”<role>Senior Java engineer.</role><task>Implement PatientService.updateContactInfo().</task>” USE: Add <output_specification> to every generation prompt: ”<output_specification>Generate: complete compilable class. Include: package declaration + all imports. One class per code block. No preamble. No explanation before the code. If anything is ambiguous: list your assumptions as numbered points before the code. </output_specification>” Why: Without this, the model might generate a method body (requiring you to add the class wrapper), skip imports (requiring manual completion), provide three alternatives (requiring you to choose), or add a lengthy explanation before the code. All of these are correct completions of the prompt as written.
H
164
Gap 2: Negative-Only Constraints Every constraint in the book’s prompts was prohibitive: NEVER use double, do NOT use @Autowired, PHI must NEVER appear in logs. The model knows what to avoid but is not told what to use instead. When a common pattern is prohibited without a specified alternative, the model either defaults to the second most common pattern (which may also be wrong) or hedges by showing multiple options. Negative-Only (This edition)
”NEVER use double or float for money”
”NEVER double/float; ALWAYS Money<TCurrency> (C#) or Money.of(String, String) (Java) for ALL monetary values”
”PHI must NEVER appear in log statements”
”PHI never in logs; ALWAYS log correlation ID only: log.info(\”patientId={}\” , id)”
”Do NOT use @Autowired field injection”
”No @Autowired; ALWAYS constructor injection via @RequiredArgsConstructor”
”NEVER FetchType.EAGER on relationships”
”No FetchType.EAGER; ALWAYS explicit @EntityGraph on the specific query method that needs join loading”
”Do NOT drop columns in migrations”
”Additive only; ALWAYS create new columns then migrate data; DROP in a subsequent migration after verification”
Gap 3: No Ambiguity Resolution Protocol When a prompt is unclear, the model has three options: ask a clarifying question, make an assumption and proceed, or make an assumption and document it. The prompts in this book specified none of these. Without guidance, the model defaults to making silent assumptions — assumptions that may be incorrect and that the engineer cannot see until they read the output carefully. <!-- Add this to every generation prompt <constraints> section: --> If anything in this prompt is ambiguous or underspecified: - List your assumptions as numbered points BEFORE the code - Format: 'ASSUMPTION: [what you assumed] because [why]' - Do NOT proceed silently with assumptions you have not stated - If a required type (Money<T>, Result<T>, etc.) is referenced but ,→ not defined: use the standard implementations from Appendix B H
165
Gap 4: No ‘One Answer’ Instruction Technical models tend toward thoroughness. Without explicit instruction to provide a single implementation, the model often presents alternatives with trade-off explanations, or hedges with ‘you could also consider’ paragraphs. For production code generation, a single correct implementation is almost always more useful than three alternatives with trade-offs. <!-- Add this to every generation prompt: --> PROVIDE ONE IMPLEMENTATION. Do not offer alternatives. Do not ask which approach I prefer. Do not include 'alternatively, you could...' sections. If there are trade-offs that affect the implementation choice, state the assumption you made and proceed.
Gap 5: The Pattern Example Guidance Is Too Vague Chapter 3 instructs engineers to include a ‘representative pattern example: 20–40 lines of method body.’ This is good guidance, but it doesn’t tell engineers what makes an example representative or what specific elements the model needs to see. <!-- More specific guidance for <pattern_example>: --> <pattern_example> Paste 20-40 lines from an EXISTING implementation in the same layer as the code you are requesting (Service if requesting a Service, CommandHandler if requesting a CommandHandler, etc.). The example MUST show: 1. How your team injects dependencies (constructor/field/@Autowired ,→ ?) 2. How your team handles business rule failures (Result<T>/ ,→ exception/both?) 3. How your team logs (structured params/interpolation/which ,→ framework?) 4. How your team publishes domain events (inside/outside ,→ transaction?) DO NOT paste a test class, a controller, or a domain entity as the pattern example for a service implementation.
H
166
</pattern_example>
H.2 The Ten Universal Improvements These ten additions improve every prompt in the book. Append them to your team system prompt to apply them automatically to every interaction. Enhanced System Prompt Additions — Add to Every Team System Prompt <universal_output_rules> OUTPUT FORMAT: - Code first. Explanations within the code as comments. No preamble. ,→ - Complete compilable output: namespace/package + all imports + ,→ full class. - ONE implementation. No alternatives. No 'you could also...' ,→ sections. - If adding tests: generate implementation class first, then test ,→ class separately. CONSTRAINT FORMAT (positive+negative pairs): - For every 'NEVER X': also specify 'ALWAYS use Y instead'. - Example: 'NEVER double for money. ALWAYS use Money<TCurrency> (C#) ,→ . NEVER @Autowired. ALWAYS use @RequiredArgsConstructor. PHI NEVER in logs. ALWAYS log correlation ID (UUID) only ,→ .' AMBIGUITY PROTOCOL: - If anything is unclear: list ASSUMPTION: [what] because [why] ,→ before code. - NEVER proceed silently with unstated assumptions. - If a type is referenced but not defined: use Appendix B ,→ implementations. SCOPE: - Generate ONLY what was requested. Do not improve unrelated code.
H
167
- Do not modify .csproj, pom.xml, or configuration files unless ,→ explicitly asked. - New class = new file. Modified class = show complete updated ,→ class. </universal_output_rules>
H.3 Prompt-by-Prompt Assessments The following assessments cover every major prompt from the book’s recipes. Each shows the version in the book, the model’s assessment of where it would produce inconsistent output, and the enhanced version with the gaps filled. Chapter 3 — The Specification Frame AI REVIEW: The Core Specification Frame Template
GOOD
Verdict: The six XML elements (role, architecture, existing_interface, pattern_example, domain_types, task, constraints) are well-chosen. The structure works. The consistent failure mode is engineers completing only 3 of the 6 elements — particularly skipping existing_interface and pattern_example. 1. Engineers frequently omit existing_interface — without it, I generate the interface I think fits, which may not match your actual codebase contracts. 2. Engineers frequently omit pattern_example — without it, I use the most common structural pattern in the model’s training data, not your team’s specific conventions. 3. The <domain_types> section often says ’see Appendix B’ without actually pasting the types. I cannot read Appendix B. If a type is not in the prompt, it is not in my context. Enhanced version: <required_elements_checklist> Before sending: confirm ALL six elements are present: [ ] <role> includes platform VERSION (not just language) [ ] <existing_interface> has the actual interface (not 'see codebase') [ ] <pattern_ example> is from the SAME LAYER as the requested code [ ] <domain_types> has the ACTUAL type definitions pasted inline [ ] <task> specifies ALL Result<T> failure variants by name [ ] <constraints> has both NEVER and ALWAYS for each domain rule </ required_elements_checklist> H
168
Chapter 4 — Code Generation Recipes AI REVIEW: Recipe 1: HIPAA Patient Service (Java)
GOOD
Verdict: The constraints are specific and correct. @AuditLog is explicitly required, PHI prohibition is clear, and the two lifecycle guards (deceased/merged) are named. This prompt produces consistent, compliant output when all elements are provided. 1. Missing: output specification (full class or method body only? Include the interface definition?) 2. Missing: whether to generate the corresponding unit test class alongside the implementation. 3. Minor: the @AuditLog annotation parameters would benefit from a concrete example showing the exact attribute format your team uses.
GOOD
Verdict: The order-of-operations constraint (’STEP 1 through STEP 5’) is the highest-value addition to any idempotency prompt. Naming the steps by number makes it structurally impossible for me to reorder them. 1. Missing: what to do when SaveChangesAsync throws — should the idempotency key be stored before or after the gateway call? 2. Missing: the specific exception type to catch for gateway timeouts (different providers use different exception hierarchies).
EXCELLENT
Verdict: The @Version + @Retryable constraint combination is exactly correct and the InsufficientStockException ’MUST NOT be swallowed’ instruction prevents the most common mitigation mistake. This prompt will produce correct, thread-safe code consistently. 1. No significant gaps. This is the model prompt in Part II.
H
169
Chapter 5 — Code Review AI REVIEW: The Critic Frame
EXCELLENT
Verdict: The adversarial framing (’find problems, do NOT evaluate quality’) is the most important single instruction in the book. It structurally prevents the validation mode that generic review prompts trigger. BLOCKING/IMPORTANT/MINOR structure produces actionable, prioritized output consistently. 1. The only gap: ’Do NOT list anything correct’ could be reinforced with ’If you find yourself writing a positive sentence, delete it and continue looking for problems.’
GOOD
Verdict: The explicit PHI field list (PatientName, DateOfBirth, SSN, DiagnosisCode, etc.) is essential and well-specified. The CFR citation requirement (’Cite the CFR section for every finding’) elevates output from advisory to compliance-reportable. 1. Missing: the specific HIPAA Security Rule technical safeguards checklist (encryption at rest, transmission security, audit logging completeness). 2. Missing: whether to flag ’risk’ items even if no current code violates them (this matters for architect-level reviews).
Verdict: The five injection categories (direct, indirect, tool escalation, data exfiltration, system prompt leakage) are correct. However, the prompt does not specify what makes a PoC payload ’valid’ in the context of the engineer’s specific system — without this, I produce generic payloads rather than system-specific ones. 1. Missing: the system’s actual user input entry points (form fields, API parameters, file uploads, database records). 2. Missing: which MCP tools are connected (the most dangerous injection vectors depend on what tools the model can call). 3. Missing: minimum viable PoC format (’show the exact HTTP request / form submission / database record that exploits the vulnerability’). Enhanced version: <!-- Enhanced: add system context to injection audit --> <system_context> User input entry points: [list form fields, API params, file uploads] Connected MCP tools: [list tools with their most sensitive capabilities] PoC format: show the exact user input / API request / DB record that would trigger the vulnerability in THIS system. </system_context> H
170
Chapter 6 — Debugging AI REVIEW: The XML Evidence Brief
EXCELLENT
Verdict: The Evidence Brief is the best-designed prompt in the book. The six-section structure with explicit <already_ruled_out> element produces the highest diagnostic quality of any prompt in this book. The instruction ’Distinguish confirmed facts from hypotheses’ prevents the most common diagnostic error. 1. One enhancement: the task section asks for ’specific diagnostic commands (not check the logs — exact commands)’. This would be stronger with platform specificity: ’For Java/Spring: exact Actuator endpoints, log4j2 queries, or Datadog APM commands. For .NET: exact dotnet-trace, PerfView, or Application Insights KQL queries.’
GOOD
Verdict: The ’six questions before hypotheses’ instruction is well-designed. The ’Do NOT give hypotheses before I answer the questions’ constraint prevents the anchoring problem effectively. 1. Missing: what to do after answering the questions. Engineers sometimes answer the six questions and then wait — the prompt should explicitly say ’After I answer all six, your next response should be exactly two hypotheses ranked by likelihood, nothing else.’ Enhanced version: "Ask me exactly SIX diagnostic questions. After I answer ALL six: provide EXACTLY two hypotheses, ranked by likelihood (most likely first). Nothing else --- no questions, no preamble, no options. Do NOT give hypotheses before I answer all six questions."
Chapter 11 — Prompt Files AI REVIEW: The .md Prompt File YAML Frontmatter Standard
GOOD
Verdict: The YAML structure captures the most important metadata: model, temperature, platform, stack, required_inputs. The last_validated field is particularly valuable — it forces quarterly maintenance. 1. Missing: a ’failure_modes’ field documenting known cases where this prompt produces poor output. This makes the library self-documenting about limitations. 2. Missing: a ’test_assertions’ field summarizing the promptfoo assertions, so the YAML is self-contained documentation. Enhanced version: # Add to YAML frontmatter: failure_modes: 'Omitting existing_interface causes generated contract mismatch' - 'Pattern example from wrong layer causes incorrect DI pattern' test_assertions: - 'Output contains @AuditLog' - 'Output does NOT contain log.info.*getName' H
171
Chapter 13 — CLAUDE.md AI REVIEW: The CLAUDE.md Template (Java)
Verdict: The stack, architecture rules, and hard constraints sections are well-structured. The critical gap: the current template has no ambiguity resolution protocol and no ’one answer’ instruction. Without these, agentic Claude Code sessions produce output where I silently assume your intentions rather than stating them. 1. Missing: ambiguity resolution protocol — what to do when requirements are unclear. 2. Missing: output scope instruction — how many files to generate per task, whether to include tests automatically. 3. Missing: ’no alternatives’ instruction — agents are particularly prone to offering options when uncertain. 4. Missing: what ’improve’ means vs. ’rewrite’ vs. ’fix’ — these three words produce dramatically different scopes of change. Enhanced version: ## Ambiguity and Scope Protocol When any requirement is unclear: - List ASSUMPTION: [what] because [why] before writing code - NEVER proceed silently with unstated assumptions - NEVER rewrite code you were not asked to change ## Output Scope - 'Implement X': generate X only. Do not improve adjacent code. - 'Fix X': correct the specific issue. Do not refactor unrelated code. - 'Improve X': ask for clarification on scope BEFORE generating. - 'Review X': use the Critic Frame (find problems, not quality). ## Answer Format ONE implementation. No alternatives. No 'you could also...' sections.
H.4 The Fully Enhanced Generation Prompt This is the complete Specification Frame for this edition: every gap surfaced during the prompt quality review (Appendix H) has been filled. Use it as the basis for every code generation prompt in the book.
H
172
The Complete Specification Frame — All Gaps Filled <!-- ============================================================ SPECIFICATION FRAME — COMPLETE VERSION All sections required. Skipping any section = inconsistent ,→ output. ============================================================ --> <role> You are a [Senior/Staff] [C#/Java] engineer on a [domain] platform. Platform: [.NET 9 / Java 21 LTS] Stack: [list exact dependencies with versions] Standing standard: [the most critical non-negotiable for this ,→ context] </role> <architecture> Pattern: [Clean Architecture/DDD/Layered] Error handling: Result<T> for business rules, exceptions for ,→ infrastructure DI: Constructor injection only via @RequiredArgsConstructor / no ,→ @Autowired Events: Published AFTER transaction commit, never inside ,→ @Transactional </architecture> <existing_interface> [THE ACTUAL INTERFACE. Paste it. Do not write 'see the codebase'.] </existing_interface> <pattern_example> [20-40 lines from an existing implementation IN THE SAME LAYER. MUST show: DI pattern, error handling, logging style, event ,→ publishing. DO NOT use a test class, controller, or entity as the example.] </pattern_example> <domain_types> [PASTE the actual type definitions inline. Do not reference Appendix ,→
B.
H
173
If using Money<T>: paste the record definition. If using Result<T>: paste the class definition. The model ’cant infer types not present in the context window.] </domain_types> <task> Implement [ClassName.MethodName] that: - [Requirement 1 with specific input types and expected output] - [Requirement 2] - Returns [type] with ALL variants: Success([type]), Failure([code]) ,→
for each case
</task> <constraints> NEVER double or float for money. ALWAYS Money<TCurrency> (C#) or ,→ Money.of() (Java). PHI NEVER in logs. ALWAYS log correlation ID (UUID) only. NEVER @Autowired. ALWAYS @RequiredArgsConstructor. [Add domain-specific NEVER/ALWAYS pairs for your system] Include ALL using directives (C#) / package + ALL imports (Java). Compilable code only. No pseudocode. No TODO: implement. Do not modify dependencies (.csproj / pom.xml) without instruction. </constraints> <output_specification> Generate: ONE complete compilable class. Include: package/namespace declaration + all imports/using ,→ directives. NO preamble. Code first. Explanations as inline comments only. ONE implementation. No alternatives. No 'you could also...' ,→ sections. If ambiguous: ASSUMPTION: [what] because [why] BEFORE the code. If a referenced type is not in this prompt: use the Appendix B ,→ implementation. </output_specification> H
174
H.5 What Works Exceptionally Well For balance: these are the prompts in this book that produce the most consistently excellent output, requiring no enhancement. Prompt / Recipe
@Version + @Retryable with explicit exception class + InsufficientStockException must not be swallowed = complete, correct, thread-safe output every time.
Six-section XML structure forces systematic evidence assembly. <already_ruled_out> section halves the search space. Produces the highest-quality debugging output of any prompt in this book.
Adversarial framing + BLOCKING/IMPORTANT/MINOR structure + verdict requirement produces actionable, prioritized findings consistently. One of the most well-designed prompts in the book.
Explicit list of files the agent must not modify prevents scope creep. ’Never’ instructions for destructive operations (modify pom.xml, drop columns) are the most effective agent safety mechanism.
Five mandatory adversarial outputs + ’do NOT say whether this a good design’ constraint prevents the validation mode completely. Produces genuine blind spot identification.
Complete platform, DI pattern, error handling, testing, and logging specification in one reusable document. Caching this template removes 90% of the cost of domain specification from each individual prompt.
H.6 Prompt Debugging Guide If a prompt from this book produces inconsistent or incorrect results, diagnose the problem using this guide before rewriting the prompt: Symptom
Fix
Output uses the wrong types (double instead of Money<T>) <domain_types> section empty or references external document the model cannot read. Paste the actual type definition inline in <domain_types>.
H
175
<pattern_example> missing or shows a controller instead of a service.
Paste 20-40 lines from an existing service in the same layer.
No ’ONE implementation, no alternatives’ instruction.
Add <output_specification> section with the universal output rules from H.2.
Output generates a method body when I wanted a full class
No output specification.
Add: ’Generate: one complete compilable class including package/namespace and all imports.’
No ambiguity protocol.
Add: ’If ambiguous: list ASSUMPTION: [what] because [why] before the code.’
CLAUDE.md missing scope constraints.
Add the Ambiguity and Scope Protocol from Section H.3 to your CLAUDE.md.
Generic review prompt without adversarial framing.
Use the Critic Frame: ’Find problems. Do NOT evaluate quality.’
One or more of the six sections is empty.
Fill all six sections. <already_ruled_out> is the highest-value section. Fill it first.
Orchestrator is summarizing the original spec instead of passing it verbatim.
Pass the original specification as an immutable <original_specification> XML block.
Missing imports or using directives despite constraint.
Add: ’Include ALL using directives (C#) / package + ALL imports (Java). Compilable code only. No pseudocode.’
H.7 Summary Verdict As the model these prompts are written for, my overall assessment is: the book’s prompts are well-designed and will produce significantly better output than ad hoc prompting. The five gaps documented in Section H.1 cause the majority of inconsistency when they occur. Filling them with the additions from Section H.2 produces consistently excellent output. The most important change between This edition and This edition is the addition of <output_specification> to every generation prompt and the conversion of all NEVER constraints to NEVER/ALWAYS pairs. These two changes eliminate the most common failure modes without requiring H
176 engineers to understand why they work. The Evidence Brief (Chapter 6) and the Critic Frame (Chapter 5) are the two best-designed prompts in the book. They produce excellent output without modification. If you use only two prompts from this book, use those.
prompts: missing output specification, negative-only constraints, no ambiguity protocol, no ’one answer’ instruction, and vague pattern example guidance. + The Ten Universal Improvements in Section H.2 fix all five gaps simultaneously when added to your team system prompt. + The three best-performing prompts in the book are the Evidence Brief (Ch 6), the Critic Frame (Ch 5), and Recipe 3: Thread-Safe Inventory (Ch 4). Use these as templates for designing other prompts. + CLAUDE.md requires the Ambiguity and Scope Protocol and the Output Scope definitions to prevent silent assumptions and scope creep in agentic sessions. + Every NEVER constraint should have an ALWAYS counterpart. ’NEVER double for money’ without ’ALWAYS use Money<T>’ leaves the model without a specified alternative.