---
name: handoff-update-eb7f8f3d8907
description: "Update an existing handoff document with current session progress. Applies section-specific merge rules: append-only for Work Done (never deletes history), replace for Status and Next Steps, merge for Files and Discoveries. Falls back to creating a new handoff if no source file is found."
argument-hint: "[handoff-file-path]"
effort: low
disable-model-invocation: true
---

Update an existing handoff document with this session's progress.

## Step 1: Resolve the handoff file

Determine which file to update, in this priority order:

1. If `$ARGUMENTS[0]` was provided, use it as the file path.
2. If this session was started via `/handoff:resume`, look in conversation history for the argument that was passed to it.
3. If neither is found, fall back to creating a new file: `claudedocs/handoffs/handoff_YYYYMMDD_HHMMSS.md`. Inform the user that no existing handoff was found.

## Step 2: Read the existing file

Read the resolved file completely. Parse all sections as the baseline for the merge.

## Step 3: Apply section merge rules

Rewrite the file with updated content using these merge rules:

| Section | Rule | Notes |
|---------|------|-------|
| **Task** | Keep original | Update only if scope fundamentally changed |
| **Scope** | Keep or refine | Preserve exclusions, acceptance, authorization, and ownership; record a new contract revision for material changes |
| **Files** | Merge | Add new files touched in this session. Keep originals. Use paths and symbols; include lines only when verified at the recorded revision |
| **Discoveries** | Append | Add new findings below existing list. Never remove prior discoveries |
| **Work Done** | **Append only** | Add new completed items below existing list. Never remove entries. Include commit hashes |
| **Status** | **Replace** | Record the observed revision and time, checks and their scope, blockers, and next owner; distinguish task, run, and acceptance state |
| **Next Steps** | **Replace** | Write the updated actionable checklist |
| **Code** | Update | Replace with the most relevant snippets from the current state |

**The append-only rule for Work Done is strict.** Even if a previous entry describes work that was later revised, keep it. The history records prior claims; live evidence determines what is currently true. Append a correction with its evidence instead of removing the old entry.

## Step 4: Confirm

After saving, confirm:
- File path updated
- How many new Work Done items were added
- The updated Status (one line)
- How many Next Steps remain

---

> This command implements the Handoff Triad pattern documented in this guide's Session Handoff Pattern section.
> Template inspired by [Packmind's handoff commands](https://github.com/PackmindHub/packmind) (Apache 2.0).


---
Source attribution: FlorianBruniaux
Original project: https://github.com/FlorianBruniaux/claude-code-ultimate-guide
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 Gabriel Moreira

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: FlorianBruniaux
Original project: https://github.com/FlorianBruniaux/claude-code-ultimate-guide
Attribution basis: Upstream repository explicitly recorded in package mirror path

Fields of work: Operations, Project & Program Management
Roles: Business Process Analyst, Operations Manager, Project Manager
Specialties: Specialty not specified
Tools: Tool not specified
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 5c302793c5dd50b17c3a299bdc7c6026292c64603deaf6cb487c9659dc72662e