Session Handoff Skill

Purpose

Large context windows degrade in instruction adherence, reasoning precision, and tool accuracy as token counts accumulate. Long sessions fill with superseded plans, aborted scratchpads, and repetitive error traces. Resetting to a fresh session restores performance, but discarding context blindly introduces state loss, hallucinated progress, and repeated mistakes.

The session-handoff skill standardizes how an agent snapshots active state. It translates ephemeral working memory into an actionable, verifiable bridge document for the next session.

When to Use This Skill

• Context usage approaches capacity (roughly >60%) and a reset is coming.
• Before running /clear or /compact in Claude Code, Cursor, or Codex.
• When switching tasks mid-session, or ending a coding session that another session (or agent) will continue.

Workflow: Ending a Session (6 Steps)

Run this sequence when an agent session reaches operational limits or when halting work:

1. Audit Git and Workspace State Run git status -s and git diff --stat to establish grounded reality. Never rely on chat memory for what was modified. Identify modified, untracked, and staged files.

2. Capture Goal State vs. Implemented Reality Define the original objective in one sentence. Document precisely what has been verified as working (with passing test commands or runtime checks) versus what remains partial or unverified.

3. Record Decisions Made and Discarded Paths List architectural and design choices committed during the session, along with the concrete rationale. Explicitly record negative decisions (approaches tried and discarded) to prevent the next agent from re-attempting failed solutions.

4. Catalog Files Touched and Relevant Symbols List key file paths, functions, classes, and schema definitions modified or referenced. Include line references where relevant.

5. Isolate Open Loops with Owners and Checks List all unaddressed edge cases, failing tests, deferred tasks, and environment constraints. Every open loop must specify who resolves it (Human or Agent) and how completion is verified.

6. Specify the Immediate Next Action Draft a single, atomic, unambiguous instruction for the next agent to execute on turn one. Do not provide a broad list; specify the exact command to run or file to edit first.

Operating Rules

• Separate Facts from Speculation: A test that passed is a fact; assuming code works because it compiled is speculation. Label untested assumptions explicitly as [UNVERIFIED].
• Mandate Owners and Verifications for Open Loops: Every open loop must state an owner (Human or Agent) and a deterministic verification criteria (e.g., pytest tests/auth/test_token.py:test_refresh_rotation passes).
• Ban Vague Continuations: Never write "continue working on auth" or "finish frontend components." State the exact symbol, file, and failure mode.
• Reference Real Workspace Identifiers: All references to code must use exact file paths and symbol names. Do not use generalized pseudocode descriptions.

Worked Example: Session Handoff Note

# Session Handoff: JWT Rotation Implementation

### Goal & Current State
- **Target Goal**: Implement refresh token rotation and revocation in the FastAPI auth service.
- **Current State**: Refresh token database migration applied and rotation endpoint created. Token generation and database persistence work. Revocation blacklist cache is not yet wired into the dependency validator.
- **Verification**: `pytest tests/test_auth_tokens.py` passes (4/4 tests).

### Decisions Made (With Reasons)
- **Used Redis for Token Revocation List**: Selected Redis over Postgres lookups for revoked JTI tokens to keep latency under 5ms on protected routes.
- **Rejected Stateless Refresh Tokens**: We initially evaluated sliding expiration in JWT claims without persistence, but discarded it because compromised tokens could not be revoked before natural expiry.
- **Token Format**: Chose UUIDv4 for `jti` claim to maintain compatibility with existing session storage schemas.

### Files Changed
- `src/services/auth.py`: Added `rotate_refresh_token(old_token: str)` function and Redis invalidation call.
- `src/models/tokens.py`: Added `RefreshTokenRecord` SQLModel table for tracking token families.
- `alembic/versions/20261005_add_token_families.py`: Migration creating `token_records` table.

…