Skip to main content
An explanation is a versioned evidence report, not a prose guess at what the adapter probably did. Start with the report identity and lifecycle, follow decision events to their supporting facts, and keep observed, derived and hypothetical claims separate. This guide uses one customer-facing synthetic report in all three formats. It is adapted from the renderer’s evidence model so the examples use public terminology; it is not a byte-for-byte golden renderer fixture or a measurement from a production deployment. Every tab carries the same report ID, revision, five event IDs and six fact IDs. Agent and JSON payloads abbreviate repetitive fields, but they do not omit identities from the decision chain.

​
Read the report envelope first

Before interpreting an event, record:
The Human rendering prioritizes the decision path. It still includes stable event and fact IDs so a conclusion can be checked against the Agent or JSON rendering.

​
Follow events to evidence

Events are occurrences captured inside a named scope. Facts are assertions whose provenance describes how the adapter knows them. They serve different purposes. In the fixture:
  1. event-decision says the admission decision selected reject.
  2. Its evidence field points to fact-constraint.
  3. fact-constraint is Derived and points to fact-instance as support.
  4. fact-instance is Observed from snapshot ec2-install@lsn-4412, with row version row-v9 and an observation time.
  5. The bounded conclusion is that this evaluation found an instance dependency in that snapshot and selected rejection.
Do not strengthen that conclusion into “the VPC always has a live dependency” or “Azure refused deletion.” No Azure deletion was attempted in Explain mode, and the report does not establish later state.

​
Distinguish evidence bases

An effective-configuration fact can show which mode, backend, tuning choice or revision was selected. A compatibility-difference fact can describe a known semantic difference. Neither becomes an observed provider effect unless the report names that observation.

​
Planned, attempted and observed effects

Use these words precisely:
  • Planned: the adapter selected an operation, mapping or target field.
  • Attempted: an execution path sent or began target work.
  • Observed: the adapter received or read a named result.
An attempted upload with a lost response is not an observed failure and not proof of success. An observed provider acceptance is not necessarily final convergence. A planned deletion in Explain mode is not a deletion attempt. For asynchronous operations, inspect the latest revision and the operation-specific status observation. A provider-assigned ID may be unavailable in an early revision, so later events should continue with the exact identity once known rather than guessing from a reused name.

​
Treat sequence as scoped capture order

The Human fixture explicitly says its timeline is “in capture order (not a cross-service clock).” A report sequence is useful for stable rendering and local reasoning. It does not prove global wall-clock order between independent producers. Use stronger causal evidence when available:
  • causedBy relationships;
  • parent and child spans;
  • intent and operation references;
  • producer-local sequence values;
  • facts that explicitly name their supporting facts or events.
Adjacent rows without those links may simply have been captured in that order.

​
Read partial and incomplete reports

A report can be readable before it is sealed. Record the revision and lifecycle on every read. A later revision may add target observations, retries, child work or limitations. When a report is partial:
  • do not acknowledge it as though it were final;
  • poll the same report ID rather than replaying the origin operation;
  • retain the native result separately;
  • compare revisions monotonically and ignore an older snapshot that arrives after a newer one;
  • treat missing facts as unknown, not negative evidence.
CompleteForInstrumentedScope still has a boundary: it describes capture within instrumented scope. A listed limitation further narrows interpretation. An unsupported fact type means that fact is unavailable to this reader even if other parts of the report are usable.

​
Authorization denial does not have one universal shape

Report availability depends on the service path: The illustrative fixture contains an authorization fact with outcome Allow. The request is rejected by the dependency constraint. Do not use it as an authorization-denial example.

​
Choose the next action from evidence

For this fixture, the next safe action is to inspect the named instance dependency and its current relationship to the VPC. It is not to issue the deletion again. If the observation is stale or unavailable, gather a current non-mutating observation first. For another report:
  1. Identify the decision or failed step.
  2. Follow its evidence IDs.
  3. Check every fact’s basis, source, version and limitations.
  4. State what the evidence establishes and what remains unknown.
  5. Choose the smallest test that resolves one unknown without replaying an ambiguous mutation.
See Following Asynchronous Explanations for evolving revisions and Diagnostic Response Headers for authorized reads and acknowledgment.