Part VI — Debugging Prompts, Retrieval, and Hallucinations

The prompt that “just needed a tweak” — and took down the refund bot

Chapter 29 ended with the trajectory triaged and the loop convicted: the agent re-applies equivalent edits because nothing in its instructions forbids equivalent retries, requires exit-code gating, or defines progress. That “nothing” has a name. It is the prompt — a program with no repository, no version, no diff, and no test, edited by folklore until it breaks in production.

Concrete failure. A support assistant answers refund questions. An engineer “tightens” the system prompt in the dashboard — adds one sentence about being concise — and refund answers start citing reference numbers that do not exist. Nobody can say what changed: the dashboard shows the current text, not the previous text; there is no commit, no hash, no record of which model, retrieval snapshot, or test suite the old wording passed against.

OBSERVATION: two prompt texts exist (a pasted copy in a ticket, the current dashboard text); they differ by at least one sentence, but the full diff is UNKNOWN because neither text is hashed or versioned. HYPOTHESIS H1 (prompt regression): the added sentence changed the failing behavior. H2 (environment drift): model, retrieval index, or context assembly changed under a fixed prompt. H3 (untested prompt): the prompt never had a passing criterion, so “regression” is unmeasurable. INFERENCE: none yet — H1/H2/H3 predict different version-and-test signatures and are separable only once the prompt is an artifact.

This chapter’s question: how do we make a prompt reproducible, diagnosable, and testable — like any other program?

Two things you control: the instruction and the evidence

A prompt-and-retrieval system exposes two broad classes of controlled artifact: what the system was told — the prompt program, Chapters 30–31 — and what it was given as evidence — retrieval and the assembled context, Chapters 32–35. Part VI makes both inspectable in turn. Not every AI failure belongs to one of these two classes; they are Part VI’s focus, not a universal taxonomy.

This chapter starts with the instruction because it is the artifact you author directly and the one most often edited by folklore. Chapter 25 already debugged whether the intent behind it was right — the specification question, did we ask for the right thing? This chapter asks a different one: what executable instruction artifact did the model actually receive — which version, assembled how, tested against what? The lineage is intent → specification → prompt program → rendered model input; Chapter 25 owns the first two, this chapter owns the prompt program (versioning, identity, assembly, fixtures, diffs, deployment gates), and Chapter 19 already covered the rendered input. Chapter 25’s specification argument is not re-opened here.

Why “just read the prompt” fails first

The obvious move — opening the dashboard and reading the current wording — fails because words are not the program. The program is words plus versions plus assembly plus tests. Five defects hide behind prompt-text review:

1. No identity. Two engineers paste “the same” prompt from memory; whitespace, line breaks, and a missing stop sequence differ. Without a content hash, sameness is an OPINION, not a MEASUREMENT. And the difference is not cosmetic: Mizrahi and colleagues generated instruction paraphrases across 39 tasks and 20 models — 6.5 million instances — and found that semantically equivalent templates produce very different performance, both absolute and relative to each other (Mizrahi et al., 2024). A whitespace-level diff can be a behavior-level diff.
2. No history. The dashboard overwrites. The question “what changed on Tuesday?” has no answer, so bisection is impossible.
3. Hidden assembly. The system prompt is one input among many: retrieved chunks, tool outputs, conversation history, and template glue are concatenated at runtime. Reading the template alone never shows the model input.
4. No contract. “Be helpful and accurate” is not a test. Without a measurable success criterion (exact fixture set, pinned contexts, pass threshold over repeated trials), every edit is vibes.
5. Multi-variable edits. Wording, temperature, top-k, and index version change together. When the symptom moves, attribution is UNKNOWN.

OPINION: a prompt that lives only in a dashboard textbox is not an asset. It is a rumor about an asset. Promote it to code or stop debugging it as code.

The mental model: prompt-as-program — a versioned, hashed, assembled, tested artifact. The prompt file is source; the assembled model input is the build; the fixture suite is the test. Debug the build, blame the source, gate on the test.

The method: repo, hash, assemble, pin, test

Treat every prompt change like a code change:

1. Repo the source. One prompt file per role (system, task, guardrail) in version control. No dashboard-only edits; the dashboard deploys a hash, never hand text.
2. Hash the build. Log the exact assembled input (template + retrieved docs + history + parameters) with a content hash per run. The hash decides identity; prose resemblance does not.
3. Diff versions. Every behavior change starts with diff(prompt@v_n, prompt@v_n+1) plus the environment pin (model identifier, index snapshot, seed/parameters). If either side is missing, the first act is reconstruction, not diagnosis.
4. Pin a fixture suite. A small set of inputs with recorded contexts and expected properties (refusal, citation presence, exact reference strings). Run each fixture ≥3 times; nondeterministic generation gets distributions, not single samples.
5. Gate edits on the suite. A prompt edit ships only when the suite passes at the pre-declared threshold. A “better sounding” answer that breaks a fixture is a regression, full stop.

    flowchart TD
    R["repo + hash every prompt version; reconstruct missing ones as UNKNOWN-fidelity"] --> D["diff(v_n, v_n+1) + pin the environment: model id, index snapshot, seed / params"]
    D --> A["re-assemble the failing input under each version; log the build hash before reading output"]
    A --> S["run the pinned fixture suite x3 per version, all else fixed"]
    S --> Q{"which does the failure follow?"}
    Q -->|"the prompt hash, environment fixed"| H1["H1 prompt regression — revert / reword / restore the guardrail line"]
    Q -->|"the environment pin, prompt hash fixed"| H2["H2 environment drift — route to retrieval / assembly probes (Ch32-33)"]
    Q -->|"no version passes determinably"| H3["H3 suite too weak — harden fixtures before any edit"]
    H1 --> G["gate: deploy only a hash that passed the suite; dashboard becomes read-only"]
  

PROMPT PROGRAM RECORD (frozen per run):
prompt hash: sys@9c2e task@41ab guard@07f0 | assembled input hash: b3:77d1
model/pin: <identifier as logged> | index snapshot: idx-2026-08-14 | seed/params: <as logged>
retrieved: [doc-12 hash a91f, doc-07 hash 44c0] | sent context: 11,940 bytes (hash c55e)
output hash: e012 | fixtures: 12/12 pass (x3 trials) | UNKNOWN: none open
RULE: the hash decides what ran. Memory of what "should" be deployed decides nothing.

OBSERVATION (constructed illustration, not a measured run): prompt hash sys@9c2e with assembled hash b3:77d1 passes 12/12 fixtures across three trials; the dashboard edit produces sys@9c2f, assembled hash b3:81aa, and 10/12 with the same index snapshot. UPDATED BELIEF: H1 supported for this instance (prompt diff correlates with the two fixture failures under a fixed environment); H2 exonerated here (index snapshot unchanged); H3 retired going forward (a suite now exists). No universal causality claimed.

No paraphrase of the prompt, no confidence statement, no agreement across two chat retries, and no downstream symptom (“customers seem fine”) substitutes for hashes, diffs, and fixture counts.

Example: the one-sentence edit, convicted by diff and suite

The refund bot’s ticket holds a pasted “old prompt” and the dashboard holds the new text. The engineer repos both, hashes both, and reconstructs assembly for the failing input:

# prompt-as-program: identity and blame (no re-running yet)
old = load_prompt("prompts/system@v14.md")  # OBSERVATION: hash sys@9c2e
new = load_prompt("prompts/system@v15.md")  # OBSERVATION: hash sys@9c2f
print(unified_diff(old.text, new.text))  # MEASUREMENT: one added sentence + one deleted guardrail line
# Re-assemble the failing input under both versions, fixed index snapshot:
for ver in (old, new):
    bundle = assemble(ver, retrieved=frozen_docs, history=frozen_history)
    log(bundle.hash, ver.hash)  # build hash recorded before any output is read
# Run the 12-fixture suite x3 per version. Predictions pre-written per hypothesis.

In the constructed case the diff shows the added “be concise” sentence and a silently deleted “cite only reference numbers present in context” guardrail — the real break. The suite confirms: v14 passes 12/12, v15 fails exactly the two citation fixtures. The fix is a revert of the guardrail line, shipped as v16 with the suite green. The dashboard is then locked to deploying hashes; hand edits stop being possible.

Second artifact: the deploy-from-hash gate

Versioning without enforcement decays back to folklore within a sprint, so the chapter’s second artifact is procedural: nothing reaches production except a hash that passed the suite. The migration is deliberately boring:

1. Freeze the current dashboard text as v0. Export, hash, commit. Mark fidelity UNKNOWN if no prior version survives — v0 is a baseline, not a verified good.
2. Build the minimal suite first (5 fixtures suffice). Inputs with frozen contexts and checkable properties: exact reference strings, refusal presence, citation hooks. Run ×3; record the v0 score as MEASUREMENT, not verdict.
3. Flip the direction. Dashboard becomes read-only display of the deployed hash; edits happen in the repo and deploy by hash after a green suite. The first reverted bad deploy (red suite blocks ship) teaches the discipline faster than any memo.
4. Flag guardrail lines in review. Any diff touching a line tagged GUARDRAIL requires the full suite (not a single manual retry) before merge. Conciseness edits are the classic guardrail killers — Chapters 31 and 34 will show why at the word level.

DEPLOY RECORD (constructed illustration):
deployed: sys@9c2e+task@41ab+guard@07f0 | suite 12/12 x3 | by ___ at ___
blocked: sys@9c2f (10/12, citation fixtures red) | action: REVERT, no override path
RULE: a red suite blocks the ship even when the prose "reads better." Taste never overrides count.

OBSERVATION (constructed illustration): after the gate flips, two “urgent wording tweaks” are blocked in one week, each red on citation fixtures; both authors confirm on re-read that the tweak deleted a constraint. UPDATED BELIEF: process constraint supported as prevention for this team-instance; no claim that gating improves wording quality in general. Prevention is about blocking regressions, not producing eloquence.

Research lineage: “programming, not prompting”

The chapter’s discipline has a compiled form. DSPy’s premise is exactly this chapter’s: hard-coded prompt templates are “lengthy strings discovered via trial and error,” and the fix is to treat the LM call as a program — a declarative module with a typed signature, assembled and optimized by a compiler against a metric, rather than hand-edited prose (Khattab et al., 2024). In a DSPy pipeline the prompt text is a build artifact, not source — which makes “hash the build, not the source” the natural identity rule, and makes the fixture suite the compiler’s objective. DSPy is one of a large family of automatic prompt-optimization methods — OPRO, APE, ProTeGi, EvoPrompt, and TextGrad among them, now numerous enough to warrant a systematic survey (Ramnath et al., 2025) — that differ in whether they tune the instruction, the examples, or the pipeline structure. Hand-authored prompts still dominate production practice, and the point is not that a team must adopt an optimizer. It is that the repo / hash / assemble / diff / fixture-gate discipline is orthogonal to that choice: it makes any prompt, hand-written or compiler-generated, safe to deploy and possible to debug, and every optimizer already presupposes exactly the pinned fixture suite this chapter builds.

Single-prompt verdicts are unreliable, so the suite tests a family. Mizrahi and colleagues’ result means a fixture suite built on one phrasing per input can mistake phrasing sensitivity for a regression. Each fixture should carry two or three paraphrases of its instruction, and a v-to-v drop that appears on one paraphrase but not its siblings is flagged as sensitivity, not convicted as a regression (Mizrahi et al., 2024).

Guardrail lines are verifiable constraints. The “cite only reference numbers present in context” line the conciseness edit deleted is exactly the kind of instruction that instruction-following benchmarks like IFEval make checkable — a predicate on the output that a fixture can test without model judgment. Tag guardrail lines, and give each one a fixture that fails loudly when the constraint is dropped.

Lab 30: prompt-version bisection with pre-written predictions (proposed)

PROPOSED, not executed: no author-measured results are reported. The evidence this chapter requires is the reader’s own repo and suite.

Setup. Take one prompt you own that has failed at least once. Repo two or more versions (reconstruct from history, tickets, or dashboard copies where needed; mark reconstructions as UNKNOWN-fidelity). Freeze the retrieval snapshot, model identifier, and parameters. Build a 5–12 item fixture set with expected properties checkable without model judgment (exact strings, refusal presence, citation hooks).

Task.

1. Before running, write H1/H2/H3 with distinct predicted signatures: H1: “failure follows the prompt hash across fixed environments”; H2: “failure follows the environment pin across a fixed prompt hash”; H3: “no version passes determinably — suite too weak to separate them.”
2. Run each prompt version × each fixture ≥3 times, all else fixed. Record OBSERVATION (hashes, per-trial pass/fail verbatim) and UPDATED BELIEF per hypothesis.
3. Ship nothing until one hash passes the pre-declared threshold.

Success criterion. A versioned prompt directory, per-run build hashes, and a suite table with three trials per cell. A dashboard screenshot or a single “looks better now” retry is explicitly not completion.

Companion tool: Prompt Program Checklist

What it accepts: prompt source files, version hashes, assembled-input logs with hashes, environment pins (model identifier, index snapshot, parameters), and fixture definitions with pass criteria. What it performs: it verifies every run maps to exactly one prompt hash plus one environment pin, diffs prompt versions byte-exactly, checks that fixtures ran the declared number of trials, and blocks any “fix” lacking a green suite on the shipped hash. What it can establish: whether a behavior change tracks a prompt version, an environment pin, or neither — for the examined fixtures only. What it cannot establish: prompt quality in general, fixture completeness, or future reliability. It never treats fluency, confidence, agreement across retries, single-run outcomes, scores, or downstream symptoms as diagnosis. How its output changes your next action: prompt-tracking failure routes to version repair (revert, reword, restore guardrails); environment-tracking failure routes to Chapters 32–33 pipeline probes; suite-too-weak routes to fixture hardening before any prompt edit.

Paper form, sufficient for this chapter:

Prompt: ___ (hash ___)  Env pin: model ___ index ___ params ___
Diff vs. last green: ___ lines (guardrails touched? y/n ___)
Fixtures: ___/___ pass ×3 trials (failures: ___)  VERDICT: ship / revert / harden suite
NEXT: ___

Where a software implementation does not yet exist in the reader’s stack, this record is the tool. Hash before hypothesizing.

Reusable procedure: promote every prompt to a program

1. Repo and hash — source files versioned; every run logs prompt and build hashes.
2. Diff first — version diff plus environment pin before any theory.
3. Assemble explicitly — log the full model input, not the template alone.
4. Fixture and repeat — pinned suite, ≥3 trials per cell, pre-written predictions.
5. Gate the ship — green suite on the shipped hash or no ship.

Failure modes

• Dashboard folklore. Editing live text with no version. No hash, no history, no diagnosis.
• Template-only review. Reading the system prompt while assembly (retrieval, history, glue) does the damage unseen.
• Criterion-free “improvement.” “Sounds better” with no suite. Taste is not a test.
• Multi-variable ships. Prompt, temperature, and index changed together. Attribution destroyed at the moment of repair.
• Single-sample verdicts. One green retry closing a prompt defect. Nondeterminism requires trials.
• Guardrail erosion. Small “conciseness” edits that silently delete constraints. Diffs catch what reading misses.
• Hash without pin. Versioning the prompt while the model and index float. A prompt hash plus an unpinned environment is half an identity.
• Suite rot. Fixtures that no longer match the task’s requirements, kept green by luck. Review the suite when the task changes, not just the prompt.

Limits, per contract: one checklist covers the examined prompt versions, fixtures, and environment pins; it does not certify prompt quality, does not transfer across tasks, and stays UNKNOWN where hashes or pins are missing.

References

• Omar Khattab, Arnav Singhvi, Paridhi Maheshwari, Zhiyuan Zhang, Keshav Santhanam, Sri Vardhamanan, Saiful Haq, Ashutosh Sharma, Thomas T. Joshi, Hanna Moazam, Heather Miller, Matei Zaharia, and Christopher Potts. DSPy: Compiling Declarative Language Model Calls into Self-Improving Pipelines. International Conference on Learning Representations (ICLR), 2024. https://arxiv.org/abs/2310.03714
• Kiran Ramnath, Kang Zhou, Sheng Guan, Soumya Smruti Mishra, Xuan Qi, Zhengyuan Shen, Shuai Wang, Sangmin Woo, Sullam Jeoung, Yawei Wang, Haozhu Wang, Han Ding, Yuzhe Lu, Zhichao Xu, Yun Zhou, Balasubramaniam Srinivasan, Qiaojing Yan, Yueyan Chen, Haibo Ding, Panpan Xu, and Lin Lee Cheong. A Systematic Survey of Automatic Prompt Optimization Techniques. Proceedings of the 2025 Conference on Empirical Methods in Natural Language Processing (EMNLP), 2025. https://arxiv.org/abs/2502.16923
• Moran Mizrahi, Guy Kaplan, Dan Malkin, Rotem Dror, Dafna Shahaf, and Gabriel Stanovsky. State of What Art? A Call for Multi-Prompt LLM Evaluation. Transactions of the Association for Computational Linguistics 12, 2024, pp. 933–949. https://doi.org/10.1162/tacl_a_00681
• Jeffrey Zhou, Tianjian Lu, Swaroop Mishra, Siddhartha Brahma, Sujoy Basu, Yi Luan, Denny Zhou, and Le Hou. Instruction-Following Evaluation for Large Language Models (IFEval). arXiv:2311.07911, 2023. https://arxiv.org/abs/2311.07911

Debugging Checklist

• Prompt sources versioned (hash per role, no dashboard-only text)?
• Every run logs the assembled-input hash plus environment pin?
• Version diff computed byte-exact before theorizing?
• Fixture suite pinned with measurable pass criteria (each fixture carries 2–3 instruction paraphrases)?
• Guardrail lines tagged, each with a verifiable-constraint fixture?
• v-to-v drop checked across paraphrase siblings (sensitivity vs. regression)?
• H1/H2/H3 predictions pre-written with distinct signatures?
• Each version × fixture run ≥3 times (all else fixed)?
• Dashboard read-only (deploys hashes, accepts no hand text)?
• Guardrail-line diffs flagged for full-suite review?
• No fluency, confidence, agreement, scores, single runs, or symptoms cited as verdict?

What This Chapter Established

• Prompt-as-program discipline: repo, hash, assemble, diff, fixture-gate — demonstrated on the constructed refund-bot regression, no measured runs claimed.
• The version-vs-environment separation (H1/H2) plus the suite-adequacy check (H3) as the entry gate for all Part VI debugging.
• Lab 30 as a proposed version-bisection record the reader executes; the Prompt Program Checklist contract (accepts/performs/can-establish/cannot-establish/next-action).
• The deploy-from-hash gate as the prevention artifact: read-only dashboard, guardrail-flagged review, blocked ships logged.
• What was NOT proved: any prompt-writing rule, any general reliability claim, or any certification of a prompt family. One discipline introduced; nothing universal.
• Research grounding: “prompts as programs” is the DSPy thesis (compiled, parameterized modules; prompt text as build artifact — Khattab et al.), and DSPy is one instantiation of a broad automatic prompt-optimization field (OPRO, APE, ProTeGi, EvoPrompt, TextGrad — Ramnath et al.) whose shared substrate is the versioning-and-testing discipline this chapter builds; semantically equivalent phrasings swing performance across 6.5M instances (Mizrahi et al.), so byte-identity matters and fixtures test a paraphrase family; guardrail lines are verifiable output constraints (IFEval-style) and each deserves a fixture that fails when the constraint is dropped.
• Position in the arc: Chapter 29 timed the trajectory; this chapter versions the instructions that drive it. Versions frozen, history queryable.

Next

Versioning tells you which prompt ran. It does not tell you which words inside it matter — the typical production prompt carries months of appended instructions, examples, and guardrails, any one of which may be load-bearing or dead weight. Chapter 31, “Minimize the Prompt,” applies removal-until-break to prompt content itself; what the minimal failing prompt reveals is its chapter’s to establish, not this one’s.