Guides
Create Branches
Turn one hypothesis into one branch and one or more targeted interventions.
Branch creation is the moment a possible cause becomes a testable claim. Keep branches narrow.
1. Select A Checkpoint
npx isplay runs checkpoints <runId>Choose the earliest checkpoint after irrelevant setup and before the suspected cause.
2. Create The Branch
npx isplay branch create \
--from <runId> \
--checkpoint <checkpointId> \
--project "$ISPLAY_PROJECT_ID" \
--name "mask risky policy clause"The branch inherits or stores replay policy. You can override policy when you run replay.
3. Add The Intervention
npx isplay branch intervene <branchId> \
--project "$ISPLAY_PROJECT_ID" \
--kind prompt_clause_mask \
--target-context <contextItemId> \
--description "Remove the clause that permits auto-refunds"For JSON patches:
npx isplay branch intervene <branchId> \
--project "$ISPLAY_PROJECT_ID" \
--kind state_patch \
--target-context-path state.claim.status \
--patch patch.json \
--description "Set claim status to approved before decision"Target Selection
| Target kind | Prefer when |
|---|---|
--target-context | You are testing a prompt, retrieval, memory, state, schema, or setting item. |
--target-event | You are testing a specific observed event. |
--target-ref or --target | You want the projection record linked to an event. |
--target-type | You want a specific event type. |
--target-tool | You are patching any call to one tool. |
--target-model-call | You are patching one model boundary. |
--target-artifact | You are patching by artifact identity. |
--target-context-path | You are patching a named context path. |
--json-pointer | You know the exact JSON path inside the matched event data. |
Review Before Replay
npx isplay branch get <branchId>
npx isplay branch interventions <branchId>If the branch contains multiple unrelated interventions, split it before replay.