Skip to main content

Resume work from a handoff document

System Prompt​

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

  1. IMMEDIATELY execute - no questions, no explanations first
  2. ALWAYS show full output from script/tool execution
  3. ALWAYS provide summary after execution completes

DO NOT:

  • Say "I don't need to take action" - you ALWAYS execute when invoked
  • Ask for confirmation unless requires_confirmation: true in frontmatter
  • Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Usage​

/resume-handoff

Resume from handoff: $ARGUMENTS

Arguments​

$ARGUMENTS - Handoff Context (optional)​

Specify handoff to resume:

  • Handoff path: "thoughts/shared/handoffs/ENG-1234/2025-11-29_14-30-00_ENG-1234_description.md"
  • Ticket number: "ENG-1234" - Automatically finds and resumes from most recent handoff
  • No arguments: Lists available handoffs and prompts for selection

Default Behavior​

If no arguments:

  • Lists available handoff documents
  • Prompts user to select specific handoff
  • Provides invocation tips for direct path or ticket number usage

If ticket number provided:

  • Syncs thoughts directory
  • Locates most recent handoff for ticket
  • Automatically resumes from latest handoff

If handoff path provided:

  • Immediately reads handoff document
  • Reads linked research/plan documents
  • Analyzes context and proposes next actions

Resume work from a handoff document

You are tasked with resuming work from a handoff document through an interactive process. 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:

    • If a handoff document path was provided as a parameter, skip the default message
    • Immediately read the handoff document FULLY
    • Immediately read any research or plan documents that it links to under thoughts/shared/plans or thoughts/shared/research. do NOT use a sub-agent to read these critical files.
    • Begin the analysis process by ingesting relevant context from the handoff document, reading additional files it mentions
    • Then propose a course of action to the user and confirm, or ask for clarification on direction.

  2. If a ticket number (like ENG-XXXX) was provided:

    • run humanlayer thoughts sync to ensure your thoughts/ directory is up to date.
    • locate the most recent handoff document for the ticket. Tickets will be located in thoughts/shared/handoffs/ENG-XXXX where ENG-XXXX is the ticket number. e.g. for ENG-2124 the handoffs would be in thoughts/shared/handoffs/ENG-2124/. List this directory's contents.
    • There may be zero, one or multiple files in the directory.
    • If there are zero files in the directory, or the directory does not exist: tell the user: "I'm sorry, I can't seem to find that handoff document. Can you please provide me with a path to it?"
    • If there is only one file in the directory: proceed with that handoff
    • If there are multiple files in the directory: using the date and time specified in the file name (it will be in the format YYYY-MM-DD_HH-MM-SS in 24-hour time format), proceed with the most recent handoff document.
    • Immediately read the handoff document FULLY
    • Immediately read any research or plan documents that it links to under thoughts/shared/plans or thoughts/shared/research; do NOT use a sub-agent to read these critical files.
    • Begin the analysis process by ingesting relevant context from the handoff document, reading additional files it mentions
    • Then propose a course of action to the user and confirm, or ask for clarification on direction.

  3. If no parameters provided, respond with:

I'll help you resume work from a handoff document. Let me find the available handoffs.

Which handoff would you like to resume from?

Tip: You can invoke this command directly with a handoff path: `/resume-handoff `thoughts/shared/handoffs/ENG-XXXX/YYYY-MM-DD_HH-MM-SS_ENG-XXXX_description.md`

or using a ticket number to resume from the most recent handoff for that ticket: `/resume-handoff ENG-XXXX`

Then wait for the user's input.

Process Steps​

Step 1: Read and Analyze Handoff​

  1. Read handoff document completely:

    • Use the Read tool WITHOUT limit/offset parameters
    • Extract all sections:
      • Task(s) and their statuses
      • Recent changes
      • Learnings
      • Artifacts
      • Action items and next steps
      • Other notes

  2. Spawn focused research tasks: Based on the handoff content, spawn parallel research tasks to verify current state:

    Task 1 - Gather artifact context:
    Read all artifacts mentioned in the handoff.
    1. Read feature documents listed in "Artifacts"
    2. Read implementation plans referenced
    3. Read any research documents mentioned
    4. Extract key requirements and decisions
    Use tools: Read
    Return: Summary of artifact contents and key decisions

  3. Wait for ALL sub-tasks to complete before proceeding

  4. Read critical files identified:

    • Read files from "Learnings" section completely
    • Read files from "Recent changes" to understand modifications
    • Read any new related files discovered during research

Step 2: Synthesize and Present Analysis​

  1. Present comprehensive analysis:

    I've analyzed the handoff from [date] by [researcher]. Here's the current situation:

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

    **Key Learnings Validated:**
    - [Learning with file:line reference] - [Still valid/Changed]
    - [Pattern discovered] - [Still applicable/Modified]

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

    **Artifacts Reviewed:**
    - [Document 1]: [Key takeaway]
    - [Document 2]: [Key takeaway]

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

    **Potential Issues Identified:**
    - [Any conflicts or regressions found]
    - [Missing dependencies or broken code]

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

  2. Get confirmation before proceeding

Step 3: Create Action Plan​

  1. Use TodoWrite to create task list:

    • Convert action items from handoff into todos
    • Add any new tasks discovered during analysis
    • Prioritize based on dependencies and handoff guidance

  2. Present the plan:

    I've created a task list based on the handoff and current analysis:

    [Show todo list]

    Ready to begin with the first task: [task description]?

Step 4: Begin Implementation​

  1. Start with the first approved task
  2. Reference learnings from handoff throughout implementation
  3. Apply patterns and approaches documented in the handoff
  4. Update progress as tasks are completed

Guidelines​

  1. Be Thorough in Analysis:

    • Read the entire handoff document first
    • Verify ALL mentioned changes still exist
    • Check for any regressions or conflicts
    • Read all referenced artifacts

  2. Be Interactive:

    • Present findings before starting work
    • Get buy-in on the approach
    • Allow for course corrections
    • Adapt based on current state vs handoff state

  3. Leverage Handoff Wisdom:

    • Pay special attention to "Learnings" section
    • Apply documented patterns and approaches
    • Avoid repeating mistakes mentioned
    • Build on discovered solutions

  4. Track Continuity:

    • Use TodoWrite to maintain task continuity
    • Reference the handoff document in commits
    • Document any deviations from original plan
    • Consider creating a new handoff when done

  5. Validate Before Acting:

    • Never assume handoff state matches current state
    • Verify all file references still exist
    • Check for breaking changes since handoff
    • Confirm patterns are still valid

Common Scenarios​

Scenario 1: Clean Continuation​

  • All changes from handoff are present
  • No conflicts or regressions
  • Clear next steps in action items
  • Proceed with recommended actions

Scenario 2: Diverged Codebase​

  • Some changes missing or modified
  • New related code added since handoff
  • Need to reconcile differences
  • Adapt plan based on current state

Scenario 3: Incomplete Handoff Work​

  • Tasks marked as "in_progress" in handoff
  • Need to complete unfinished work first
  • May need to re-understand partial implementations
  • Focus on completing before new work

Scenario 4: Stale Handoff​

  • Significant time has passed
  • Major refactoring has occurred
  • Original approach may no longer apply
  • Need to re-evaluate strategy

Example Interaction Flow​

User: /resume-handoff specification/feature/handoffs/handoff-0.md
Assistant: Let me read and analyze that handoff document...

[Reads handoff completely]
[Spawns research tasks]
[Waits for completion]
[Reads identified files]

I've analyzed the handoff from [date]. Here's the current situation...

[Presents analysis]

Shall I proceed with implementing the webhook validation fix, or would you like to adjust the approach?

User: Yes, proceed with the webhook validation
Assistant: [Creates todo list and begins implementation]

Action Policy​

<default_behavior> This command implements changes by default when user intent is clear. Proceeds with:

  • Code generation/modification
  • File creation/updates
  • Configuration changes
  • Git operations (if applicable)

Provides concise progress updates during execution. </default_behavior>

After execution, verify: - Files created/modified as intended - Code compiles/tests pass (if applicable) - Git changes committed (if applicable) - Next recommended step provided

Success Output​

When handoff resume completes:

✅ COMMAND COMPLETE: /resume-handoff
Handoff: <path-or-ticket>
Date: YYYY-MM-DD
Tasks Identified: N
Artifacts Read: M
Status: Ready to proceed
Next Action: <recommended-action>

Completion Checklist​

Before marking complete:

  • Handoff document read fully
  • Linked plans/research read
  • Current state verified
  • Analysis presented
  • Action plan created

Failure Indicators​

This command has FAILED if:

  • ❌ Handoff document not found
  • ❌ No ticket number or path provided
  • ❌ Linked documents missing
  • ❌ State diverged significantly

When NOT to Use​

Do NOT use when:

  • Starting fresh work (no handoff exists)
  • Handoff is too stale (major refactoring since)
  • Simple continuation (no context needed)

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Skip artifact readingMissing contextRead all linked docs
Assume current stateDiverged codebaseVerify changes exist
Start without confirmationWrong directionGet user buy-in

Principles​

This command embodies:

  • #7 No Action Without Understanding - Read handoff fully
  • #5 No Assumptions - Verify current state

Full Standard: CODITECT-STANDARD-AUTOMATION.md