Session Documentation Enforcer

This skill ensures comprehensive documentation is created as part of completing work, not as an afterthought. It automatically activates when features are completed, bugs are fixed, or sessions end to prevent documentation debt and context loss across sessions.

Why This Skill Exists

Documentation debt compounds session over session. Without proactive documentation:

This skill ensures documentation is part of "done" - treating it as a first-class deliverable.

Activation Triggers

Automatically activate this skill when:

1. **Feature implementation completed** - Any new capability added to the codebase

2. **Bug fix committed** - Any issue resolved and code changed

3. **Significant code change** - More than trivial edits (multiple files or complex logic)

4. **Session ending** - User says "done", "finished", "ending session", or similar

5. **Handoff requested** - User explicitly asks for summary, handoff, or status report

6. **PR ready** - Before creating a pull request to ensure reviewers have context

Documentation Requirements

Minimum Required Sections (ALL must be present)

For every completed task, create documentation with these sections:

**What Was Done**

**Why It Was Done**

**How to Verify**

**What Remains**

Recommended Sections (Include when applicable)

**Decisions Made**

**Gotchas and Warnings**

**Related Updates**

For Session Handoffs (REQUIRED at session end)

Create a comprehensive handoff document with:

**Current State**

**Completed This Session**

**Blocked Items**

**Next Steps (Prioritized)**

**Verification Commands**

**Key Files**

Documentation Quality Standards

Before marking documentation complete, verify:

**Structure Quality**

**Content Quality**

**Completeness Check**

Output Locations

Create documentation in appropriate locations based on type:

| Documentation Type | Location | Use Case |

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

| Session handoff | `docs/development/SESSION_HANDOFF_YYYYMMDD.md` | End of work session |

| Feature documentation | `docs/architecture/` or `docs/guides/` | New capabilities or features |

| Bug fix notes | Commit message + CHANGELOG entry | Issue resolution |

| Technical details | `docs/development/` | Implementation specifics |

| Postmortem | `docs/development/POSTMORTEM_*.md` | Session analysis after issues |

Anti-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

Files Modified

How to Verify

```bash

pytest backend/tests/test_scheduler.py::test_hst_conversion -v

Expected: PASSED (1/1 tests)

```

Root Cause

Scheduler assumed UTC timestamps but database stored local time in HST,

causing 10-hour offset in scheduling calculations.

Next Steps

```

Implementation Instructions

When this skill is activated, follow these steps:

1. **Assess scope** - Determine what type of documentation is needed (feature, bug fix, handoff)

2. **Gather information** - Review all modified files, commits, and test results

3. **Create structured output** - Use appropriate template sections from requirements above

4. **Verify completeness** - Check against quality standards checklist

5. **Save to appropriate location** - Use correct file path based on documentation type

6. **Confirm with user** - Ask if additional detail is needed in any section

For session handoffs specifically:

1. Run verification commands yourself to confirm current state

2. List ALL completed work with commit references

3. Document ALL blocked items with specific blockers

4. Prioritize next steps based on dependencies and user goals

5. Create a Key Files table for quick navigation

Integration with Development Workflow

This skill complements other development practices:

Verification Commands

Use these commands to check documentation exists and is current:

```bash

Check for recent session documentation

find docs/development -name "SESSION_*.md" -mtime -1 | head -5

Check for handoff documentation

find docs/development -name "*HANDOFF*.md" -mtime -1 | head -5

Verify CHANGELOG or docs were updated in recent commits

git log --oneline -5 | grep -iE "changelog|docs|documentation"

Count documentation files modified in last week

git log --since="1 week ago" --name-only --pretty=format: | grep -E "\.md$" | sort -u | wc -l

```

Example: Complete Session Documentation

```markdown

Session Handoff: 2025-12-25

Session Summary

Current State

Completed This Session

- Ensured all 15 constraint types properly registered

- Added verification script

- Tracks constraint schema changes over time

- Backwards compatible with existing data

- Documents timezone handling in containers

Blocked Items

- Requires new API route in FastAPI backend

- Estimated 2-3 hours of work

- Backend returns `day_of_week`, frontend expects `dayOfWeek`

- Needs coordination between teams

Next Steps (Prioritized)

1. **Address heatmap API bug** - Frontend shows unsupported options, breaks UX

2. **Fix swap marketplace permissions** - Admin role can't access swap features

3. **Create admin person profile** - Needed to test instructor-side workflows

Verification Commands

```bash

Verify all 15 constraints registered

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

Expected output: 15

Verify schedule assignments exist

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

Expected output: 87

Run full test suite

npm test && docker exec backend pytest

Expected: All tests passing

```

Key Files

| File | Purpose | Lines Changed |

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

| `backend/app/scheduling/constraints/manager.py` | Constraint registration and initialization | 45-120 |

| `docs/development/SESSION_HANDOFF_20251225.md` | This handoff document | N/A |

| `scripts/verify_constraints.py` | Pre-flight verification script | All (new file) |

| `backend/app/scheduling/constraints/block_constraints.py` | Block 10 specific constraints | 200-245 |

```

Enforcement Strategy

Make this skill a natural part of your workflow:

1. **Build the habit** - Always check documentation checklist before marking work "done"

2. **Prompt expansion** - If you receive minimal documentation, immediately ask for comprehensive details

3. **PR gatekeeping** - Require documentation for PR approval

4. **Session endings** - Never end a session without creating handoff documentation

5. **Retrospectives** - Review documentation quality in team retrospectives

Remember: **Documentation is not optional polish - it's how future sessions avoid starting from zero.** Every minute spent documenting saves 10 minutes of context rebuilding later.