Enforces comprehensive documentation as part of work completion for features, bug fixes, and session handoffs to prevent context loss and enable seamless continuity across sessions.
Enforce comprehensive documentation as part of work completion to prevent documentation debt and enable seamless session handoffs.
Documentation debt compounds session over session. Without proactive documentation:
This skill ensures documentation is part of "done" - not an afterthought.
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
For every completed task, provide:
**What Was Done**
**Why It Was Done**
**How to Verify**
**What Remains**
**Decisions Made**
**Gotchas and Warnings**
**Related Updates**
When ending a session or handing off work, create a handoff document with:
**Session Summary**
**Completed This Session**
**Blocked Items**
**Next Steps (Prioritized)**
1. Highest priority task with context
2. Second priority task
3. Third priority task
4. Include why this order matters
**Verification Commands**
```bash
```
**Key Files**
Table of critical files with their purpose:
| File | Purpose |
|------|---------|
| path/to/file.ext | Brief description |
Before marking documentation "complete," verify:
Create documentation in appropriate locations:
| Type | Location | When |
|------|----------|------|
| Session handoff | `docs/development/SESSION_HANDOFF_YYYYMMDD.md` | Ending a session |
| Feature docs | `docs/architecture/` or `docs/guides/` | New capability added |
| Bug fix notes | Commit message + CHANGELOG | Issue resolution |
| Technical details | `docs/development/` | Implementation specifics |
| Postmortem | `docs/development/POSTMORTEM_*.md` | Significant incident or learning |
Adjust paths based on project structure.
```
"Fixed the bug in scheduler.py"
```
This leaves future sessions with:
```markdown
Scheduler assumed UTC timestamps but database stored local time (HST).
This caused off-by-hours scheduling errors for Hawaii users.
```bash
pytest backend/tests/test_scheduler.py::test_hst_conversion -v
```
No explicit timezone handling at database boundary. Naive datetime
objects were being compared across timezone boundaries.
Added timezone validation in ORM model. All datetime fields now
require explicit timezone (pytz). Added pre-commit hook to catch
naive datetime usage.
```
```markdown
- Registered missing Block 10 constraints in ConstraintManager
- Added verification script to prevent future gaps
- Created migration system for constraint schemas
- Added rollback capability
- Documented MCP tool limitations in containerized environments
- Added fallback procedures
- Requires: POST /api/v1/fallbacks endpoint in FastAPI backend
- Estimate: 2-3 hours to implement
- Requires: Backend schema update + migration
- Breaking change, needs coordination
1. **Address heatmap API bug** (highest priority)
- Frontend shows unsupported filter options
- Users experiencing errors on heatmap page
- Fix: Update backend schema + add validation
2. **Fix swap marketplace permissions** (medium priority)
- Admin role can't access swap marketplace
- Fix: Add admin role to allowed_roles in route guard
3. **Create person profile for admin user** (low priority)
- Admin account missing person profile relation
- Fix: Run data migration script
```bash
docker exec backend python -c "from app.scheduling.constraints.manager import ConstraintManager; print(len(ConstraintManager.create_default().constraints))"
curl -s http://localhost:8000/api/v1/schedule/block/10 | jq '.assignments | length'
docker exec backend pytest -v
```
| File | Purpose |
|------|---------|
| `backend/app/scheduling/constraints/manager.py` | Constraint registration and initialization |
| `backend/app/scheduling/constraints/block10/` | Block 10 specific constraint implementations |
| `docs/development/SESSION_HANDOFF_20251225.md` | This handoff document |
| `scripts/verify_constraints.py` | Pre-flight verification for constraint system |
| `docker-compose.yml` | Container orchestration config |
```
1. Check documentation checklist before saying task is "done"
2. Create documentation as you work, not as an afterthought
3. Update handoff doc incrementally throughout session
1. Review the Session Handoff checklist
2. Create or update handoff document
3. Commit handoff doc with final commit
4. Verify someone unfamiliar could continue work
1. Documentation required for PR approval
2. Handoff doc linked in PR description
3. Verify all checklist items complete
```bash
if git branch --show-current | grep -E 'feature|fix'; then
if ! ls docs/development/SESSION_* 1> /dev/null 2>&1; then
echo "ERROR: No session handoff documentation found"
exit 1
fi
fi
```
This skill complements:
Check that documentation exists and is recent:
```bash
find docs/development -name "SESSION_*.md" -mtime -1 | head -5
find docs/development -name "*HANDOFF*.md" -mtime -1 | head -5
git log --oneline -5 | grep -i "changelog\|docs"
git log --oneline -10 --no-merges
```
1. **Documentation is part of "done"** - Not optional polish, but a completion requirement
2. **Write for future sessions** - Assume zero context retention
3. **Be specific** - Vague docs are worse than no docs
4. **Make it verifiable** - Include commands to prove it works
5. **Update incrementally** - Don't wait until session end
6. **Link everything** - Connect docs to commits, issues, and related docs
1. Document what the bug was and how to reproduce
2. Document root cause analysis
3. Document the fix and verification steps
4. Update CHANGELOG
5. Add regression test documentation
1. Document feature purpose and use cases
2. Document implementation approach and key files
3. Document testing strategy
4. Document configuration or setup needed
5. Update user-facing documentation (README, guides)
1. Document what was refactored and why
2. Document migration path (if breaking changes)
3. Document verification that behavior unchanged
4. Document new patterns for future contributions
1. Use full Session Handoff template
2. Include prioritized next steps with context
3. Document any non-obvious state
4. Include verification commands
5. Link to all relevant commits and docs
---
**Remember:** Future sessions depend on your documentation. Write for the AI or developer who has never seen this codebase before. If you wouldn't want to receive minimal docs, don't write them.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/session-documentation/raw