---

name: session-handoff description: "Generate Sarah Briefs and maintain STATUS/TODO files for session continuity. Use for: (1) End-of-session documentation, (2) STATUS.md updates, (3) TODO.md task management, (4) Session context preservation. Triggers: Sarah Brief, brief, handoff, session end, status update, TODO update, documentation, end session."

Session Handoff Skill

Purpose

Ensure session continuity by generating structured documentation at the end of significant work sessions. This skill codifies the Sarah Brief format and STATUS/TODO update patterns.

Memory Framework Context

Session handoff serves Layer 4 of the Prometheus Memory Framework:

CopyLayer 1: Constitution & Architecture (Immutable Authority)
Layer 2: Context Packages (Task-specific anchoring)
Layer 3: PKE Retrieval (Structured long-term knowledge)
Layer 4: Logs & Trace History (Temporal grounding)  ← THIS LAYER
Layer 5: Local State (Ephemeral)

Document Types

1. Sarah Brief

Purpose: Comprehensive session report for Controller (Sarah) review

Location: docs/briefs/SARAH_BRIEF_{topic}_{date}.md

Naming Convention:

• SARAH_BRIEF_ prefix (mandatory)
• {topic} - kebab-case description of work focus
• _{date} - YYYY-MM-DD format
• .md extension

Examples:

• SARAH_BRIEF_scalar-bidirectional-sync_2025-01-14.md
• SARAH_BRIEF_format-page-implementation_2025-12-30.md
• SARAH_BRIEF_status-update_2025-01-09.md

---

Sarah Brief Template

Copy# Sarah Brief: [Title]

**Date:** [YYYY-MM-DD]
**Session:** Claude Code (CC)
**Type:** [Feature Implementation Report | Status Update | Bug Fix | Refactor]
**Branch:** `[branch-name]`
**Commit:** `[short-hash]`

---

## Executive Summary

[2-3 sentences summarizing what was accomplished and why it matters]

---

## Problem Statement

[What issue/requirement drove this work?]
[Root cause if applicable]

---

## Solution Implemented

### [Solution Name]

[Description of approach]

| Component | Change | Purpose |
|-----------|--------|---------|
| [File/Function] | [What changed] | [Why] |

### Data Flow (if applicable)

[ASCII diagram of data flow]

Copy
---

## Files Modified

### Core Changes ([count] files, +[added] / -[removed] lines)

| File | Lines Changed | Impact |
|------|---------------|--------|
| [file.jsx] | +[n] | [Description] |

### New Components Created

| Component | Purpose |
|-----------|---------|
| [Component.jsx] | [What it does] |

---

## Testing Results

### Automated Testing ([Framework])

| Test | Status | Notes |
|------|--------|-------|
| [Test name] | PASS/FAIL | [Details] |

### Manual Testing Recommended

[List of things to verify manually]

---

## Commit Details

commit [hash] Author: [User] Date: [Date]

[Full commit message]

Copy
---

## Technical Debt Addressed

| Item | Status | Notes |
|------|--------|-------|
| [Debt item] | RESOLVED/DEFERRED | [Details] |

---

## Outstanding Items

### From Previous Sessions

| Item | Status | Priority |
|------|--------|----------|
| [Item] | [Status] | [Priority] |

### New Items

| Item | Priority | Notes |
|------|----------|-------|
| [Item] | [Priority] | [Details] |

---

## Session Metrics

| Metric | Value |
|--------|-------|
| Files Modified | [n] |
| Lines Added | +[n] |
| Lines Removed | -[n] |
| Net Change | +/-[n] |
| New Components | [n] |
| Tests Run | [n] |

---

## Recommendations

### Immediate

1. [Action item]

### Short-Term

1. [Action item]

### Medium-Term

1. [Action item]

---

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk] | LOW/MEDIUM/HIGH | LOW/MEDIUM/HIGH | [Mitigation] |

---

## Session Handoff Notes

### Key Context for Next Session

1. [Important context point]

### Files Requiring Attention

- [file.jsx] - [Reason]

---

*Brief prepared by Claude Code for Controller (Sarah) review.*
*Report generated: [Date]*

---

2. STATUS.md Update

Purpose: Maintain authoritative system state

Location: docs/STATUS.md

Update Triggers:

• End of significant session
• Component state change
• Major commit
• Phase completion

STATUS.md Sections to Update

Update Pattern

Copy## Recent Changes (Last 5 Sessions)

| Date | Session | Key Changes |
|------|---------|-------------|
| [NEW DATE] | CC | [NEW CHANGES] |
| [Previous] | CC | [Previous changes] |
...

Rule: Keep only last 5 sessions; archive older to briefs.

---

3. TODO.md Update

Purpose: Track active task backlog

Location: docs/TODO.md

Update Triggers:

• Task completed → Move to "Completed"
• New task identified → Add to "Active" or "Backlog"
• Priority change → Reorder items
• Task blocked → Note blocker

TODO.md Sections

Task Movement Pattern

Copy## Active (Current Focus)

| Task | Priority | Status | Notes |
|------|----------|--------|-------|
| [Task moving to completed] | HIGH | **COMPLETE** | [Notes] |

↓ Move to ↓

## Completed (Recent)

| Task | Completed | Notes |
|------|-----------|-------|
| [Task] | [Date] | [Notes] |

---

Handoff Checklist

Before ending a significant session:

Documentation

• Create Sarah Brief if substantial work done
• Update STATUS.md Quick Summary
• Update STATUS.md Component Status (if changed)
• Add entry to Recent Changes
• Update Session Handoff Notes

TODO Management

• Mark completed tasks as COMPLETE
• Add new tasks discovered during session
• Add entry to Task Log
• Review priorities (still correct?)

Git State

• All work committed (or documented why not)
• Commit messages descriptive
• Branch state documented

Context Preservation

• Key decisions documented
• Files requiring attention noted
• Blockers/risks identified
• Next steps clear

---

Automated Generation (Future)

Proposed Command

Copy# Generate Sarah Brief from git state
python scripts/generate_brief.py \
  --topic "scalar-sync" \
  --type "feature" \
  --since "HEAD~5"

# Update STATUS.md
python scripts/update_status.py \
  --component "Design - Scalar" \
  --state "ENHANCED" \
  --notes "Bidirectional sync implemented"

# Update TODO.md
python scripts/update_todo.py \
  --complete "SCALAR Bidirectional Sync" \
  --add "Full CRUD testing for SCALAR" \
  --priority MEDIUM

Brief Data Sources

---

Quality Standards

Sarah Brief Quality

STATUS.md Quality

TODO.md Quality

---

Brief Types

---

File Locations

---

See Also

• docs/memory-framework.md - Memory architecture context
• /prometheus-testing - Testing doctrine (SOC reports)
• CLAUDE_PROTOCOL.md - Task execution protocol
• docs/briefs/ - Historical briefs for reference