Guides

Practical, task-oriented capture, replay, fixture, experiment, integration, and operations workflows.

Guides answer "how do I do this specific thing?" Start here after the quickstart when you already know the outcome you want: instrument an agent, choose checkpoints, redact captured data, replay a counterfactual, resolve fixtures, run a hypothesis batch, or write an RCA report.

Capture

Instrument runs, context, model calls, tools, artifacts, checkpoints, and side effects.

SDK instrumentation

Use @isplay/sdk directly when you own the execution path.

Custom framework instrumentation

Use adapter-kit patterns for frameworks without a dedicated adapter.

Checkpoint strategy

Place checkpoints so branches are meaningful and replayable.

Context annotation

Capture prompts, retrieval, memory, state, tool schemas, and settings as searchable context.

Tool side effects

Classify tool risk before replay and fixture work.

Redaction

Capture useful evidence without leaking private fields.

Replay

Create branches, interventions, replay jobs, diffs, metrics, and effects.

Create branches

Turn one hypothesis into one targeted intervention.

Fixtures

Resolve missing tool outputs while preserving provenance and safety.

Experiments

Create hypothesis batches, run trials, read statistics, and rank effects.

Interpret output

Read diffs, metrics, comparability, effects, and low-N caveats.

RCA reports

Write bounded reports that separate facts, tested changes, and uncertainty.

Agent analysis

Use the isplay-analysis skill to run bounded evidence investigations.

Build an adapter

Add capture and replay support for a new framework or runtime.

Production operations

Run isplay with external Postgres, durable artifacts, and explicit safety policies.

Default RCA Loop

Confirm ISPLAY_API_URL, ISPLAY_PROJECT_ID, and the base runId.

Run isplay discover run <runId> and read the catalog, context summary, and context items.

List checkpoints and choose the earliest checkpoint that still contains enough state to replay the suspected decision.

Write a factual baseline narrative: task, prompts, settings, tools, retrieval, memory, key tool outputs, and final behavior.

Convert each possible cause into one intervention. Avoid broad bundles.

Replay or run a hypothesis batch with recorded-only model policy and pause-for-fixture tool policy.

Resolve fixture requirements only with explicit provenance and scope.

Report first divergence, metrics, effects, fixture dependency, comparability, validity labels, and next experiments.

Choosing A Workflow

Situation	Use	Why
You have no run yet	Capture workflow	A replay investigation is only as good as the baseline evidence.
You own the app code	SDK or adapter-kit guide	Capture can be precise and low-noise.
You have one suspected cause	Branch and replay	Fastest way to isolate one controlled change.
Replay paused	Fixture workflow	Tool side effects stay explicit and auditable.
You have several possible causes	Experiment workflow	One batch can materialize branches, trials, statistics, and ranked effects.
You want the agent to drive	Agent analysis workflow	The skill enforces discovery, hypothesis discipline, and bounded reporting.
You need a final RCA	Report guide	Gives the evidence wording and structure.

Reporting Rule

Evidence wording

Use "observed" for base trace facts, "under replay" for recorded replay results, "under fixture" for analyst/simulator/AI fixture results, and "unsupported" when evidence is missing. Avoid saying a cause is proven.