notque/vexjoy-agent / skills/process/workflow
workflow
VerifiedStructured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.
references/pl-resume.md
View on GitHub# Resume Work Reference
## Overview
This reference reconstructs session state from handoff artifacts so work can continue without wasting time re-reading files and re-discovering decisions. It is the consumer half of the pause/resume pair — the pause intent creates the artifacts, this reference consumes them.
The priority cascade exists because handoff quality varies:
1. **HANDOFF.json** — Best case. Machine-readable, structured, created by explicit pause. Contains reasoning context.
2. **.continue-here.md** — Good case. Human-readable prose. May exist without JSON if user wrote it manually.
3. **task_plan.md** — Fallback. Records task structure but not session reasoning. Better than nothing.
4. **git log + git status** — Last resort. Can infer recent activity but cannot reconstruct reasoning or rejected approaches.
Each level down the cascade loses more context, so this reference always starts from the top.
---
## Instructions
### Phase 1: DISCOVER
**Goal**: Find the best available state source using the priority cascade. Always check sources in order to ensure no high-quality context is lost (higher sources contain richer information than lower ones).
**Step 1: Identify project root**
```bash
git rev-parse --show-toplevel
```
**Step 2: Check for HANDOFF.json (Priority 1)**
Look for `{project_root}/HANDOFF.json`. If found:
- Read and parse the JSON
- Check `created_at` timestamp — if older than 24 hours, set `stale_warning = true` and plan to alert user before proceeding
- This is the richest source: proceed to Phase 2 with full structured data
- Also read `.continue-here.md` if it exists (for supplementary prose context)
**Step 3: Check for .continue-here.md (Priority 2)**
If no HANDOFF.json but `.continue-here.md` exists:
- Read the prose content
- Extract what you can: task description, completed items, next action, decisions
- Note that reasoning context may be limited compared to JSON handoff
**Step 4: Check for task_plan.md (Priority 3)**
If neither handoff file exists but `task_plan.md` exists:
- Read the plan
- Extract: completed phases `[x]`, remaining phases `[ ]`, decisions, errors, current status
- Note: this source captures task structure but not session reasoning
**Step 5: Fall back to git reconstruction (Priority 4)**
If no handoff files and no task_plan.md:
```bash
# Recent activity
git log --oneline -20
# Current branch context
git branch --show-current
# Uncommitted work
git status --short
# What's changed
git diff --stat
```
Synthesize a best-effort summary from git state. This is the least precise reconstruction — it shows WHAT happened but not WHY. Never skip to this source if higher-priority sources exist, as that would lose context.
**Step 6: Set reconstruction quality indicator**
| Source | Quality | Missing |
|--------|---------|---------|
| HANDOFF.json | Full | Nothing — richest source |
| .continue-here.md | Good | Structured data, may lack reasoning detail |
| task_plan.md | Partial | Session reasoning, rejected approaches, mental model |
| git log | Minimal | All reasoning context, decisions rationale, next action specifics |
**GATE**: At least one state source found and read. If ALL sources are empty (no handoff, no plan, no git history), inform user: "No session state found. Use /do to start a new task."
### Phase 2: RECONSTRUCT
**Goal**: Build a coherent state picture from available sources. Always present a status dashboard before taking action — the user needs to confirm the reconstructed state matches reality, since self-assessment of "what I was doing" is inherently fallible.
**Step 1: Verify uncommitted files**
If the handoff reports `uncommitted_files`, check whether they still exist (work may have been lost during worktree cleanup or manual revert):
```bash
# For each file in uncommitted_files list
git status --short -- <file>
```
Flag any files that were listed as uncommitted but are now missing — these represent potential work loss.
**Step 2: Check for false completions**
If the handoff reports `false_completions`, verify those placeholder markers still exist in the codebase. They may have been fixed by manual intervention between sessions.
**Step 3: Synthesize status dashboard**
Build the dashboard from available data. This dashboard is your knowledge checkpoint — it prevents false assumptions from carrying into the resumed session:
```
===================================================================
SESSION RESUMED
===================================================================
Source: HANDOFF.json (created: <timestamp>) [STALE WARNING if applicable]
Branch: <branch> (base: <base_branch>)
Task: <task_summary>
Completed:
- <completed item 1>
- <completed item 2>
Remaining:
- <remaining item 1>
- <remaining item 2>
Blockers: <blockers or "None">
Key Decisions:
- <decision>: <reasoning>
Uncommitted Work: <N file(s)> [WARNING: N file(s) missing if applicable]
False Completions: <N placeholder(s)> [or "None detected"]
Next Action:
<next_action description>
===================================================================
```
**GATE**: Status dashboard constructed. Ready to present to user.
### Phase 3: PRESENT
**Goal**: Show the user what was reconstructed and confirm before proceeding. Never skip the dashboard — it is the validation checkpoint that catches assumptions made by the new session before they cause problems.
**Step 1: Display status dashboard**
Show the dashboard from Phase 2.
**Step 2: Handle stale handoff warning**
If `stale_warning` is true, warn the user before proceeding (stale handoffs may describe work superseded by manual changes between sessions):
```
WARNING: Handoff is from <timestamp> (>24 hours ago).
State may not reflect manual changes made since then.
Proceed with this handoff or discard it? [proceed/discard]
```
If user discards, fall to next priority level in cascade.
**Step 3: Determine action mode**
- **Quick resume** (user said "continue", "resume", or similar with no qualifiers): Skip options menu and proceed directly to Phase 4 to execute `next_action`. This optimizes for the common case where the user trusts the handoff and wants to get back to work fast.
- **Review mode** (user said "what was I doing", "where did I leave off", or asked a question): Display dashboard only, wait for user to choose what to do next
**GATE**: User has seen the dashboard. In quick resume mode, proceed to Phase 4. In review mode, wait for user direction.
### Phase 4: EXECUTE
**Goal**: Route to the next action and clean up handoff files (they are ephemeral session artifacts, not persistent state, so keeping them risks future resume calls loading outdated context).
**Step 1: Execute next action**
Take the `next_action` from the handoff and execute it:
- If it matches a skill trigger (e.g., "run tests" -> `vitest-runner`), route through `/do`; the dispatch prompt must say `Call the Skill tool with \`skill-name\`.`
- If it describes a code change, proceed with the implementation directly
- If it requires user input (e.g., "need clarification on threshold"), present the question
Carry forward all context from the handoff: decisions made, approaches rejected, gotchas to avoid. Honor previous session's findings unless circumstances have changed — reexploring rejected approaches burns context on work already done.
**Cache check before re-dispatching agents.** When `next_action` resumes a parallel agent wave (fan-out dispatch) that was interrupted, check the handoff's `agent_outputs` cache before dispatching each agent — reusing a finished agent's output instead of re-running it saves tokens. For each agent about to be dispatched:
1. Compute its input hash with `scripts/feature-state.py`'s `agent_input_hash(prompt, inputs, paths)` over the exact dispatch input: the prompt text, any inputs that determine the agent's output, and `paths=` listing every repo file the agent reads but does not write (reviewed artifact, analysis inputs). List files, not directories. Leave out the files an agent writes: its key is captured before it runs, so a written file's bytes differ at resume and the agent would always miss, re-dispatching an implementer whose edits are already on disk and risking the same edits twice. An agent whose `paths=` would then be empty still hits on unchanged prompt and inputs; if it must react to the current tree, treat it as a miss and re-dispatch it against that tree. The hash folds in each listed file's content, so a cached result is invalidated by any change to the prompt, to `inputs`, to the set of listed paths, or to the bytes of any listed file (including a file created or deleted since pause). A file the prompt names but `paths=` omits is not checked, so a stale verdict on it can be reused. Determinism is the contract: unchanged prompt, inputs, and file contents yield the same hash as the previous session. The cache is only as fresh as its keys: a stored key must have been computed at dispatch, before the agent read its files. A key hashed at pause after another agent in the wave edited a listed file covers the edited bytes, so it hits on resume while its output judges the old ones. When this session dispatches agents, compute and record each key before dispatch for the same reason.
2. Look it up with `lookup_agent_output(handoff, input_hash)`. On a **hit**, reuse the cached `output` and skip dispatch. On a **miss** (or any input that changed since pause), dispatch the agent normally, then record the result with `store_agent_output(handoff, input_hash, output, label, timestamp)` so a later interruption can reuse it too.
A handoff with no `agent_outputs` field loads as an empty cache (`load_agent_outputs` returns `{}`) — every agent is a clean miss, so legacy handoffs and non-wave resumes behave exactly as before. Use the script helpers for hashing and lookup rather than reimplementing the hash in prose, because only identical normalized hashing across sessions makes a cache hit reliable.
**Step 2: Clean up handoff files**
After the next action has been initiated (not necessarily completed — just successfully started), delete the one-shot handoff artifacts to prevent stale state:
```bash
# Remove one-shot handoff artifacts
rm -f HANDOFF.json .continue-here.md
```
If `--keep` flag was provided, skip deletion (use only for debugging).
**Step 3: Update task_plan.md if present**
If `task_plan.md` exists, update its status line to reflect that the session has resumed. The plan is the persistent record; handoff is the ephemeral session context:
```
**Status**: Resumed from handoff — executing: <next_action summary>
```
**GATE**: Next action initiated. Handoff files cleaned up. Session is now in active work mode. Note: This reference never modifies code, resets git state, or discards uncommitted changes — it only reads and deletes handoff files.
---
## Error Handling
### Error: No State Sources Found
**Cause**: No HANDOFF.json, no .continue-here.md, no task_plan.md, and git log is empty or on a fresh branch
**Solution**: Inform user: "No session state found to resume from. Use /do to start a new task, or describe what you were working on and I'll reconstruct manually."
### Error: HANDOFF.json Parse Failure
**Cause**: HANDOFF.json exists but contains invalid JSON (corrupted, partially written, manually edited badly)
**Solution**: Warn user about the parse error. Fall through to .continue-here.md if it exists, otherwise fall to task_plan.md. Do not silently ignore the error — the user should know their handoff was corrupted.
### Error: Uncommitted Files Missing
**Cause**: Handoff reports uncommitted files that no longer exist (worktree cleanup, manual deletion, git checkout)
**Solution**: Alert the user with specific file names. These changes are likely lost. The user may need to recreate them — the handoff's `context_notes` and `decisions` can help guide reconstruction.
### Error: Stale Handoff Rejected
**Cause**: User chose to discard a stale (>24h) handoff
**Solution**: Delete the stale handoff files and fall through to the next priority level in the cascade (task_plan.md or git log). Proceed with the lower-quality reconstruction.
---
## References
### Related Intents
- `pause` (planning umbrella) — Creates the handoff artifacts this reference consumes
- `do` — Routes next_action to appropriate agent/skill for execution
- `workflow-orchestrator` — For complex multi-phase tasks that benefit from handoff between phases
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |