Worked Example - Dialog Interface (Intent Clarification)
Companion to Chapter 8. A full intent-clarification dialog where the user's literal request and underlying need diverge. Annotations call out the AI-side disciplines the chapter names: intent modeling, faithfulness signals, assumption surfacing, and dialog repair.
Context
A senior engineer asks an AI partner to "make our error logs more useful." The literal request is small (probably a logging format change). The underlying need (uncovered through the dialog) is structural: the team cannot triage incidents because the log volume is unfilterable. Solving the literal request would have wasted half a day on a fix the team does not actually want.
The transcript
Can you make our error logs more useful?
Happy to. "More useful" can mean a few different things - could you tell me which of these is the closest fit? (1) Better structured for parsing - adding fields, switching to JSON. (2) Easier to filter - too much noise from low-priority warnings. (3) More context per entry - request IDs, user IDs, stack traces with source maps. (4) Different destinations - separating critical errors from debug logs. If it's a mix, just say so and we'll do the dominant one first.
Intent modeling: rather than guess, the partner offers four plausible framings and asks the user to pick. Each framing is concrete (so the user can recognize "yes, that one"), and the partner names a default for the mixed case so the user does not have to fully decompose the answer.
Mostly (2). On-call gets buried in noise during incidents.
That helps. Two more sharp questions before I propose a change. (a) When you say "buried in noise," is it that the warnings outnumber the errors at the wrong ratio (volume problem), or that the warnings are correctly logged but indistinguishable from errors at a glance (visual / parsing problem)? (b) Is this about during the incident (filtering live) or after the incident (filtering in the post-mortem search)? Those need different fixes.
Assumption surfacing: the partner notices two assumptions hidden in "buried in noise" and names them. Either assumption could be wrong, and the right fix depends on which one is in play. One sharp pair of questions beats five generic ones.
(a) is the visual one - warnings and errors look identical in the dashboard. (b) is mostly during the incident.
Got it - the real problem is dashboard discriminability during live incidents, not the log format itself. That reframes the work. Two paths from here:
Path A - cheap and reversible: add a severity-based color and prefix to log entries in the dashboard view layer, no changes to the log producers. About an hour of work, covers the dominant case.
Path B - broader: introduce log levels at the producer (if you don't already have them) and route warnings to a separate dashboard pane. Half a day; pays off long-term but moves more code.
I'd suggest Path A this week and revisit Path B if the team still struggles during the next incident. Want me to start on A, or would you rather see the diff for both first?
Dialog repair + materiality calibration: the partner explicitly reframes the problem ("the real problem is dashboard discriminability") and proposes two paths sized to different stakes. The recommendation is named, the rationale is named, and the user is offered control over whether to proceed or review first. The original literal request ("make logs more useful") is not what is being done - the partner has surfaced the reframe and gotten user buy-in before changing direction.
Start on A. We can talk about B at the retro.
On it. I'll come back with the diff before merging anything, and I'll keep B written up so the retro discussion has a concrete starting point.
Faithfulness signal + handoff: the partner commits to a review gate before merge (verifiable stop, even at the dialog layer) and explicitly preserves the deferred Path B for the retro - debt-accumulation primitive at the dialog level.
What this trace shows
- The partner did not implement the literal request; the partner discovered that the literal request was a symptom and surfaced the cause.
- The dialog used three turns to refine the problem before any code was proposed. Each turn was concrete enough that the user could answer in a sentence.
- The partner offered the user control at every reframe (which framing fits? which path? proceed or review first?). The architecture's job is to support calibration; the user makes the calibration call.
What would have failed without the discipline
Without intent modeling, the partner would have implemented a JSON log format change - the most common literal answer to "more useful logs." Half a day of wasted work; the on-call experience would not have changed at all because the dashboard discriminability problem would still be there.
Practitioner templates
The dialog-layer prompts page hosts the intent-clarification, assumption-surfacing, and dialog-repair templates this trace used.