session-handoff

Session Handoff

This skill provides a structured process for producing a handoff document at the end of a session. It ensures the next session or teammate can resume without re-discovering what was done, what remains, and what decisions were made.

When to Use

• User says "done for now", "wrap up", "handoff", "pause", or "end session"
• Session reaches a natural completion point (PR ready, task deployed, review delivered)
• Multi-repo task completes (mandatory — always run handoff)
• Before switching to a different task in the same session

When NOT to Use

• Session consisted only of answering a question with no file modifications
• User explicitly says "no handoff needed" or "skip handoff"
• Task was a single-response answer that did not modify any files

Core Principles

Output File

Output file: .codex-handoff.md in repo root — always overwrite, never append.

Handoff Document Structure

## Handoff — [date]

### Status
[What was fully completed this session. Past tense. Specific.]

### In Progress
[Tasks started but not finished. Include exact stopping point and file/line if relevant.]

### Blocked
[What cannot proceed and why. Always include reason — never just "blocked".]

### Decisions Made
[Architectural or implementation decisions taken this session, with brief rationale.]

### Files Modified
[Every file touched. Format: `path/to/file.ts` — one-line description of change.]

### Next Steps
[Ordered list. Specific enough to act on without reading session history.]

### Open Questions
[Unresolved questions requiring human input or further research.]

### Observed Patterns
[NEW — see pattern extraction section below]

Writing Rules

• Use file paths, not folder names
• Use line numbers when describing exact stopping points
• Next Steps must be actionable by someone who was not in the session
• Do not mark anything complete if tests are failing or review is pending
• Include the Session Context Block from project-context when available