Documenting Sessions

Overview

Create professional session summary documents that track development work, link related artifacts, and apply clear writing standards.

Core principle: Evidence-based session summaries with verifiable commit history and artifact links.

Announce at start: "I'm using the documenting-sessions skill to [operation]."

Session Document Template

Every session document uses this structure:

# Session YYYY-MM-DD: [Title]

**Date:** YYYY-MM-DD
**Status:** ✅ COMPLETE | ⚠️ IN PROGRESS | ❌ BLOCKED
**Related Handoffs:** [Links to handoff files]
**Related Plans:** [Links to plan files]
**Commits:** [N commits, branch info]

---

## Executive Summary
[2-3 sentences: what was accomplished]

## Work Completed
- Task 1
- Task 2
- Task 3

## Technical Details
[Implementation notes, decisions made]

## Next Steps
[What remains, blockers, follow-ups]

## Files Changed
[Key files modified/created]

Operations

Create Session

When: Starting a development session or documenting completed work.

Process:

1. Get information:

- Title (brief, descriptive) - Status (COMPLETE, IN PROGRESS, BLOCKED) - Related handoffs (paths to handoff files) - Related plans (paths to plan files)

1. Generate filename:

``python from datetime import date today = date.today().strftime('%Y-%m-%d') slug = title.lower().replace(' ', '-').replace('_', '-') filename = f"SESSION-{today}-{slug}.md" ``

1. Create file at: /docs/sessions/{filename}

1. Content structure:

```markdown # Session {today}: {Title}

Date: {today} Status: {statusemoji} {STATUS} Related Handoffs: {handofflinks} Related Plans: {plan_links} Commits: [To be updated]

## Executive Summary

[Summarize main accomplishment in 2-3 sentences]

## Work Completed

- [Task 1] - [Task 2] - [Task 3]

## Technical Details

[Implementation notes, architectural decisions, design choices]

## Next Steps

[Remaining work, blockers, follow-up tasks]

## Files Changed

[List key files that were created or modified] ```

1. Status emoji mapping:

- ✅ COMPLETE - ⚠️ IN PROGRESS - ❌ BLOCKED

1. Commit:

``bash git add docs/sessions/{filename} git commit -m "docs: create session summary for {title}" ``

Update Session

When: Adding work items, updating status, or recording commits.

Process:

1. Load session file

- Read existing content - Identify sections to update

1. Update work items:

- Add new items to "Work Completed" section - Use bullet points for each task/subtask - Be specific and actionable

1. Update commit information:

```bash # Count commits since session date SESSIONDATE=$(grep "^**Date:" session.md | cut -d' ' -f2) COMMITS=$(git log --oneline --since="$SESSIONDATE" | wc -l) BRANCH=$(git branch --show-current)

# Update commits line Commits: $COMMITS commits to $BRANCH ```

1. Update status if changed:

- Change status emoji and text - Add resolution notes if moving to COMPLETE

1. Update next steps:

- Remove completed items - Add newly discovered tasks - Note any blockers

1. Commit updates:

``bash git add docs/sessions/{filename} git commit -m "docs: update session summary - {change description}" ``

Link Artifacts

When: Completing session documentation and connecting to related work.

Process:

1. Scan git commits for file changes:

``bash SESSIONDATE=$(grep "^**Date:" session.md | cut -d' ' -f2) git diff --name-only $(git log --since="$SESSIONDATE" --format=%H | tail -1)..HEAD ``

1. Identify related handoffs:

- Check for handoff files mentioned in commits - Search handoff content for references to this work - Look for handoffs with matching creation dates - Format: [handoff-title](../handoffs/current/YYYY-MM-DD-handoff-name.md)

1. Find referenced plan files:

- Look for implementation plan references in commits - Check for plans in docs/plans/ matching the work - Format: [plan-title](../plans/YYYY-MM-DD-plan-name.md)

1. Link to created/updated summaries:

- Identify new guides in docs/guides/ - Identify new summaries in docs/summaries/ - Add to "Files Changed" section with relative paths

1. Verify all links:

- Test that linked files exist - Use relative paths from docs/sessions/ - Example: ../handoffs/current/2025-11-14-feature-handoff.md

Apply Style

When: Finalizing session documentation before marking complete.

Process:

1. Invoke writing-clearly-and-concisely skill:

`` Use writing-clearly-and-concisely skill to improve this session document: [session content] ``

1. Apply Strunk's Elements of Style rules:

- Simplify complex sentences - Remove needless words - Use active voice - Make definite assertions - Avoid overstatement

1. Specific checks:

- Executive Summary: 2-3 clear sentences maximum - Work Completed: Action verbs (Created, Implemented, Fixed, Added) - Technical Details: Specific, concrete information - Next Steps: Clear, actionable items

1. Before/After comparison:

- Show improvements made - Explain why changes strengthen the writing - Ensure technical accuracy preserved

1. Save polished version:

``bash git add docs/sessions/{filename} git commit -m "docs: apply style improvements to session summary" ``

Integration

Uses:

• superpowers:verification-before-completion - Evidence-based commit verification
• writing-clearly-and-concisely - Final polish and style checking

Used by:

• managing-handoffs skill - Sessions linked from handoff metadata
• project-status skill - Shows recent sessions on dashboard
• Development workflows - Document work sessions

Session Types

Implementation Session

Focus on feature development, code commits, and deliverables.

Emphasize:

• What was built
• Technical decisions
• Test coverage
• Files changed

Investigation Session

Focus on analysis, research, and findings.

Emphasize:

• Questions investigated
• Findings and conclusions
• Data analyzed
• Recommendations

Debugging Session

Focus on problem resolution and root cause analysis.

Emphasize:

• Problem description
• Investigation steps
• Root cause identified
• Solution implemented

Planning Session

Focus on design decisions and planning artifacts created.

Emphasize:

• Design choices made
• Alternatives considered
• Plans created
• Next implementation steps

Common Mistakes

Vague summaries:

• Problem: "Made progress on the feature"
• Fix: "Implemented database migration and 3 API endpoints for import status tracking"

Missing evidence:

• Problem: Claims work complete without commit references
• Fix: Link specific commits or provide git log output

Broken links:

• Problem: Absolute paths or incorrect relative paths
• Fix: Use relative paths from docs/sessions/ directory

Weak writing:

• Problem: Passive voice, wordiness, vague statements
• Fix: Apply writing-clearly-and-concisely skill

Red Flags

Never:

• Claim work complete without verification
• Use absolute file paths in links
• Skip the executive summary
• Leave status as IN PROGRESS for finished work
• Mark COMPLETE with incomplete next steps

Always:

• Verify commits exist for claimed work
• Use relative paths for artifact links
• Write 2-3 sentence executive summary
• Update status to match reality
• Clear next steps or mark none remaining

Examples

Good Executive Summary

"Successfully implemented Import Status Dashboard MVP with full-stack integration from PostgreSQL views to React components. All 8 planned tasks delivered including database migrations, API endpoints, and UI components with real-time auto-refresh. Dashboard now provides visibility into import pipeline health and data quality metrics."

Poor Executive Summary

"Worked on the dashboard. Made good progress. Still some things to do."

Good Work Completed

• Created 4 PostgreSQL views for import quality metrics
• Implemented ImportStatusController with 4 filtered endpoints
• Built ImportStatusDashboard React component with TanStack Query
• Added sortable ImportHistoryTable with 8 columns
• Integrated SystemHealthIndicator and QualityMetricsCards

Poor Work Completed

• Did database stuff
• Made some API changes
• Updated the frontend
• Fixed bugs

Verification Checklist

Before marking session COMPLETE:

• Executive summary exists and is 2-3 sentences
• All work items listed with specific actions
• Technical details capture key decisions
• Commit count and branch info accurate
• Related handoffs linked (if applicable)
• Related plans linked (if applicable)
• Files changed section lists key files
• Next steps clear or marked as none
• Style applied using writing-clearly-and-concisely
• All links verified to work

Quick Reference

Create session:

# From skill
Operation: Create session
Title: {descriptive-title}
Status: IN PROGRESS

Update commit count:

git log --oneline --since="YYYY-MM-DD" | wc -l

Find related files:

git diff --name-only $(git log --since="YYYY-MM-DD" --format=%H | tail -1)..HEAD

Apply style:

# Invoke writing-clearly-and-concisely skill on session document

Verify links:

# From docs/sessions/ directory
cd /path/to/project/docs/sessions
# Test each link
ls -la ../handoffs/current/YYYY-MM-DD-handoff.md
ls -la ../plans/YYYY-MM-DD-plan.md