ajbcoding/documenting-sessions

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