skill_issue

Patterns / Context

Context

Handoff summary between sessions

End long sessions with a compact state file, and start the next session from it instead of the full history.

The problem

Long sessions accumulate noise: dead ends, superseded decisions, large tool outputs. Context windows are finite, and even before they fill up, important details get buried. Starting fresh loses everything unless you capture it.

The pattern

Before ending (or when a session gets long), ask the agent to write a handoff file with the current state: what is done, what is in progress, decisions made and why, open problems, and the next concrete step. Review it, fix anything wrong, then start a new session with the rules file, the original brief and the handoff, nothing else.

The handoff should be written for a capable colleague who has never seen the conversation.

Template

Write HANDOFF.md for someone continuing this work with no access to this conversation.
Be concrete and brief. Use these sections:

## Goal
<the task, in one or two sentences>

## Done
- <completed item> (verified by: <command/check>)

## In progress
- <item> – current state, what's left

## Decisions
- <decision> – because <reason>. Rejected: <alternative> because <reason>.

## Known problems
- <bug / failing test / open question>

## Next step
<The single next action, specific enough to start immediately.>

## Pointers
- Key files: <paths>
- Commands: <how to run/test>

Do not include dead ends unless they explain a decision.

When not to use it