summarize-session

name	summarize-session
description	Use for a read-only progress snapshot without committing, pushing, or closing anything
allowed-tools	Read, Bash, Glob, Grep

Summarize Session: $ARGUMENTS

Generate a comprehensive session summary for task $ARGUMENTS. This is a standalone command that ONLY generates the summary - it does NOT commit, push, close the task, or make any changes.

1. Gather Context

If Linear MCP is available, call get_issue(id=$ARGUMENTS, includeRelations=true) to get task details (title, status, priority, description, blockers, blocked-by).

If Linear MCP is not available, skip task context — use plan file or conversation context instead.

git status
git log --oneline -10
git diff --stat HEAD~5 2>/dev/null || git diff --stat
pwd

2. Identify Changed Files

# Files changed in recent commits
git diff --name-only HEAD~5 2>/dev/null || git diff --name-only

# New files created
git diff --name-only --diff-filter=A HEAD~5 2>/dev/null

# Files modified
git diff --name-only --diff-filter=M HEAD~5 2>/dev/null

Read key files to understand what was implemented.

3. Check Test Status

# Get test counts
uv run pytest --collect-only -q 2>/dev/null | tail -5
# Or
pnpm test 2>/dev/null | tail -10

4. Check Unblocked Tasks

If Linear MCP is available, call get_issue(id=$ARGUMENTS, includeRelations=true) and check the blocks array — those are tasks this one unblocks when completed.

If Linear MCP is not available, note "No dependency info available."

5. Re-Read Original Task Spec

CRITICAL: Before writing the session summary, re-read the original task specification to accurately identify divergences.

If Linear MCP is available, call get_issue(id=$ARGUMENTS) and read the description field.

If not, check docs/plans/ for the relevant plan file section.

Save this output mentally - you'll compare it against your implementation when writing the SPEC DIVERGENCES section. Don't rely on memory; divergences are easy to miss without explicit comparison.

6. Generate Session Summary

IMPORTANT: Output a detailed session summary for orchestrating agents. This summary will be consumed by a coordinating agent to track progress across multiple parallel work sessions. Be verbose and thorough.

Use this exact format:

===============================================
SESSION SUMMARY: <Task Title>
===============================================

TASK OVERVIEW
-------------
ID: $ARGUMENTS
Title: <title from task>
Status: <current status>
Priority: <priority from task>
Labels: <labels from task>

INTENT & SCOPE
--------------
What this task set out to accomplish:
<2-3 sentences explaining the goal of this task in plain language. What problem does it solve? Why was it needed?>

IMPLEMENTATION SUMMARY
----------------------
<Narrative description of what was built. Write 3-5 sentences explaining the approach taken, key design decisions, and how the pieces fit together. An orchestrating agent should be able to understand the work without reading the code.>

FILES CREATED
-------------
<For each new file, include path and brief description>

1. <path/to/file.py>
   Purpose: <what this file does>
   Key components: <main classes/functions>
   Lines: <approximate line count>

2. <path/to/file.py>
   ...

FILES MODIFIED
--------------
<For each modified file, explain what changed and why>

1. <path/to/file.py>
   Changes: <what was added/changed>
   Reason: <why this change was needed>

2. <path/to/file.py>
   ...

TESTS
-----
New tests added: <count>
Total tests now passing: <count>
Test file(s): <path(s)>

Key test coverage:
- <what scenarios are tested>
- <what edge cases are covered>

DOCUMENTATION UPDATED
---------------------
<List each doc file updated with a brief note on what changed, or "None required">

GIT ACTIVITY
------------
Branch: <branch-name>
Commits: <count in this session>
PR: <URL or "Not created">
Merged to: <target branch or "Not merged">
Model: <opus|sonnet|inherited>

TASK STATUS
-----------
Task closed: <Yes/No>
Reason: <close reason or "Still in progress">

SPEC DIVERGENCES
----------------
Compare your implementation against the original task description (from Linear issue or plan file). Document ANY differences between what was specified and what was actually built. Be explicit and thorough - the orchestrator relies on this to keep the task board accurate.

Format each divergence as:

**Divergence N: <brief title>**
- Specified: <what the task description said to do>
- Implemented: <what was actually built>
- Reason: <why the change was necessary - technical constraint, better approach discovered, dependency issue, etc.>
- Impact: <what downstream tasks or specs need updating>

If implementation matched spec exactly, state: "None - implementation matches specification."

Examples of divergences to document:
- Different file structure than specified
- Added/removed features from original scope
- Changed API contracts or schemas
- Used different libraries or approaches
- Deferred functionality to follow-up tasks
- Discovered requirements that weren't in the spec

FOLLOW-UP ISSUES CREATED
------------------------
<List any new issues created during this session (Linear or otherwise), or "None">

DEPENDENCIES UNBLOCKED
----------------------
The following tasks were blocked by this task and can now proceed:
<List each task ID and title, or "None">

ARCHITECTURAL NOTES
-------------------
<Any important technical decisions, patterns established, or constraints discovered that future work should be aware of. This helps maintain consistency across parallel agent sessions.>

HANDOFF CONTEXT
---------------
<What should the next agent or session know? Include:
- Any gotchas or things that didn't work as expected
- Assumptions made that might need revisiting
- Suggested next steps if continuing related work
- Dependencies on external systems or APIs
- Performance considerations if any>

===============================================
END SESSION SUMMARY
===============================================

This format ensures orchestrating agents have full context to coordinate parallel work and make informed decisions about task assignment.

7. Persist Summary to Disk

Write the summary to a file so orchestrating agents can read it directly from disk.

# Get project root (handles worktrees correctly)
PROJECT_ROOT=$(git rev-parse --show-toplevel)

# Create directory if needed
mkdir -p "$PROJECT_ROOT/docs/session_summaries"

# Add to .gitignore if not present
if ! grep -q "^docs/session_summaries/$" "$PROJECT_ROOT/.gitignore" 2>/dev/null; then
  echo "docs/session_summaries/" >> "$PROJECT_ROOT/.gitignore"
fi

# Generate filename with timestamp
TIMESTAMP=$(date +%y%m%d-%H%M%S)
SUMMARY_FILE="$PROJECT_ROOT/docs/session_summaries/$ARGUMENTS_${TIMESTAMP}.txt"

Write the summary content using a heredoc:

cat > "$SUMMARY_FILE" <<'SUMMARY_EOF'
<paste the full session summary content here>
SUMMARY_EOF

echo "Summary written to: $SUMMARY_FILE"

Important: The summary file allows orchestrators to asynchronously review completed work without needing the worker session to remain active.

8. Copy to Clipboard (Optional)

Use AskUserQuestion to offer copying the summary to clipboard:

Question: "Copy session summary to clipboard?"

• Options: "Yes, copy to clipboard" / "No, skip"
• Header: "Clipboard"

If the user selects "Yes, copy to clipboard":

cat "$SUMMARY_FILE" | pbcopy
echo "Summary copied to clipboard"

This avoids clipboard conflicts when multiple worker sessions complete simultaneously.