Disclosure Without Overwhelm

Showing everything is not transparency. It is a way of making the user responsible for checking work they never asked to supervise.

Falk Gottlob7 min read

The short version

  • How much AI reasoning to show is the wrong question, and it is the one most teams argue about. The real decision is which of five disclosure levels is the default for which reader in which moment, and what single action moves them up a rung. Showing everything is not transparency, it is a way of making the user responsible for checking work they never asked to supervise. There are four specific cases where more disclosure costs trust rather than building it, and the test that separates a useful disclosure from decoration is whether it changes what a reasonable reader would do next. The ladder, the defaults table, and the escalation triggers are in the template at the end.
  • Every AI product I look at is sitting on one of two failures.
  • One is a confident paragraph with nothing behind it. No source, no provenance, no hint of where the claim came from, delivered in the same voice whether the system checked forty documents or guessed.
  • Then there is the overcorrection. Forty visible steps of reasoning, a retrieval log, a little animation of the model thinking, all of it above the answer the person actually came for. Somebody on that team said the word transparency in a review and nobody argued, because arguing against transparency sounds like arguing for hiding things.
  • Both are the same mistake. Neither team decided what the reader was supposed to do with the information.

Five levels, and the default is the decision

Level 0 is the answer alone. Level 1 adds provenance, what it drew from, one line and one action to open. Level 2 shows the shape of the reasoning, two or three steps in the user's language rather than a transcript. Level 3 is the full chain on request, every retrieval and intermediate decision, available in one action and never the default. Level 4 is the raw trace: prompts, tool calls, tokens, timings, model versions.

Drawing that ladder takes an afternoon. Every team gets there within a week of shipping.

Where the design work actually sits is two columns. Where a given reader starts, and what sits one action away. A first-time user starts at provenance and can reach the reasoning shape. A routine user on a low-stakes task can sit at 0 or 1. A routine user on a high-stakes task starts at 1 with the full chain one action away. A reviewer starts at 2. An admin or auditor starts at 2 with the raw trace reachable. Support and engineering live at 3.

Two things that table encodes get argued every single time, so I will say them out loud.

Level 0 is legitimate. Reserve it for outputs the user can check at a glance or that cost nothing when wrong, and then use it without guilt. A product that explains itself constantly is exhausting, and the exhaustion is not neutral. It teaches people to skip the explanation, and once they have learned that habit, the one explanation that mattered goes past them with all the others.

Level 4 is never a default for anyone. It belongs in a debugging tool. The moment a raw trace becomes a default view, somebody has confused an internal surface with a product decision.

The four cases where more costs you

Teams are usually surprised by this list, which is why it gets to be a list.

When the reasoning reveals the method is thinner than the confident tone implied. A three-sentence answer delivered with authority, whose trace shows it looked at exactly one document, reads worse than the answer would have alone. Fix the tone rather than hiding the trace, which is a conversation for The Shape of Uncertainty.

When the volume implies rigor that is not there. Forty steps feels thorough and is frequently just verbose. Users read length as effort, which is exactly the wrong signal to send about a system whose length costs it nothing.

When it exposes the user's own data back to them in a way they did not expect. "I read your last two hundred messages to answer this" can be true, accurate, and a serious mistake to say out loud in that moment.

When the reader cannot evaluate it. Showing a chain of reasoning to somebody with no way to judge it produces anxiety with extra steps. They now know there was a process, they cannot tell whether it was a good one, and the only thing you have given them is a new thing to worry about.

Which gives you a test short enough to use in a review. Does this disclosure change what a reasonable reader would do next? If it does not, it is decoration, and decoration in this position is not free. It spends the attention that the disclosures which do matter are going to need.

Escalation is where the value is

Skip past the ladder in the template. Go to the page listing the conditions under which the product raises the default level on its own, without being asked. That page is where the value sits.

Raise a rung when at least one of these is true. Confidence is below your stated floor. The action is in an irreversible class, in the sense described in Undo Is a Design Primitive. The output contradicts something the user said or the system said earlier. The user reversed a similar output recently. Money, permissions, external communication, or deletion are involved.

Write your own list, then put it in the eval set so it stays true through model changes. A disclosure ladder that only moves when the user climbs it is a ladder nobody climbs on the day it matters, because the day it matters is exactly the day they are moving fast and trusting the product.

Escalation is also what makes low defaults defensible. You can justify Level 0 on routine output precisely because the system will raise itself when the situation changes. Without triggers, every argument about defaults collapses into a fight between the person who wants a clean interface and the person who wants coverage, and the person with the scarier hypothetical usually wins.

Three mechanics decide whether any of this survives contact with the actual interface.

Moving up a rung is one action, never two. Reasoning that takes three clicks to reach does not exist, whatever the design file says.

Moving up is never destructive. Opening the trace does not lose the answer, close the panel, or reset the input. Sounds obvious. It breaks constantly, usually because the trace was built as a separate view by a separate team.

And the rung is remembered per user, not per session. Somebody who opens the reasoning every single time is telling you what their default should be, and re-collapsing it on every visit is a small daily insult that adds up to a product that does not seem to be paying attention.

None of this is exotic. It is the same discipline as instrumenting anything else you cannot see directly, which is the argument in Ship With Observability, pointed at the user's view rather than yours.

This week: pick the surface where your product currently shows the most reasoning. Ask three people who use it what they actually do with that information. If the answer is that they skip it, you are spending attention you will need later, and dropping that surface a rung is the highest-value edit available to you.

The five levels, the defaults table by reader, the four failure cases, and a blank escalation trigger list are in The Disclosure Ladder. The short version for a team that just wants the rule is How much of an AI's reasoning should you show the user?


Chapter 8 of a series on the design operating model. Next: what waiting does to a relationship when the user cannot tell whether anything is happening.

Share this post

Take the template

Disclosure ladder, five levels

Download

Frequently asked

How much of an AI's reasoning should you show the user?+

As much as changes what a reasonable reader would do next, and no more. That is the test. Use a five-level ladder, from the answer alone up to the raw trace, and decide which rung is the default for which reader in which moment. The design decision is never how much to show in general, it is what the default is and what single action moves someone up a rung.

Is showing the AI's chain of thought always good for trust?+

No, and there are four cases where it actively costs you. When the trace reveals the method is thinner than the confident tone implied. When the sheer volume of steps implies rigor that is not there. When it exposes the user's own data back to them in a way they did not expect. And when the reader has no way to evaluate what they are looking at, which produces anxiety rather than confidence.

Is it ever acceptable to show no reasoning at all?+

Yes. Level 0, the answer by itself, is legitimate for outputs the user can check at a glance or that cost nothing when they are wrong. A product that shows its reasoning for everything is exhausting, and the exhaustion is not neutral: it teaches people to stop reading, which is worse than never having shown them. Save the attention for the disclosures that need it.

When should an AI product show more reasoning than the user asked for?+

When at least one escalation trigger fires: confidence is below your stated floor, the action falls in an irreversible class, the output contradicts something the user or the system said earlier, the user reversed a similar output recently, or money, permissions, external communication, or deletion are involved. Write your triggers down and put them in the eval set. A ladder that only moves when the user climbs it is a ladder nobody climbs on the day it matters.

What are the rules for how disclosure works in the interface?+

Three that hold across products. Moving up a rung is always one action, never two, because reasoning that takes three clicks to reach does not exist. Moving up is never destructive, so opening the trace does not lose the answer or reset the panel. And the rung is remembered per user rather than per session, because someone who always opens the reasoning is telling you their default.

Should engineers and end users see the same level of AI explanation?+

No. Default by reader and by stakes. A first-time user starts at provenance, a reviewer at the shape of the reasoning, an admin or auditor at the shape with the full chain one action away. Support and engineering live a rung higher still. Level 4, the raw trace of prompts, tool calls, and timings, is never a default for anyone, because it is a debugging tool rather than an interface.

Related reading

Chapters and essays on the same thread, across both handbooks.

The short answers