Session Documentation Enforcer
This skill ensures comprehensive documentation is created as an integral part of work completion, not as an afterthought. It automatically activates when features are completed, bugs are fixed, or sessions are ending to prevent documentation debt and context loss.
Purpose
Without proactive documentation:
Future sessions rebuild context from scratch consuming ~50K tokensHandoff errors occur (implemented features not properly registered)Users must prompt multiple times for comprehensive documentationKnowledge is lost between sessionsThis skill makes documentation a required part of "done."
Activation Triggers
Automatically activate this skill when:
1. **Feature implementation completed** - Any new capability has been added
2. **Bug fix committed** - Any issue has been resolved
3. **Significant code change** - More than trivial edits made
4. **Session ending** - User says "done", "finished", "ending session", or similar
5. **Handoff requested** - User asks for summary, handoff, or status
6. **PR ready** - Before creating a pull request
Step-by-Step Documentation Protocol
Step 1: Detect Completion Event
Monitor for completion signals:
Task marked as complete in todo listUser indicates work is finishedSession end phrases detectedPull request creation initiatedStep 2: Assess Documentation Requirements
Determine which documentation level is required:
**Minimum Required (ALL tasks):**
What was done (task list)Why it was done (context/motivation)How to verify (commands and expected output)What remains (incomplete work)**Session Handoff (session end):**
Current system stateCompleted work with commit hashesBlocked items with reasonsPrioritized next stepsVerification commandsKey files table**Feature Documentation (new capabilities):**
Architecture decisionsDesign rationaleIntegration pointsUsage examplesGotchas and warningsStep 3: Generate Documentation Structure
Create appropriate documentation file(s):
**Location mapping:**
Session handoff → `docs/development/SESSION_HANDOFF_YYYYMMDD.md`Feature documentation → `docs/architecture/` or `docs/guides/`Bug fix notes → Commit message + CHANGELOG entryTechnical details → `docs/development/`Postmortem → `docs/development/POSTMORTEM_*.md`**Required sections for minimum documentation:**
```markdown
What Was Done
Specific task 1 with file referencesSpecific task 2 with line rangesTests added/modifiedWhy It Was Done
Context and motivationProblem being solvedRelated issue referenceHow to Verify
```bash
Actual commands to verify
```
**Expected output:** [description]
What Remains
Incomplete task 1Known limitation 1Follow-up work needed```
**Required sections for session handoff:**
```markdown
Session Handoff: YYYY-MM-DD
Session Summary
Current State
Component 1: statusComponent 2: statusDatabase state: descriptionCompleted This Session
[x] Task 1 - commit hash[x] Task 2 - commit hashBlocked Items
Item 1 - specific reason and blocker detailsItem 2 - specific reason and blocker detailsNext Steps (Prioritized)
1. Highest priority task with context
2. Second priority task with context
3. Third priority task with context
Verification Commands
```bash
Command to verify current state
Command to check key functionality
```
Key Files
| File | Purpose |
|------|---------|
| path/to/file1 | Specific description |
| path/to/file2 | Specific description |
```
Step 4: Populate Content
Fill documentation with specific, actionable information:
**Be specific, not vague:**
❌ "Made changes to the scheduler"✅ "Fixed UTC/local timezone conversion in `scheduler.py:145-160`"**Include verification:**
❌ "Feature is working"✅ "Run `pytest tests/test_feature.py -v` - expect 5 passing tests"**Document decisions:**
❌ "Used approach A"✅ "Used approach A over B because X; trade-off: accepts Y limitation"**List files with context:**
❌ "Modified backend files"✅ "Modified `app/scheduler.py` (lines 145-160): timezone handling"Step 5: Quality Verification
Before marking documentation complete, verify:
**Structure checklist:**
[ ] Clear headings and sections present[ ] Bullet points used for scanability[ ] Code blocks for commands and examples[ ] Tables for structured data[ ] Proper markdown formatting**Content checklist:**
[ ] Specific details, not vague statements[ ] Actionable next steps provided[ ] Verifiable claims with commands to prove[ ] No orphan references (all links exist)[ ] File paths and line numbers included[ ] Commit hashes referenced where applicable**Completeness checklist:**
[ ] Someone unfamiliar could understand and continue work[ ] No assumed knowledge left undocumented[ ] Edge cases and exceptions noted[ ] Future sessions won't need to ask "what was done?"[ ] All required sections presentStep 6: Create Documentation Files
Write documentation to appropriate location:
```bash
Session handoff example
docs/development/SESSION_HANDOFF_20250202.md
Feature documentation example
docs/architecture/new-feature-name.md
Bug fix - ensure CHANGELOG updated
CHANGELOG.md
```
Step 7: Verify Documentation Exists
Run verification commands:
```bash
Check for recent session docs
find docs/development -name "SESSION_*.md" -mtime -1
Check for handoff docs
find docs/development -name "*HANDOFF*.md" -mtime -1
Check CHANGELOG updated
git log --oneline -5 | grep -i "changelog\|docs"
```
Step 8: Present Documentation Summary
Provide user with:
Link to created documentation file(s)Summary of what was documentedVerification that all required sections are completeReminder of any follow-up documentation neededAnti-Patterns to Avoid
**Don't provide minimal responses:**
```
"Fixed the bug in scheduler.py"
```
**Do provide comprehensive documentation:**
```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 case in `tests/test_scheduler.py`Files 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
```
**Expected output:** 1 passed test showing HST timezone handled correctly
Root Cause
Scheduler assumed UTC timestamps but database stored local time in HST, causing 10-hour offset in calculations.
What Remains
[ ] Add timezone validation for other timezones (PST, EST, etc.)[ ] Consider centralizing timezone handling in config module```
Example: Complete Session Handoff
```markdown
Session Handoff: 2025-02-02
Session Summary
Current State
Backend: Running in Docker (healthy)Frontend: Running on npm dev server (port 3000)Database: PostgreSQL with 87 assignments in Block 10All services passing health checksCompleted This Session
[x] Fixed constraint registration gap in ConstraintManager (commit abc1234)[x] Added schema versioning feature to migrations (commit def5678)[x] Created Docker networking workaround documentation (commit ghi9012)[x] Added 3 new test cases for timezone edge cases (commit jkl3456)Blocked Items
MCP tool `get_static_fallbacks` - needs backend API endpoint implementation (blocked on API design review)Heatmap API data format mismatch - frontend expects v2 format but backend returns v1 (requires backend changes + migration)Swap marketplace admin permissions - role inheritance bug in auth middleware (investigating root cause)Next Steps (Prioritized)
1. **High:** Address heatmap API mismatch - frontend shows unsupported visualization options due to data format mismatch
2. **Medium:** Fix swap marketplace permissions for admin role - currently returns 403 for valid admin users
3. **Low:** Create default person profile for admin user - enhancement for better UX
Verification Commands
```bash
Verify constraint registration
docker exec backend python -c "from app.scheduling.constraints.manager import ConstraintManager; print(len(ConstraintManager.create_default().constraints))"
Expected: 12 constraints
Verify Block 10 schedule
curl -s http://localhost:8000/api/v1/schedule/block/10 | jq '.assignments | length'
Expected: 87 assignments
Run test suite
docker exec backend pytest tests/ -v
Expected: 45 passed
```
Key Files
| File | Purpose |
|------|---------|
| `backend/app/scheduling/constraints/manager.py` | Constraint registration - added missing Block 10 constraints |
| `backend/migrations/v2_add_schema_version.py` | Schema versioning implementation |
| `docs/development/DOCKER_NETWORKING.md` | Docker workaround documentation for dev environment |
| `docs/development/SESSION_HANDOFF_20250202.md` | This handoff document |
| `scripts/verify_constraints.py` | Pre-flight verification script for constraint system |
```
Integration with Other Skills
This skill works with:
**constraint-preflight** - Both verify completion criteria are met**code-review** - Documentation is part of review checklist**pr-reviewer** - PR descriptions require documentation links**changelog-generator** - Documentation feeds into release notes**commit** - Ensures commit messages reference documentationImportant Notes
Documentation is not optional polish - it is a required completion criterionAlways create documentation before marking work as completeIf user provides minimal information, prompt for expansion with specific questionsSession handoffs are mandatory when session is ending or work is being handed offDocumentation should be verifiable - include commands that prove the work functions correctlyUse specific file paths, line numbers, and commit hashes - never be vagueFuture sessions should be able to continue work without asking "what was done?"Constraints
Documentation must be written before marking tasks completeAll required sections must be present (What/Why/How/Remains)Verification commands must be executable and produce expected outputFile references must include line numbers or line rangesSession handoffs must include current state and verification commandsDocumentation must be specific enough that an unfamiliar developer can understand and continue