Skip to main contentSkip to footer
Browse principles
Principle 4trust

Apply progressive disclosure to system agency

Provide the minimum information necessary by default, while enabling users to inspect additional detail when confidence, understanding, or intervention is required.

Key Facts

Cluster
trust
Primary risk
The system is experienced either as an opaque black box or as an over-exposed technical log.
Related examples
6 library examples
Doctrine library
Internal doctrine reference
Why does this principle matter?

Different users, and the same user in different contexts, require different levels of transparency. The default experience should remain clear and efficient, while deeper inspection should remain available when justified.

Prioritise intent, status, and outcome in the primary view.
Allow expansion into actions taken, supporting evidence, decision logic, or tool usage.
Present explanation at an appropriate level of abstraction.
Distinguish clearly between summary information and detailed inspection.
What failure does this principle prevent?

The system is experienced either as an opaque black box or as an over-exposed technical log.

AI as interface embellishment: A conventional product is given a text input and labelled intelligent, without any meaningful change in operational model.
Simulated autonomy: The system appears autonomous in language or presentation but cannot act with meaningful independence.
Opaque execution: Work occurs in the background without adequate status, accountability, or recoverability.
How do I apply this in practice?

The implementation library contains inspectable, runnable examples that show this principle applied in real agentic product code. Study the source paths, library choices, and runtime assumptions — not just the pattern name.

Implementation example

Get Single Page

Runnable example (intermediate) for script using docling, openai. (script · intermediate)

Inspect implementation

Implementation example

Web Search

Runnable example (intermediate) for script using docling, openai. (script · intermediate)

Inspect implementation

Implementation example

Search Handbook

Runnable example (intermediate) for script using docling, openai. (script · intermediate)

Inspect implementation

Related examples