end-session

End Session Skill

Use this skill to close every development session properly and prepare handoff for the next session.

When to Use

• Completing any development session
• Before taking a break from the project
• After finishing a feature or task
• When context needs to be preserved for next session

Inputs

• Work completed during session
• Files modified
• Tests run and results
• Any blockers or issues encountered

Steps

1. Create Session Log

Create a new log file in session_logs/MM-DD-YYYY/N - Title.md where:

• Folder: MM-DD-YYYY (e.g., 02-11-2026)
• File: N - Title.md (e.g., 1 - Feature Implementation.md)
• N = Sequential number for that day (1, 2, 3...)
• Title = Concise description of session

Session log template:

# Session Log — YYYY-MM-DD (Session NN)

## TL;DR (≤5 lines)
- **Goal**: [What was the intended outcome]
- **Accomplished**: [What was completed]
- **Blockers**: [Any issues or blockers]
- **Next**: [What should happen next]
- **Branch**: [Feature branch name]

**Tags**: ["feature", "bugfix", "docs", "testing", etc.]

---

## Context
- **Started**: HH:MM
- **Ended**: HH:MM
- **Duration**: ~X hours
- **User Request**: [Original user request]

## Work Completed

### Files Modified
- `path/to/file1.py` - [What changed]
- `path/to/file2.py` - [What changed]

### Tests Added/Modified
- `tests/test_feature.py` - [New test cases]

### Commands Run
```bash
# Commands executed during session
uv run pytest
uv run ruff format .

Decisions Made

• [Key decision 1 and rationale]
• [Key decision 2 and rationale]

Issues Encountered

• [Issue 1 and resolution/workaround]
• [Issue 2 and status]

Next Steps

1. [Next action item]
2. [Next action item]
3. [Next action item]

Handoff Notes

• For next session: [Context needed]
• Open questions: [Unresolved questions]
• Dependencies: [Waiting on what?]

---

Session Owner: [AI tool used: Claude Code/Gemini/etc.] User: [User name if applicable]

### 2. Run Health Checks

Execute the health check workflow:

```bash
# Follow steps in:
cat .agent/workflows/health-check.md

If health check fails:

• Document the failure in session log
• Fix issues or note them for next session
• DO NOT commit broken code

3. Update Implementation Schedule

If tasks were completed:

• Open docs/implementation_schedule.md
• Update task status (mark completed tasks)
• Add new tasks if discovered
• Note any timeline impacts

4. Prepare Commit

DO NOT commit directly. Propose a commit message for user review:

# Proposed commit message format:
<type>: <short description>

<detailed description>
- What changed
- Why it changed
- Any breaking changes

Refs: session_logs/YYYY-MM-DD/NN.md

Commit types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• test: Test additions/changes
• refactor: Code refactoring
• chore: Maintenance tasks
• perf: Performance improvements

5. Document Handoff

Create handoff documentation for the next session:

What to document:

• Current state of work (completed, in-progress, blocked)
• Files to review first
• Known issues or technical debt
• Questions that need answering
• Recommended next steps

Where to document:

• Session log (Handoff Notes section)
• Implementation schedule (task notes)
• Code comments (for complex logic)

Validation

Before ending session, confirm:

• Session log created in session_logs/
• Health check passed (or failures documented)
• Implementation schedule updated if tasks completed
• Commit message proposed (not executed)
• Handoff notes documented
• All work saved and pushed to feature branch (if ready)

Common Mistakes to Avoid

1. Skipping session log — Every session needs a log
2. Not running health check — Always validate before closing
3. Committing without user approval — Propose, don't execute
4. Missing handoff notes — Next session needs context
5. Forgetting to update schedule — Keep schedule current

Health Check Failures

If .agent/workflows/health-check.md checks fail:

Linting failures:

uv run ruff check . --fix  # Auto-fix where possible
uv run ruff format .        # Format code

Test failures:

uv run pytest -vv           # Verbose output
uv run pytest --lf          # Re-run last failed

Document in session log:

• Which checks failed
• Why they failed
• What needs to be fixed
• Whether it's blocked or ready for next session

Session Log Location

Organize logs by date with descriptive titles:

session_logs/
├── 02-11-2026/
│   ├── 1 - Feature Implementation.md
│   ├── 2 - Bug Fix.md
│   └── 3 - Documentation Update.md
├── 02-12-2026/
│   └── 1 - Testing Session.md
└── TEMPLATE.md  # Template for new logs

Handoff Notes Template

Document these for the next session:

## Handoff Notes
- **Current state**: [What was accomplished/in-progress/blocked]
- **Last file edited**: [File path and line number]
- **Blockers**: [Any issues preventing progress]
- **Next priority**: [What should happen next]
- **Open questions**: [Unresolved questions]
- **Context needed**: [What next agent needs to know]

---

Links

• Context: .agent/CONTEXT.md
• Skills catalog: .agent/skills/CATALOG.md
• Agent guidance: .agent/AGENTS.md
• Implementation schedule: docs/implementation_schedule.md
• Start session: .agent/skills/start-session/SKILL.md
• Health check: .agent/workflows/health-check.md

---

Close properly. Document thoroughly. Prepare for handoff.