# Recover > [Utilities] Use when restoring workflow context from a checkpoint after session loss. - Skill: `duc01226/recover-2` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/recover-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/recover-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/duc01226/recover-2 --- ## Quick Summary **Goal:** Restore workflow state and todo items from checkpoint files after context loss or session interruption. **Workflow:** 1. **Find Checkpoint** — Locate latest `checkpoint-*.md` in reports directory (legacy `memory-checkpoint-*.md` are also recognized) 2. **Read Metadata** — Extract JSON block with session ID, active plan, current step, pending todos 3. **Restore Todos** — Immediately call TaskCreate with pending items from checkpoint 4. **Resume Workflow** — Continue from the interrupted step using restored context **Key Rules:** - Always restore TaskCreate items before resuming any work - Check both `plans/reports/` and plan-specific report directories - Use timestamp to find the checkpoint closest to the interruption **Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).** # Recover Workflow Context Restore workflow state and todo items from checkpoint files after context compaction or session loss. ## Usage Use this command when: - Context was compacted and you've lost track of the workflow - Session was interrupted and needs to resume - Todo items need to be restored from a checkpoint - The automatic recovery didn't trigger ## Recovery Process ### Step 1: Find Latest Checkpoint Look for checkpoint files in the reports directory: ```bash ls -la plans/reports/checkpoint-*.md | tail -5 ``` Or search for all recent checkpoints: ```bash find plans -name "checkpoint-*.md" -mmin -60 | head -5 ``` ### Step 2: Read Checkpoint File Read the most recent checkpoint to understand the saved state: ``` Read the checkpoint file at: plans/reports/checkpoint-YYYYMMDD-HHMMSS-slug.md ``` ### Step 3: Extract Recovery Metadata The checkpoint file contains a JSON metadata block at the end: ```json { "sessionId": "...", "activePlan": "plans/YYMMDD-slug/", "workflowType": "feature", "currentStep": "feature-implement", "remainingSteps": ["test", "code-review"], "pendingTodos": [...] } ``` ### Step 4: Restore Todo Items **IMMEDIATELY call TaskCreate** with the pending todos from the checkpoint: ```json [ { "content": "[Workflow] /feature-implement - Implement", "status": "in_progress", "activeForm": "Executing /feature-implement" }, { "content": "[Workflow] /test - Run tests", "status": "pending", "activeForm": "Executing /test" }, { "content": "[Workflow] /code-review - Review code", "status": "pending", "activeForm": "Executing /code-review" } ] ``` ### Step 5: Read Active Plan (if exists) If `activePlan` is set in the metadata, read the plan file: ``` Read: {activePlan}/plan.md ``` ### Step 6: Continue Workflow Resume from the `currentStep` identified in the metadata. Execute the remaining workflow steps in order. ## Recovery Checklist - [ ] Located most recent checkpoint file - [ ] Read checkpoint content - [ ] Extracted recovery metadata JSON - [ ] Restored todo items via TaskCreate - [ ] Read active plan (if applicable) - [ ] Identified current workflow step - [ ] Ready to continue from interrupted step ## Recovery (skill-driven) | Scenario | Recovery Type | Trigger | | ----------------------------- | ------------- | -------------------------------- | | Session resume after compact | Manual | This `/recover` command — static `CLAUDE.md` re-read re-anchors protocol; recovery is skill-driven | | New session in same directory | Manual | This `/recover` command | | Explicit user request | Manual | This `/recover` command | | No workflow state found | Manual | This `/recover` command | ## Checkpoint Locations Checkpoints are saved to different locations based on context: 1. **Active plan exists:** `{plan-path}/reports/checkpoint-*.md` 2. **No active plan:** `plans/reports/checkpoint-*.md` > Legacy `memory-checkpoint-*.md` files (written before the grammar was unified) are still matched by the resume/recover globs — back-read is preserved, nothing on disk is orphaned. ## Tips 1. **Check multiple locations** - Plans may have their own reports directories 2. **Use timestamp** - Checkpoints are timestamped, find the one closest to when you were working 3. **Verify todo status** - Compare checkpoint todos with current TaskCreate state 4. **Read incrementally** - Don't try to restore everything at once ## Related Commands - `/checkpoint` - Create a manual checkpoint (before expected loss) - `/compact` - Manually trigger context compaction - `/context` - Load project context - `/watzup` - Generate progress summary ## Example Recovery Flow ``` User: /recover Claude: Let me find and restore your workflow context. 1. Finding latest checkpoint... Found: plans/reports/checkpoint-20260110-143025-new-feature.md 2. Reading checkpoint metadata... - Workflow: feature - Current step: /feature-implement - Remaining: /test, /code-review - Active plan: plans/260110-1430-new-feature/ 3. Restoring TaskCreate items... [Calling TaskCreate with 3 pending items] 4. Reading active plan... [Reading plans/260110-1430-new-feature/plan.md] 5. Ready to continue from /feature-implement step. Shall I proceed with the implementation? ``` --- > **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip. > **AI Mistake Prevention** — Failure modes to avoid on every task: > > **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting. > **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. > **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. > **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. > **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect. > **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. > **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk. > **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. > **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols. > **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. > **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. **MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence. **MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting. > **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `/.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`. > > Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently. **MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `/.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user. ## Closing Reminders **Protocols in force (concise digest of the SYNC/shared blocks this skill carries):** - **Critical Thinking:** MUST ATTENTION apply critical + sequential thinking; traced proof, confidence >80% to act. - **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity. **IMPORTANT MUST ATTENTION** break work into small todo tasks using `TaskCreate` BEFORE starting **IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code **IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act) **IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality **[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.