The stage-snapshot-writer Skill — Surviving a Closed Terminal
How Datarim's stage-snapshot-writer skill persists the last operator-visible response to disk after every pipeline step, so the next command can resume from the exact checkpoint without re-reading the session history.
A long pipeline step finishes, the operator runs /clear to free context, and the next command needs to know where things stand. Without a written record, the agent has to reconstruct state from scratch. The stage-snapshot-writer skill solves this with a single file per task, overwritten at the end of each pipeline stage.
Every /dr-* command that emits a CTA block writes its final operator-visible response to datarim/snapshots/{TASK-ID}.snapshot.md as its terminal step. The file is the primary context source for /dr-next after a session reset. Overwrite semantics mean a second call for the same stage always produces a fresh file — there is no accumulation of stale states.
What the snapshot contains
The file has a YAML frontmatter block followed by the rendered summary and CTA section. The frontmatter records the task ID, the stage name, the command that produced the snapshot, the timestamp, which entity captured it (agent or operator), the recommended next command, and an options list of alternative next steps. Two more fields track the file's own size in bytes and whether the body was truncated.
The 8,192-byte hard cap is the key constraint. If the rendered summary and CTA together exceed that limit, the body is truncated at the cap and a marker is appended: <!-- snapshot-truncated, full response in session jsonl -->. The full response is still available in the session JSONL log; the snapshot is not the only record, just the fast-path one.
Concurrency and security controls
The writer acquires a mkdir-based lock before writing. The lock timeout is configurable via DR_SNAPSHOT_LOCK_TIMEOUT (default 60 seconds). The mkdir primitive is used instead of flock because POSIX flock is unreliable on macOS over NFS and SMB mounts.
Three more controls address the most common file-operation failure modes. Path traversal is blocked by validating the task ID against the pattern ^[A-Z][A-Z0-9-]+-[0-9]{4,5}$ before constructing the path. Shell injection is prevented by reading the body from a file argument rather than expanding it inline. Symlink attacks are blocked by unlinking any pre-existing symlink at the target path before the atomic rename. The finished snapshot file gets chmod 600 and the lock directory gets chmod 700.
Kill switch and implementation location
Setting DATARIM_DISABLE_SNAPSHOT=1 turns the writer into a no-op without modifying any source files. This is useful when running in an environment where the snapshots directory is on a read-only mount or when testing a pipeline without side effects.
The implementation lives in scripts/lib/snapshot-writer.sh, specifically in the write_stage_snapshot function. The single producer touchpoint is the cta-format skill's Snapshot Emission section — the writer is not called directly by individual commands, only through that one entrypoint. The consumer side is the dr-next-snapshot-replay skill, which reads the file and reconstructs context for the resuming command.
Exit codes
The writer exits 0 on success, 1 on IO error or argument validation failure, 2 on a missing required flag, and 3 on lock timeout. A lock timeout (exit 3) typically means another writer is running for the same task — the correct response is to wait and retry rather than overwrite the lock.
Read what Datarim is for context on how snapshots fit into the pipeline, or see the subagent-driven-development skill for how isolated agents use checkpoints during plan execution.