lvlup-sw/rehydrate

Workflow Rehydrate Skill

Overview

Restore full workflow awareness that survives context auto-summarization without starting a new session.

This skill owns the read/restore side of workflow state — reading current state, reconciling it against git reality, and verifying whether a workflow exists at all. For the write side (init, update, transition, capturing a handoff), see @skills/checkpoint/SKILL.md.

Triggers

Activate this skill when:

• Restoring context after summarization (rehydrate <featureId>)
• The agent has drifted after context compaction (stopped emitting events or using tools proactively)
• Returning to a workflow after a break

State Location

Workflow state lives in the MCP event store, not the filesystem. Use exarchos:exarchos_workflow get to read state and exarchos_view pipeline to discover active workflows. Do not scan ~/.claude/workflow-state/*.state.json — that path is legacy and may be stale or empty.

Source of Truth — does this workflow exist?

Workflow state lives in two surfaces, and conflating them causes wrong "untracked" conclusions:

1. The SQLite event store (events + projected workflow_state + streams) — the authoritative record of whether a workflow exists. This is what rehydrate / get read.
2. <featureId>.state.json files (under the state dir) — a secondary "planner's stamp" that carries plan-state facts the event projection cannot derive (review status, declared task list, dimension findings). It may be absent for a tracked workflow (CLI tools, tests, in-flight workflows before the first update) and is not an existence signal.

Canonical existence check: use the rehydrate envelope's _meta.workflowExists (true/false), or equivalently a non-empty data.workflowState.featureId. A cold probe of a never-init'd featureId returns success: true with an empty initial document and _meta.workflowExists: false — and is side-effect-free (it emits no workflow.rehydrated event). Never infer existence from the presence or absence of a .state.json file on disk.

Rehydrate the Workflow

Use exarchos:exarchos_workflow with action: "rehydrate" and featureId: "<id>" — it returns an envelope containing the canonical rehydration document (workflowState, taskProgress, artifacts, blockers, phase playbook, next actions) in a single call. No multi-step get fields=[...] composition is needed.

If the featureId is unknown or the user hasn't named one, fall back to exarchos_view pipeline to list active workflows and ask which to rehydrate, then re-invoke rehydrate with the selected featureId. The pipeline view is repo-scoped by default — it lists only the caller's repo, so a workflow started in another repo won't appear. Every response reports unscopedTotal (the pre-scope count); when unscopedTotal exceeds page.total, the hidden rows live in other repos (or are legacy rows without recorded identity) — re-query with scope: "all" (or an explicit repoRoot) to reveal them.

Read State (targeted)

For a targeted read rather than a full rehydration, use exarchos:exarchos_workflow with action: "get" and featureId:

• Full state: Call with just featureId
• Specific field: Add query for dot-path lookup (e.g., query: "phase", query: "tasks")
• Multiple fields: Add fields array for projection (e.g., fields: ["phase", "featureId", "tasks"])

Field projection via fields returns only the requested top-level keys, reducing token cost.

Get Summary

For context restoration after summarization, prefer action: "rehydrate" (single-call, includes the phase playbook and next actions). For a minimal read, action: "get" with featureId outputs a summary suitable for rebuilding orchestrator context.

Output Format

Render the returned document as compact behavioral context (the same shape as post-compaction context) so the agent refreshes its awareness in one pass:

## Workflow Rehydrated: <featureId>
**Phase:** <phase> | **Type:** <workflowType>

### House Rules (apply every action this turn forward)
**Skill:** <phasePlaybook.skillRef or "(no playbook for this phase)">
**Tools:** <phasePlaybook.tools rendered as bullets>
**Required model-emitted events:** <phasePlaybook.events rendered as bullets — e.g. `task.progressed`, `phase.advanced`>
**Auto-emitted events (runtime fires these):** <phasePlaybook.autoEmittedEvents rendered as bullets>
**Transition:** <phasePlaybook.transitionCriteria> | Guard: <phasePlaybook.guardPrerequisites>
**Validation scripts:** <phasePlaybook.validationScripts joined>

### Event Emission Hints
<_eventHints.missing rendered as bullets, or "(none — phase machinery satisfied)">

### Task Progress
<task table>

### Artifacts
- Design: <path or "not created">
- Plan: <path or "not created">
- PR: <url or "not created">

### Next Action
<suggested action, from the envelope's `next_actions`>

> **Discipline reminder:** every task transition this turn forward MUST land on the workflow event stream via `exarchos_event.append` or `delegate` subagent emission. Direct `Edit` / `Bash` / `git` actions on task branches without corresponding events will desync the workflow tracker (see RCA `docs/rca/2026-05-08-rehydrate-behavioral-gap.md`).

Keep the output minimal — only essential state and behavioral guidance; full details stay in files, not the conversation.

Reconcile State

To verify state matches git reality, run rehydrate <featureId> — the rehydration projection folds events newer than the last snapshot and surfaces drift in the returned envelope. For deeper manual verification, run the reconciliation script:

exarchos_orchestrate({
  action: "reconcile_state",
  stateFile: "<state-file>",
  repoRoot: "<repo-root>"
})

On passed: true: State is consistent. On passed: false: Discrepancies found — review output and resolve via exarchos:exarchos_workflow with action: "update" (see @skills/checkpoint/SKILL.md).

Best Practices

1. Reconcile on resume - Always verify state matches git state before acting
2. Read state, don't remember - After summarization, read from the event store, not memory
3. Single-call fetch - One rehydrate call returns the full canonical document; avoid multi-step reads
4. Existence via _meta.workflowExists - Never infer existence from a .state.json file on disk

Troubleshooting

State Desync

If workflow state doesn't match git reality:

1. Run rehydrate <featureId> — the rehydration projection folds in events newer than the last snapshot
2. If manual check still needed: compare the rehydration document's workflowState / artifacts with git log and branch state
3. Update state via exarchos:exarchos_workflow with action: "update" to match git truth (see @skills/checkpoint/SKILL.md)

Resume Finds Stale State

If state references branches or worktrees that no longer exist:

1. Run rehydrate <featureId> — the rehydration document surfaces stale references
2. Compare against git branch -a / git worktree list to identify drift
3. Update via exarchos_workflow update to match git truth

Multiple Active Workflows

If multiple workflow state files exist:

1. The system uses the most recently updated active (non-completed) workflow
2. Use exarchos:exarchos_workflow with action: "cancel" and dryRun: true on stale workflows to preview cleanup
3. Cancel stale workflows before starting new ones

Example Workflow

1. Resume after context loss: Use exarchos:exarchos_workflow with action: "rehydrate" and featureId: "user-authentication" to get context restoration output.

2. Check state: Use exarchos:exarchos_workflow with action: "get" and featureId: "user-authentication".

3. Verify existence: Read _meta.workflowExists from the rehydrate envelope — if false, the feature was never started as a workflow, so report that rather than declaring it "untracked" from a filesystem check.