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:

This skill makes documentation a required part of completing any work.

When to Activate

Activate 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

Required Documentation Outputs

Minimum Required (ALL must be present)

For every completed task, provide:

Recommended (Include when applicable)

For Session Handoffs (REQUIRED at session end)

Create a comprehensive handoff document including:

Documentation Quality Standards

Before marking documentation "complete," verify:

Structure

Content

Completeness

Output Locations

Documentation should be created in appropriate locations:

Anti-Patterns to Avoid

**Don't**: Minimal responses like "Fixed the bug in scheduler.py"

**Do**: Comprehensive responses including:

Verification Script

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"

```

Example: Full Session Documentation

```markdown

Session Handoff: 2025-12-25

Session Summary

Current State

Completed This Session

Blocked Items

Next Steps (Prioritized)

1. Address heatmap API bug (frontend shows unsupported options)

2. Fix swap marketplace permissions for admin role

3. Create person profile for admin user

Verification Commands

```bash

Check constraints

docker exec backend python -c "from app.scheduling.constraints.manager import ConstraintManager; print(len(ConstraintManager.create_default().constraints))"

Check schedule

curl -s http://localhost:8000/api/v1/schedule/block/10 | jq '.assignments | length'

```

Key Files

| File | Purpose |

|------|---------|

| `backend/app/scheduling/constraints/manager.py` | Constraint registration |

| `docs/development/SESSION_HANDOFF_20251225.md` | This handoff |

| `scripts/verify_constraints.py` | Pre-flight verification |

```

Enforcement

This skill should be enforced through:

1. **Habit** - Check documentation checklist before saying "done"

2. **Prompts** - If minimal docs given, prompt for expansion

3. **PR Review** - Documentation required for PR approval

4. **CI Check** - Verify handoff doc exists for session branches

Instructions for AI Agent

When you complete any task, bug fix, feature, or session:

1. **Do not consider work "done" until documentation is complete**

2. **Always create documentation in the appropriate location** (see Output Locations above)

3. **Use the checklists above** to verify documentation quality

4. **For session ends or handoffs**, always create a SESSION_HANDOFF_YYYYMMDD.md file

5. **Include verification commands** so the next person (or AI) can prove the work is complete

6. **Be specific**: File paths, line numbers, commit hashes, command outputs

7. **If user says "done" without docs**, prompt them: "I should create session documentation. Where would you like me to put the handoff summary?"

Remember: Documentation is not optional polish - it's how future sessions avoid starting from zero.