---
name: turn-recording-workflow
description: Use when code edits or review work are complete in a Remix-bound repo and the completed turn should be captured by automatic hook recording.
---

# Record A Remix Turn

Use this skill after edits or review work are complete and the task should be captured as the final recorded turn in a Remix-bound repo.

This skill is specifically about the automatic hook recording model. The MCP surface does not expose a manual finalize tool.

## Source-blind recording rule

Remix records turns source-blind. Any local content change since the last recorded turn — whether you typed it, the user typed it, a `git pull` brought it in, a `git merge` or `git rebase` produced it, or an IDE saved it — is captured by exactly one completed-turn hook recording. The recording automatically attaches `preTurnEvents` metadata describing any commits, merges, or uncommitted state captured at the boundary; you do not need to summarize that yourself.

Do **not** call baseline repair, init, sync, or reconcile tools purely as preconditions for recording. Cursor's hooks route the safe next step:

- `record` (or `repoState: local_only_changed`) → no manual MCP action. The completed-turn hook will capture the boundary.
- `branch_binding_missing` / `baseline_missing` / `init` → hooks seed or repair the branch binding or local revision baseline.
- `pull_required` / `pull` → hooks or explicit sync bring down server-only changes.
- `reconcile_required` / `reconcile` → use reconcile only when both sides changed since the agreed baseline.

Each automatic fix runs detached, logs to `.remix/<command>.log`, and writes a marker that the next prompt surfaces. If you see a Remix recovery note on the next prompt, it is the runtime telling you what already happened — not a request for you to retry.

## Runtime recording

In a Remix-bound repo, Cursor records through `afterAgentResponse`, with `stop` as a sweep and retry backstop.

- Do **not** call a finalize MCP tool. The MCP surface does not expose one; the runtime is recording the turn.
- Do **not** call `remix_collab_drain_finalize_queue` for this turn. The runtime drains the queue automatically in the background. Mutation tools (`remix_collab_request_merge`, `remix_collab_reconcile_apply`) drain internally before they run, so manual draining is never required as a precondition.

Use `remix_collab_drain_finalize_queue` only for explicit recovery flows, such as status reporting `await_finalize` before a merge-related operation.

Workflow:

1. Run `remix_collab_status` first to confirm the repo is bound and inspect current warnings.
2. If status recommends `await_finalize`, do not request a merge yet. Use `remix_collab_drain_finalize_queue`, then re-check `remix_collab_status`.
3. When status recommends `record`, continue the turn normally. The completed-turn hook captures the exact user prompt, final assistant response, and local workspace boundary.
4. Treat hook recording as local capture plus queued remote processing, not as immediate proof that a remote change step already exists.

Important behavior:

- Automatic hook recording is the authoritative path for completed work instead of raw git commit or push.
- Hook recording is queued. A remote change step does not exist yet until the finalize queue drains successfully.
- If `remix_collab_status` reports `await_finalize`, use `remix_collab_drain_finalize_queue` and re-check status before merge-related or recovery flows.
- If the user wants to understand current repo state before the turn ends, re-run `remix_collab_status`.
- Do not make further repo mutations after the final response unless you intend them to be captured by a later completed turn.
- Do not retry recording just because a remote record is not visible yet; queue drain is the next step, not another recording attempt.
- If drain returns `recommendedNextActions` or an `error.hint`, those fields are **authoritative and mandatory**. Do not ignore them. Do not improvise around them. Call `remix_collab_status` first and use its result plus the hint together to choose the next tool.
- If the tool surfaces a preserved local recovery artifact, mention it explicitly and keep it available while you repair repo state.

Use the live worktree as the source of truth for recorded work. If the repo is not ready, fix the preflight state first rather than trying to bypass it.

## Branch recovery

If status shows the current branch is unbound, **do not call `remix_collab_init` yourself just to repair recording.** The `beforeSubmitPrompt` hook spawns `remix collab init` detached for already-bound repos and deferred turns replay automatically once init completes. If init fails, the next prompt surfaces the recovery marker.

You should only call `remix_collab_init` for this case when the user explicitly asks for an immediate, synchronous init, or when a runtime recovery message says manual init is required.

**NEVER switch git branches to resolve a recording issue.** Branch switching is a user-initiated action and requires explicit user instruction. If status shows the current branch is unbound, leave it for hook-owned recovery — do not switch to some other bound branch to avoid init.

The triviality of the user's current prompt is irrelevant. "Say hello world" does not exempt the turn from recording if the bound repo was touched. The hooks handle routine recording automatically.
