Methodology for Writing Handoff Documents

When to Write

• When a long-term task/large requirement is paused or wrapped up and needs to be handed over to another person (or Agent)
• When the user explicitly requests "write a handoff / handoff document / handoff.md"
• When the context window is about to be exhausted and progress needs to be saved to disk

Where to Place It

.agents/tasks/<task_name>/handoff.md

• <task_name>

  = task slug (in the same directory as plan.md/findings.md, e.g.,

  kdrive

  ).
• Do NOT place it in the root directory of

  .agents/tasks/

  (that is the task list area, not the document area).
• When there is a plan.md in the same directory, the handoff is the "external handoff version" and the plan is the "execution log version"; they are not interchangeable.

What to Write (Structure Template)

1. One-sentence Status: Whether it works now, and where it's stuck
2. Branch and Merge Discipline: Branch stack, MR order, retarget rules (top priority for readers)
3. Architecture Invariants: Constraints that must be memorized before modifying code (lock model, semantic red lines, protocol contracts)
4. Testing Infrastructure: How to run tests/simulations/E2E, and where the existing scaffolding is located
5. Environment Pitfalls: Records of issues encountered with permissions, CI, building, and deployment (lessons learned are the most valuable)
6. Known Boundaries and Roadmap: Uncompleted items, trigger conditions, and next-step candidates
7. How to Continue: Where to branch from, how to verify, and who to contact

Writing Principles

• Self-Contained: Readers can take over without prior context; do not reference "see the conversation above"
• Separate Invariants vs Volatile Information: Write down architecture constraints, pitfalls, and methods as-is; for volatile information such as MR status/scheduling/progress, specify the authoritative source + snapshot date (e.g., "MR status is subject to GitLab, snapshot taken on 2026-08-03") instead of copying statically
• Must Document Environment Pitfalls: Permissions, CI hooks, build workarounds—this is the most time-saving part of a handoff
• Be concise and direct; do not pile up history; the reader is the "next person to do the work", not a reviewer

Implementation Sequence

1. Write it into

   .agents/tasks/<task_name>/handoff.md

   (the home for task status)
2. If there is reusable domain knowledge (architecture invariants, environment pitfalls, discipline) in it, extract it into gizmo's

   skills/<domain>-dev/

   (SKILL.md entry + references/ for full storage); do not put the task status itself into a skill