Session Review

---
name: session-review
description: Generate a structured session summary for cross-session continuity. Captures key decisions, hypotheses, partial work, and knowledge references. Output is written to .Codex/session-handoff.json for the next session to load automatically.
argument-hint: "[optional: focus area or notes]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash, Write
---

Generate a structured session summary for cross-session continuity.

## Context

$ARGUMENTS

## Loop Building Blocks

| Loop | Purpose | Reference |
|------|---------|-----------|
| Consistency Check | Validate session summary against evidence | @loops/refinement/consistency-check.md |
| Documentation | Generate structured session review | @loops/authoring/documentation.md |

See @loops/README.md for the full loop library.

## Workflow

### Phase 1: Gather Session State (Observe)

1. Run `git log --oneline -20` to see recent commits this session
2. Run `git status` to see uncommitted work
3. Run `git diff --stat` to see scope of changes
4. Check `.Codex/state/memory-calibration.json` for pattern detection state
5. Read MEMORY.md for any updates made this session

### Phase 2: Synthesize Session Context (Orient)

From the gathered data, identify:

1. **Key Decisions**: What architectural or design choices were made and why
2. **Open Hypotheses**: What questions remain unanswered, what investigations are pending
3. **Partial Work**: What was started but not finished, with enough context to resume
4. **Knowledge Discovered**: New patterns, gotchas, or insights worth preserving
5. **Blocked Items**: What's blocked and on what
6. **Next Steps**: What the next session should prioritize

### Phase 3: Write Session Handoff (Act)

Write the session summary to `.Codex/session-handoff.json` (single file, overwritten each time) using this schema:

```json
{
  "version": "1.0.0",
  "session_id": "<from git>",
  "timestamp": "<ISO 8601>",
  "branch": "<current git branch>",
  "duration_estimate": "<approximate session duration>",
  "summary": "<1-2 sentence summary of what happened>",
  "key_decisions": [
    {
      "decision": "<what was decided>",
      "reasoning": "<why>",
      "alternatives_considered": ["<alt1>", "<alt2>"],
      "files_affected": ["<file1>", "<file2>"]
    }
  ],
  "hypotheses": [
    {
      "hypothesis": "<what's being investigated>",
      "evidence_for": ["<supporting evidence>"],
      "evidence_against": ["<counter evidence>"],
      "next_test": "<what to try next>"
    }
  ],
  "partial_work": [
    {
      "description": "<what was started>",
      "status": "<how far along>",
      "resume_from": "<specific file:line or commit to resume from>"
    }
  ],
  "knowledge_references": [
    {
      "store": "<MEMORY.md | Thoughtbox | git>",
      "reference": "<specific entity/issue/commit>",
      "relevance": "<why the next session needs this>"
    }
  ],
  "blocked_items": [
    {
      "item": "<what's blocked>",
      "blocker": "<what's blocking it>",
      "workaround": "<if any>"
    }
  ],
  "failed_approaches": [
    {
      "what": "<what was tried>",
      "why": "<why it failed>",
      "lesson": "<what to do instead>"
    }
  ],
  "next_priorities": ["<priority 1>", "<priority 2>", "<priority 3>"],
  "warnings": ["<things the next session should watch out for>"]
}
```

### Phase 4: Verify and Report (Decide)

1. Verify the handoff file was written successfully
2. Print a human-readable summary to the console
3. If there are uncommitted changes, warn about them

## Output

Present a concise summary:

```
## Session Handoff Written

File: .Codex/session-handoff.json
Branch: {branch}
Commits this session: {N}
Open hypotheses: {N}
Partial work items: {N}

### Top 3 Priorities for Next Session
1. {priority}
2. {priority}
3. {priority}

### Warnings
- {warning}
```