Plugin Reference
This page shows the internal instructions Claude follows when you invoke /kli:resume_handoff in Claude Code.
auto-generated from kli/plugin/commands/resume_handoff.md

Resume Handoff

Resume work from handoff document with context analysis and validation

You are tasked with resuming work from a handoff document through an interactive process.

Context

These handoffs contain critical context, learnings, and next steps from previous work sessions that need to be understood and continued.

Initial Response

When this command is invoked:

1. If the path to a handoff document was provided

Example: /kli:resume_handoff ace/tasks/2025-10-26-handoff-commands/handoffs/2025-10-26_14-30-00_phase-1.md

  • Skip the default message
  • Immediately read the handoff document FULLY (no limit/offset)
  • Immediately read any research or plan documents it links to under "Critical References"
  • Do NOT use a sub-agent to read these critical files
  • Derive the task ID from the path (e.g. ace/tasks/2025-10-26-handoff-commands/handoffs/... → task ID is 2025-10-26-handoff-commands)
  • Set current task via task_bootstrap so subsequent MCP calls have context
  • Begin analysis process by ingesting context
  • Propose course of action to user and confirm

2. If a task name was provided

Example: /kli:resume_handoff 2025-10-26-handoff-commands

  • Bootstrap task: task_bootstrap(task_id="2025-10-26-handoff-commands") — sets context + returns state with artifacts
  • Check timeline: timeline(limit=20) — look for :handoff.create events which contain the handoff path
  • Also check with Glob: ace/tasks/2025-10-26-handoff-commands/handoffs/*.md
  • If no handoffs exist: "I can't find any handoff documents in this task. Would you like to create one with /kli:handoff?"
  • If one handoff: Proceed with that handoff
  • If multiple handoffs: Use the most recent (by timestamp in filename YYYY-MM-DD_HH-MM-SS)
  • Read handoff FULLY and linked artifacts
  • Begin analysis process

3. If no parameters provided

Example: /kli:resume_handoff

Step 1: Use Session Start Context (Already Injected)

The session start hook injects task context at the beginning of each session. Look for this in the conversation startup:

TASK[1]{dir,phase,last_artifact}:
 ace/tasks/2025-12-12-task-name,Phase 2: Implementation,research.md
  • If TASK[1] context exists: Extract the task directory from it (first field before comma)
  • This context is already in your conversation - no file reading needed
  • The session start hook has done the discovery work for you

Step 2: Find Handoffs for Active Task

If active task found (e.g., 2025-12-12-task-name):

  1. Bootstrap task: task_bootstrap(task_id="2025-12-12-task-name")
  2. Check timeline for :handoff.create events: timeline(limit=30)
  3. Also glob for handoff files: ace/tasks/2025-12-12-task-name/handoffs/*.md
  4. If handoffs exist:
  5. Use most recent by filename timestamp (YYYY-MM-DD_HH-MM-SS)
  6. Announce: "Found active task with handoff. Resuming from {handoff_path}..."
  7. Proceed to read handoff and linked artifacts
  8. If no handoffs but task exists:
  9. Get task state with task_get() for observations and artifacts
  10. Ask: "Found active task but no handoffs. Read observations instead? [Y/n]"

Step 3: Fallback (No TASK Context)

If no TASK[1] in session startup (rare - usually means no active task):

I'll help you resume work from a handoff document.

Please provide either:
- Full path: `/kli:resume_handoff ace/tasks/2025-10-26-task/handoffs/2025-10-26_14-30-00_desc.md`
- Task name: `/kli:resume_handoff 2025-10-26-task-name`

Or I can help you find available handoffs. What would you like to do?

Then wait for user input.

Process Steps

Step 1: Read and Analyze Handoff

  1. Restore task context and activate relevant patterns: task_bootstrap(task_id) pq_query('(-> (activate "<task topic>" :boost (<domain1> <domain2>)) (:take 5))') The activate query uses task topic + graph context to surface semantically relevant patterns.

  2. Read handoff document completely:

  3. Use Read tool WITHOUT limit/offset parameters

  4. Extract all sections:
    • Task(s) and their statuses
    • Critical References
    • Recent changes
    • Learnings
    • Artifacts
    • Action items and next steps
    • Other notes

  5. Read referenced artifacts:

  6. Read all files mentioned in "Critical References" section

  7. Read research.md if referenced

  8. Read plan.md if referenced

  9. Read any other critical files mentioned

  10. Use Read tool FULLY for each file

  11. Verify current state (read-only validation):

  12. Check if mentioned files still exist at specified paths

  13. Use task_get() to see current task state vs handoff state

  14. Check timeline(limit=20) for recent activity since handoff

  15. Check if recent changes are still present

  16. Note any discrepancies between handoff and current state

  17. Verify graph state (if task has phases): Spawn graph-analyst to check current graph state:

Task( subagent_type="graph-analyst", prompt='{"question": "What is the current state of task <task_id>? Are there any stale phases, new blocking dependencies, or changes since the handoff?"}', description="Verify task graph state" )

This catches: - Phases completed by another session since handoff - New blocking dependencies introduced - Related tasks that were created - Changes to task metadata or goals

Step 2: Synthesize and Present Analysis

Present comprehensive analysis to user:

I've analyzed the handoff from [date] for task [name].

**Original Tasks:**
- [Task 1]: [Status from handoff] → [Current verification]
- [Task 2]: [Status from handoff] → [Current verification]

**Key Learnings from Handoff:**
- [Learning 1 with file:line reference]
- [Learning 2 with pattern discovered]

**Recent Changes Status:**
- [Change 1] - [Verified present/Missing/Modified]
- [Change 2] - [Verified present/Missing/Modified]

**Critical Artifacts Reviewed:**
- [research.md]: [Key findings summary]
- [plan.md]: [Phase status summary]

**Graph State** (if task has phases):
- [Graph-analyst findings about current state]
- [Phases completed since handoff]
- [New blocking dependencies]
- [Related tasks created]

**Recommended Next Actions:**
Based on the handoff's action items:
1. [Most logical next step]
2. [Second priority]
3. [Additional tasks]

**Discrepancies Found** (if any):
- [File mentioned but not found]
- [Change mentioned but different]
- [State mismatch]

Shall I proceed with [recommended action 1], or would you like to adjust the approach?

Get user confirmation before proceeding.

Step 3: Create Action Plan

  1. Use TodoWrite to create task list:

  2. Convert action items from handoff into todos

  3. Add any new tasks discovered during analysis

  4. Prioritize based on dependencies

  5. Present the plan: ``` I've created a task list based on the handoff:

[Show todo list]

Ready to begin with the first task? ```

Step 4: Begin Work

  1. Start with first approved task
  2. Reference learnings from handoff throughout work
  3. Apply patterns discovered in handoff
  4. Update progress as tasks complete

Guidelines

  1. Be Thorough in Analysis:

  2. Read entire handoff document

  3. Verify ALL mentioned changes exist

  4. Check for regressions or conflicts

  5. Read all referenced artifacts

  6. Be Interactive:

  7. Present findings before starting work

  8. Get buy-in on approach

  9. Allow course corrections

  10. Adapt based on current vs handoff state

  11. Leverage Handoff Wisdom:

  12. Pay attention to "Learnings" section

  13. Apply documented patterns

  14. Avoid repeating mistakes mentioned

  15. Build on discovered solutions

  16. Validate Before Acting:

  17. Never assume handoff state matches current

  18. Verify file references still exist

  19. Check for breaking changes since handoff

  20. Confirm patterns still valid

  21. Avoid Unnecessary Sub-Agents:

  22. Read files directly in main context

  23. Only spawn agents if complex verification needed

  24. Most handoff resumption is straightforward reading

Common Scenarios

Clean Continuation: - All changes present, no conflicts - Proceed with recommended actions

Diverged Codebase: - Some changes missing or modified - Reconcile differences and adapt plan

Incomplete Work: - Tasks marked "in_progress" - Complete unfinished work first

Stale Handoff: - Significant time passed - Re-evaluate strategy based on current state

←ResearchResume Task→