Session Documentation
Enforce comprehensive documentation as part of work completion. This skill ensures documentation is part of "done" - not an afterthought.
Purpose
Documentation debt compounds session over session. Without proactive documentation:
Future sessions rebuild context from scratch (~50K tokens)Handoff errors occur (e.g., constraints implemented but not registered)Users must prompt 3x for comprehensive docsThis skill ensures documentation happens automatically when work completes.
When to Activate
Activate this skill automatically when:
1. **Feature implementation completed** - Any new capability added
2. **Bug fix committed** - Any issue resolved
3. **Significant code change** - More than trivial edits
4. **Session ending** - User says "done", "finished", "ending session"
5. **Handoff requested** - User asks for summary/handoff/status
6. **PR ready** - Before creating pull request
Instructions
Step 1: Detect Completion Signal
Monitor for these triggers:
User says "done", "finished", "complete", "ending session"Pull request creation requestedUser asks for "summary", "handoff", "status"Feature implementation completedBug fix committedStep 2: Generate Required Documentation
Create documentation with ALL of these sections:
```markdown
What Was Done
Bullet list of completed tasksFiles created/modified (with line ranges)Tests added/modifiedWhy It Was Done
Context/motivationProblem being solvedRelated issue/task referenceHow to Verify
Commands to runExpected outputSuccess criteriaWhat Remains
Incomplete tasksKnown limitationsFollow-up work needed```
Step 3: Add Recommended Sections (When Applicable)
Include these sections if relevant:
```markdown
Decisions Made
Design choices and rationaleAlternatives considered and rejectedTrade-offs acceptedGotchas and Warnings
Common pitfallsNon-obvious behaviorDependencies or prerequisitesRelated Updates
Documentation files updatedCHANGELOG entry addedREADME updated (if applicable)```
Step 4: For Session Handoffs (REQUIRED at Session End)
Create a comprehensive handoff document with:
```markdown
Session Summary
Current State
System status (working/broken/partial)Database stateContainer/service statusCompleted This Session
Task 1 - commit hashTask 2 - commit hashBlocked Items
Item 1 - reason and contextItem 2 - reason and contextNext Steps (Prioritized)
1. Highest priority task
2. Second priority task
3. Third priority task
Verification Commands
```bash
Commands to verify current state
```
Key Files
| File | Purpose |
|------|---------|
| path/to/file | What it does |
```
Step 5: Choose Appropriate Output Location
Save documentation in the right place:
| Type | Location | When to Use |
|------|----------|-------------|
| Session handoff | `docs/development/SESSION_HANDOFF_YYYYMMDD.md` | Ending a session |
| Feature docs | `docs/architecture/` or `docs/guides/` | New capability |
| Bug fix notes | Commit message + CHANGELOG | Issue resolution |
| Technical details | `docs/development/` | Implementation specifics |
| Postmortem | `docs/development/POSTMORTEM_*.md` | Session analysis |
Step 6: Verify Documentation Quality
Before marking complete, check:
**Structure:**
[ ] Clear headings and sections[ ] Bullet points for scanability[ ] Code blocks for commands/examples[ ] Tables for structured data**Content:**
[ ] Specific, not vague ("added X to Y" not "made changes")[ ] Actionable next steps[ ] Verifiable claims (commands to prove it works)[ ] No orphan references (linked docs exist)**Completeness:**
[ ] Someone unfamiliar could understand and continue[ ] No assumed knowledge not documented[ ] Edge cases and exceptions noted[ ] Future sessions won't ask "what did we do?"Examples
Bad: Minimal Response
```
"Fixed the bug in scheduler.py"
```
Good: Comprehensive Response
```markdown
Bug Fix: Scheduler Timezone Mismatch
What Was Done
Fixed UTC/local timezone conversion in `scheduler.py:145-160`Added explicit timezone handling in `_calculate_hours()`Added test case for HST timezone edge caseFiles Modified
`backend/app/scheduling/scheduler.py` (lines 145-160)`backend/tests/test_scheduler.py` (added test_hst_conversion)How to Verify
```bash
pytest backend/tests/test_scheduler.py::test_hst_conversion -v
```
Root Cause
Scheduler assumed UTC but database stored local time (HST).
```
Verification Commands
Run these to check documentation exists:
```bash
Check for recent session docs
find docs/development -name "SESSION_*.md" -mtime -1 | head -5
Check for handoff docs
find docs/development -name "*HANDOFF*.md" -mtime -1 | head -5
Check CHANGELOG updated
git log --oneline -5 | grep -i "changelog\|docs"
```
Anti-Patterns to Avoid
**Vague summaries**: "Made some changes" → List specific files and changes**No verification steps**: Include commands to prove it works**Missing context**: Explain WHY, not just WHAT**Incomplete handoffs**: Always include Next Steps and Current State**Orphan references**: Don't mention docs that don't existIntegration with Other Skills
This skill complements:
**constraint-preflight**: Both verify "done" criteria**code-review**: Documentation is part of review**pr-reviewer**: PR descriptions require docs**changelog-generator**: Feeds into release notesNotes
Documentation is not optional polish - it's how future sessions avoid starting from zeroIf user provides minimal info, prompt for expansion before acceptingHandoff documents should be created EVERY session, not just when askedCommit documentation changes alongside code changes