Replay Graph And Clusters

replay graph and replay cluster are the replay commands you reach for after the first-minute packet, replay front door, summary, or timeline stop being enough.

Use replay packet when one artifact root failed and you need the durable run-summary.json / run-summary.md handoff before deeper triage.
Use replay open after the packet when a human wants the replay front door with the primary failure, best next action, and the longer follow-up command set.
Use replay capsule when you want the compact failure manifest and shareable summary for that same bundle.
Use replay graph when you need a stable semantic model over one artifact root: failures, actions, selectors, telemetry, artifacts, and generated scenario-draft provenance.
Use replay cluster when the question is no longer “what failed here” but “is this the same failure pattern as the last runs?”

Commands

luotsi replay packet --artifacts ./artifacts/my-run
luotsi replay packet --artifacts ./artifacts/my-run --check
luotsi replay open --artifacts ./artifacts/my-run --dry-run
luotsi replay graph --artifacts ./artifacts/my-run
luotsi replay graph --artifacts ./artifacts/my-run --write-json --write-markdown
luotsi replay cluster --artifacts ./artifacts/ci-runs --write-json --write-markdown

Replay graph contract

luotsi replay graph emits luotsi-replay-graph.v1, a stable node-and-edge view over replay artifacts.

The top-level fields that matter most are:

Field	Meaning
`schema`	Always `luotsi-replay-graph.v1`
`artifact_root`	Root directory the graph was built from
`query`	Applied graph filters such as failure-only, node kind, edge kind, action, selector, text, evidence, fact, node neighborhood, and limit
`node_count`, `edge_count`	Returned graph size after filters
`total_node_count`, `total_edge_count`	Full graph size before filters
`matched_node_count`, `matched_edge_count`	Query match size before `--limit` is applied
`agent_summary`	Compact “what failed”, “what changed”, and “what can I run next” summary; commands keep packet/check first, then include `replay open` for browser-free replay navigation
`node_kinds`, `edge_kinds`	Counts by node kind and edge kind for quick triage
`insights`, `actions`, `evidence`, `facts`, `causal_chains`, `hypotheses`	Promoted semantic summaries for agents and reviewers
`json_path`, `markdown_path`	Paths written only when `--write-json` or `--write-markdown` is requested
`nodes`, `edges`	Returned graph payload

Use graph filters when you already know what you need: --failed, --node-kind, --edge-kind, --action, --selector, --contains, --insight, --severity, --evidence, --fact, or --node <id> --depth <n>. The default action list starts with replay packet and replay packet --check, then routes to replay open, capsule, artifact browsing, scrub, streaming JSONL, and narrower graph queries.

Node kinds

The graph promotes raw replay evidence into stable node kinds:

Kind	Meaning
`session`	One `session-replay.json` session
`event`	One normalized timeline event from `session-timeline.jsonl`
`failure`	Failure-relevant timeline event or terminal failure
`failure_capsule`	`failure-capsule.json` summary node
`scenario`	Scenario entry from a failure capsule
`artifact`	Screenshot, logcat, hierarchy, report, or metadata file linked to a scenario
`action`	Promoted action such as `waitVisible`, `tap_text`, or `take_screenshot`
`selector`	Promoted text or structured element selector
`screen_state`	Screen or screenshot observation
`telemetry_signal`	Semantic telemetry signal emitted by the app or observed by Luotsi
`scenario_draft`	Generated scenario draft summary
`generated_step`	Step generated by `replay scenario-draft`
`draft_source`	Source family for generated steps and draft normalizations, such as inspect command or telemetry
`draft_normalization`	Stabilization or cleanup normalization applied while generating a draft

Scenario-draft generated_step and draft_normalization nodes keep audit fields when the draft summary contains them: source_path, sequence, timestamp, and source_command. Use those fields to jump from graph context back to the exact replay timeline event that produced a step or normalization.

Edge kinds

Edges describe how those promoted nodes relate to one another:

Kind	Meaning
`next`	Timeline ordering within one source timeline file
`transitions_to`	Semantic timeline transition with category and optional elapsed time
`indicates`	Event points to a failure node
`has_capsule`	Session has a failure capsule
`contains`	Capsule contains a scenario
`has_artifact`	Scenario links to an artifact
`describes_action`	Event describes an action node
`mentions_selector`	Event mentions a selector node
`observes_screen`	Event observes a screen or screenshot state
`observes_telemetry`	Event observes a semantic telemetry signal
`generates_step`	Scenario draft generates a step
`derived_from`	Generated step or draft normalization came from a source event family
`uses_source`	Scenario draft uses a source family
`applies_normalization`	Scenario draft applied a normalization

How to move through one bundle

These commands usually answer the next question fastest:

replay open when you want the canonical front door, primary failure, and suggested next commands
replay capsule when you want the compact bundle summary once you already know this is the run you need to share or reopen in detail
replay timeline --failures when you need the exact failure-relevant event window
replay scrub --failures --context 3 when you want the local before/focus/after view around one failure
replay search --contains <text> when you are hunting a selector, message, or other text evidence across the artifact root
replay graph when you want promoted nodes, edges, facts, causal chains, hypotheses, and evidence for that same root

Replay cluster contract

luotsi replay cluster groups failed replay sessions by normalized failure shape.

That makes it the right command when:

a CI directory contains multiple failing artifact roots
you need grouped failure shapes instead of one-run detail
you want the best representative bundle plus the next replay/search commands for that cluster

Use it as a triage reducer, not as a replacement for replay packet, replay open, replay capsule, or replay graph. In practice the flow is:

Run replay cluster on a directory of replayable artifact roots.
Pick the cluster that matches the failure class you care about.
Write and check the representative bundle’s replay packet, then follow the suggested replay commands into replay open, replay capsule, replay graph, replay scrub, or replay search.

Practical triage loop

luotsi replay packet --artifacts ./artifacts/failing-run
luotsi replay packet --artifacts ./artifacts/failing-run --check
luotsi replay open --artifacts ./artifacts/failing-run --dry-run
luotsi replay capsule --artifacts ./artifacts/failing-run --write-readme --write-json
luotsi replay timeline --artifacts ./artifacts/failing-run --failures --context 3 --write-markdown
luotsi replay graph --artifacts ./artifacts/failing-run --write-markdown
luotsi replay cluster --artifacts ./artifacts/ci-runs --write-markdown

Use replay graph when you are still reasoning within one bundle. Use replay cluster when you are deciding whether the current failure belongs to a larger recurring class.