# Technical handoff template for unfinished engineering work

Canonical: https://githtml.com/guides/technical-handoff-document-template
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

A technical handoff should let another engineer continue from a known state. Record the objective, current revision, completed work, failed attempts, open questions, and next safe step. Distinguish observations from guesses, identify relevant access boundaries, and name who owns the work after the handoff is accepted.

## Capture state instead of retelling the week

Start with the outcome the work is trying to achieve and the exact point where progress stopped. Mention local-only changes or unpublished artifacts if they matter, without implying they are available in the shared repository. An illustrative handoff might say that a parser change is implemented in a branch but its integration behavior remains unverified. That is more useful than a chronological diary. Include commands actually run and their results, while keeping credentials and private logs out of the shared document. A handoff should reduce reconstruction, not merely show activity.

## Preserve negative evidence and uncertainty

Record the hypotheses that were tested and the observations that ruled them out. Google's troubleshooting guidance notes the value of careful investigation notes; a handoff benefits from the same discipline. If a check was inconclusive, explain why rather than marking it failed. Link source files at the relevant revision and name any environment difference that could affect reproduction. For a design question, state the options and who must decide. Avoid assigning the next engineer a risky action without the required context or authority.

1. Current state: identify what is saved, shared, reviewed, and still local.
2. Open issue: separate a known failure from an untested hypothesis.
3. Next step: propose the smallest safe action that can reduce uncertainty.

## Make acceptance and ownership explicit

Name the receiving role and the expected confirmation so the handoff does not disappear into an unread document. Put urgent constraints and blocked dependencies near the top. Explain what can proceed without additional access and what requires the relevant owner. Include links to authoritative trackers rather than duplicating every task status in prose. A static HTML handoff can be convenient for mobile reading, but its date and revision should remain visible. If work continues after export, update the snapshot or point clearly to the current record.

## Sources and further reading

- [Google SRE: Effective Troubleshooting](https://sre.google/sre-book/effective-troubleshooting/)
- [GitHub Docs: Getting permanent links to files](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files)

## Related guides

- [Test strategy template organized around product risk](https://githtml.com/guides/test-strategy-document-template)
- [Performance investigation report template with reproducible evidence](https://githtml.com/guides/performance-investigation-report-template)
- [Data dictionary template with meaning, ownership, and lifecycle](https://githtml.com/guides/data-dictionary-template)
- [Dependency upgrade review template for compatibility decisions](https://githtml.com/guides/dependency-upgrade-review-template)

Editorial approach: https://githtml.com/guides/about