dr-next-snapshot-replay git:20261014.698c91cA

Immutable. This exact content never changes and is served at /api/v1/blob/887f3a414ee91ed2.

---
name: dr-next-snapshot-replay
description: Consumer contract for stage snapshots — /dr-next and /dr-orchestrate read datarim/snapshots/{TASK-ID}.snapshot.md first and emit a replay prompt.
current_aal: 1
target_aal: 2
---

# Stage-Snapshot Replay (consumer side)

`/dr-next` and `/dr-orchestrate`, after Task Resolution, read the snapshot **first** — before task-description, init-task, activeContext, PRD, or plan. If the snapshot exists and is valid, they assemble a replay prompt in the canonical form and continue autonomously. If the snapshot is missing or malformed, fall back to the legacy behaviour without warning noise.

## Contract

| Aspect | Value |
|--------|-------|
| Consumer touchpoints | `commands/dr-next.md` § Step 2.5, `commands/dr-orchestrate.md` § Snapshot-First Resume |
| Snapshot path | `datarim/snapshots/{TASK-ID}.snapshot.md` |
| Validator | `"${DATARIM_RUNTIME:?}/dev-tools/check-stage-snapshot-on-exit.sh" --validate-frontmatter --task <ID>` (exit 0 = ok) |
| Fallback policy | snapshot absent OR validator exit ≠ 0 → legacy Read pipeline, **no warning** (V-AC-7) |
| Prompt template | see § Replay-prompt template below |

## Replay-prompt template (canonical, V-AC-6 + V-AC-11)

When the snapshot is valid, emit exactly this shape, with no improvisation:

<!-- allow-non-ascii-block: canonical-bilingual-replay-prompt-rendered-verbatim-to-agent-runtime -->

```
<recommended-CTA>

Find a way to investigate all problems and answer all questions yourself. Perform on behalf of the operator every step and requirement you can do yourself. Do not spawn FU sub-tasks for Level-1 work — resolve them in the same cycle to completion.

done before:
<snapshot body>
```

<!-- /allow-non-ascii-block -->

- `<recommended-CTA>` — the `recommended_next` value from the snapshot frontmatter plus one purpose line, expanded by the CTA heuristic below.
- The English autonomy instruction is stable model-facing context. Carry both resolved language tags separately; localize human explanation using replies and preserve the snapshot body verbatim.
- The `done before:` header is a literal; the exact snapshot body content follows underneath.

## CTA Selection heuristic (V-AC-12, natural-language guidance)

The `recommended_next` value from the snapshot is a hint already emitted correctly by the previous stage per `cta-format.md` § Authoring Rules. This heuristic documents the **rationale** for preferring that option; it does not recompute it. If the operator has a reason to pick a different option from `options[]`, the operator types it explicitly — the replay prompt shows the recommended option but does not block an override.

Principle: **maximise the marginal quality improvement of the solution**. For L3+ tasks with few verification passes so far, prefer verification commands (`/dr-verify`, `/dr-qa`, `/dr-design`) over `/dr-do`. When verification is saturated, move on to implementation or archiving.

### Example 1 — L3+ after `/dr-plan`, few verification passes → `/dr-verify`

Snapshot: `recommended_next: /dr-verify`, `options:`
- `/dr-do <TASK-ID> | TDD implementation`
- `/dr-design <TASK-ID> | ratify Vault relativePath`
- `/dr-qa <TASK-ID> | pre-implementation coverage`
- `/dr-verify <TASK-ID> | tri-layer plan verification`
- `/dr-status | escape hatch`

The heuristic picks `/dr-verify` — the plan has just been finalised and the security review / threat model have not yet been cross-checked by an independent layer. Verification is cheaper than rolling back `/dr-do` if drift is found later. Rationale: <TASK-ID> is an L3 security-critical task with 21 V-AC; the cost of a verification verdict (Layer 1 deterministic + Layer 2 cross-model + Layer 3 native dispatch) is far lower than rolling back a bootstrap on PROD.

### Example 2 — L3+ saturated with verification (plan + design + verify done) → `/dr-do`

Snapshot: `recommended_next: /dr-do`, `options:`
- `/dr-do <TASK-ID> | TDD implementation`
- `/dr-qa <TASK-ID> | redo coverage check`
- `/dr-status | escape hatch`

The heuristic picks `/dr-do` directly. Rationale: accumulated evidence (plan + design + tri-layer verify all green) is enough for a confident implementation pass. Another `/dr-qa` is diminishing returns; `/dr-status` is the escape hatch for non-standard operator decisions.

### Example 3 — L1/L2 after `/dr-do` → `/dr-archive`

Snapshot: `recommended_next: /dr-archive`, `options:`
- `/dr-archive <TASK-ID> | finalise + archive doc`
- `/dr-qa <TASK-ID> | optional re-check`
- `/dr-status | escape hatch`

The heuristic picks `/dr-archive`. Rationale: per `cta-format.md` § Authoring Rules, the L1/L2 primary after `/dr-do` is `/dr-archive`. Implementation is already done; archive captures the outcome and frees activeContext. Override only when `/dr-do` surfaced open questions that justify a revisit.

## Implementation outline

### Research projection revalidation

A research projection in the snapshot body is context, not authority. Before following its CTA, run `${DATARIM_RUNTIME:?}/dev-tools/product-decision-route.py --root <workspace-root> --task <TASK-ID>` and follow only its fresh route and typed token. The helper rereads the authoritative task acceptance/evidence records, validates the latest DecisionRecord revision and digest (including the `supersedes` chain), validates the ProductBrief exact input revisions, and verifies the authorization reference and scope advance against the parent contract hash. If the helper refuses or cannot establish current state, do not advance from the snapshot. Preserve the parent acceptance contract and lineage when emitting the replay prompt.

```
1. Resolve TASK-ID per Task Resolution Rule.
2. snapshot_path = "$REPO_ROOT/datarim/snapshots/${TASK_ID}.snapshot.md"
3. if check-stage-snapshot-on-exit.sh --validate-frontmatter --task "$TASK_ID" → exit 0:
       read snapshot body + frontmatter
       emit replay prompt per § Replay-prompt template
       STOP downstream Read pipeline — primary context = snapshot
   else:
       silent fallback → legacy Read order (task-description / init-task / activeContext)
```

`/dr-orchestrate` integrates the snapshot-first read **before** `subagent_resolver.sh`; `recommended_next` is passed to the resolver as `--hint <command>`. The resolver may still return a different command — the snapshot is a hint, not a constraint.

## Shared Replay Renderer

This section is the **single canonical source** for the bilingual replay-prompt
template. Both `/dr-next` (via § Replay-prompt template above) and
`/dr-continue` (via `skills/session-handoff-replay/SKILL.md`) cite this section
to stay in lockstep. Do not duplicate the template elsewhere — reference this
section by name.

The renderer contract:
1. Consume a `recommended_next` value from the artefact frontmatter.
2. Emit the autonomy block verbatim (see § Replay-prompt template).
3. Append the `done before:` header followed by the artefact body content.
4. Any changes to wording or structure of the autonomy block MUST be made
   here first; all consumers pick them up automatically.

`/dr-continue` uses this renderer for session-scoped handoff artefacts; the
source artefact is `datarim/sessions/{SESSION-ID}.session.md` (validated by
`dev-tools/check-session-handoff.sh`) rather than the per-task snapshot, but
the rendered replay-prompt template is identical.

## Related

- `skills/stage-snapshot-writer/SKILL.md` — the producer side (per-task snapshots).
- `skills/session-handoff-writer/SKILL.md` — the producer side (session handoff artefacts).
- `skills/session-handoff-replay/SKILL.md` — consumer side for session handoff, cites § Shared Replay Renderer.
- `skills/cta-format/SKILL.md` — the CTA block ([definition](../cta-format/SKILL.md)) format that fills `<recommended-CTA>`.
- `dev-tools/check-stage-snapshot-on-exit.sh` — the mandatory validator that runs before the per-task prompt is emitted.
- `dev-tools/check-session-handoff.sh` — the mandatory validator that runs before the session replay prompt is emitted.
- `commands/dr-next.md` § Step 2.5 — consumer touchpoint.
- `commands/dr-continue.md` — session-handoff consumer touchpoint.
- `commands/dr-orchestrate.md` § Snapshot-First Resume — orchestrator touchpoint.