domains / agent-tooling / session-handoff / session-handoff

session-handoff

Skill card

combined

The two skills solve the same problem but prescribe different, non-interchangeable procedures. The softaworks copy is a tool-driven workflow that relies on specific Python scripts (create_handoff.py, validate_handoff.py, etc.) and a specific storage path (.claude/handoffs/). The sickn33 copy is a manual, principle-driven workflow that emphasizes git auditing, separating facts from speculation, and mandating owners for open loops, without relying on external scripts. Combining them is necessary to capture both the automated scaffolding/validation approach and the rigorous manual content requirements.

Repositories

Other copies

Combined skill

# Session Handoff

## When to Use
- Context window is approaching capacity (>60%).
- Before running /clear or /compact.
- When switching tasks or ending a session.
- After substantial work (5+ file edits, complex debugging).

## Workflow: Creating a Handoff

### 1. Audit State
- Run `git status -s` and `git diff --stat` to identify modified, untracked, and staged files.
- Do not rely on chat memory for file state.

### 2. Generate Scaffold (Optional)
- If using the softaworks toolkit, run: `python scripts/create_handoff.py [task-slug]`
- This creates a pre-filled document in `.claude/handoffs/`.
- If not using the toolkit, create a new markdown file in a designated handoff directory.

### 3. Populate Content
Fill in the following sections, adhering to these rules:

**Goal & Current State**
- Define the original objective in one sentence.
- Document what is verified as working (with passing test commands) vs. what is partial.
- Label untested assumptions as `[UNVERIFIED]`.

**Decisions Made**
- List architectural choices with concrete rationale.
- Explicitly record discarded paths (negative decisions) to prevent re-attempting failed solutions.

**Files Touched**
- List key file paths, functions, and classes modified.
- Use exact workspace identifiers, not pseudocode.

**Open Loops**
- List unaddressed edge cases, failing tests, and deferred tasks.
- **Mandatory:** Every open loop must specify an owner (`Human` or `Agent`) and a deterministic verification criteria.

**Immediate Next Action**
- Specify a single, atomic, unambiguous instruction for the next agent's first turn.
- Ban vague continuations like "continue working on auth." State the exact file and symbol.

### 4. Validate
- If using the softaworks toolkit, run: `python scripts/validate_handoff.py <handoff-file>`
- Ensure no `[TODO]` placeholders remain.
- Ensure no secrets (API keys, passwords) are present.
- If using a manual workflow, self-check against the operating rules above.

### 5. Confirm
- Report the handoff location and a summary of captured context to the user.

## Workflow: Resuming from a Handoff

### 1. Locate Handoff
- List available handoffs (e.g., `python scripts/list_handoffs.py` or check the handoff directory).

### 2. Check Staleness
- If using the toolkit, run: `python scripts/check_staleness.py <handoff-file>`
- Manually verify if the git branch and recent commits align with the handoff context.

### 3. Load Context
- Read the handoff document completely.
- If the handoff is part of a chain, read the linked predecessor for full context.

### 4. Verify & Begin
- Verify that blockers mentioned in the handoff are still relevant.
- Start with the "Immediate Next Action" item.
- Update the handoff or create a new chained handoff as work progresses.