handoff

Files (1)

• SKILL.md

SKILL.md (first lines)

# Session Handoff

Write a concise continuation packet for the next session. Git history explains what changed; `HANDOFF.md` explains what is still true, what is unresolved, and where to resume.

## When to invoke

- Pausing mid-task.
- Near context limit.
- Passing work to another developer or agent.
- Ending a long session with open decisions.
- After trying approaches that should not be repeated.
- Before switching repositories or priorities.

## When not to invoke

- Trivial sessions with no open state.
- Work fully committed, pushed, verified, and obvious from the commit message.
- Early brainstorming with no repo state to preserve.

## Process

### 1. Snapshot repository state

Use compact commands:

```bash
git rev-parse --short HEAD 2>/dev/null
git branch --show-current 2>/dev/null
git status --short
git stash list
git log --oneline -15
git diff --stat HEAD 2>/dev/null
git diff --stat --cached 2>/dev/null
```

Capture branch, HEAD SHA, working tree status, stashes, recent commits, staged/unstaged diff stats, and untracked files.

### 2. Read resume context

Read any present files:

- `implementation_plan.md`
- `repo_orientation.md`
- `HANDOFF.md`
- `AGENTS.md`
- `CLAUDE.md`
- `README.md`
- recent ADRs under `docs/adr/` or `adr/`

Do not paste secrets, controlled data, raw environment values, customer names, or internal hostnames into the handoff.

### 3. Check lightweight gates

Use existing repo evidence only. Do not invent commands.

Capture commands and result summaries for relevant gates:

- test
- build
- lint/typecheck/format
- security scan
- release/deploy dry run

If no command is documented, write `Not documented`. If a command is too expensive or unsafe to run, write `Not run` and explain why.

### 4. Capture decisions and dead ends

Record:

- Decisions made this session and why.
- Open decisions or user input needed.
- Approaches tried and rejected.
- Files changed or created.
- Follow-up risks and cleanup needs.

This section is what prevents the next session from repeating old work.

## Output

Write or update `HANDOFF.md` at the repo root unless the user asks for chat-only output.

Use this structure:

```markdown
# Handoff — <branch> @ <short-sha>

> Generated: <YYYY-MM-DD HH:MM UTC>
> Stale when branch or HEAD changes from this value.

## Current State
- Branch:
- HEAD:
- Working tree:
- Stashes:

## What Changed
- <commits, files, or functional changes from this session>

## Mid-Flight Work
- <uncommitted files, incomplete tasks, scratch files, TODOs>

## Decisions Made
- <decision + rationale>

## Tried and Rejected
- <approach + why it failed or was rejected>

## Open Decisions
- Decide: <question> — current leaning: <option/reason>

## Validation State
| Gate | Status | Evidence |
|---|---|---|
| `<command>` | PASS / FAIL / NOT RUN / N/A | <short output or reason> |

## Files to Read First
- `path/to/file` — why it matters

## Resume Steps

From tcbuilds/nautilus, MIT.

More from tcbuilds/nautilus