documenting-sessions

name	documenting-sessions
description	Create consistent session summary documents with automatic linking and style checking

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)

2. Generate filename:

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

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

4. Content structure:

   # Session {today}: {Title}
   
   **Date:** {today}
   **Status:** {status_emoji} {STATUS}
   **Related Handoffs:** {handoff_links}
   **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]
   

5. Status emoji mapping:

   • ✅ COMPLETE
   • ⚠️ IN PROGRESS
   • ❌ BLOCKED

6. Commit:

   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

2. Update work items:

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

3. Update commit information:

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

4. Update status if changed:

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

5. Update next steps:

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

6. Commit updates:

   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:

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

2. 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)

3. 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)

4. 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

5. 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]
   

2. Apply Strunk's Elements of Style rules:

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

3. 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

4. Before/After comparison:

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

5. Save polished version:

   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