delphine-l Documentation Skills
Best practices for creating effective documentation during Claude Code sessions.
Session Documentation
Incremental Summary Documents
When working through multiple related issues in a session:
Create summary after each major fix:
FIX_SUMMARY.md- First issue resolvedFISH_CLASSIFICATION_FIX_SUMMARY.md- Second issueTAXONOMY_COMPLETE_SUMMARY.md- Final state
Benefits:
- User can reference specific fixes
- Clear audit trail of changes
- Easy to see what was done and why
- Supports future troubleshooting
Include in each summary:
- Problem statement: What was the issue?
- Root cause: Why did it happen?
- Species/items affected: With counts for verification
- Solution applied: Step-by-step what was done
- Files modified: Complete list with paths
- Verification results: Show the fix worked
- Next steps: What to do with the results
Example Structure
# [Issue Name] - [STATUS]
## Problem
[Clear description of what was wrong]
## Root Cause
[Why the problem occurred]
## Items Fixed (N total)
| Item | Details | Category |
|------|---------|----------|
| ... | ... | ... |
## Solution Applied
1. [Step 1]
2. [Step 2]
...
## Verification Results
✓ [What was verified]
✓ [Counts match]
## Files Modified
1. `file1.txt` - [what changed]
2. `file2.txt` - [what changed]
## Next Steps
[What the user should do now]
When to Create Summaries
- After fixing a significant bug: Document root cause and solution
- After completing a major task: Show what was accomplished
- After each iteration in multi-step fixes: Track progress
- At session end: Comprehensive final state summary
Documentation File Naming
Use descriptive names that indicate:
- What was fixed:
FISH_CLASSIFICATION_FIX_SUMMARY.md - Scope:
TAXONOMY_COMPLETE_SUMMARY.md - Status: Include "FIXED", "COMPLETE", "FINAL" in filename
Avoid generic names like SUMMARY.md or NOTES.md.
Related Skills
- Skill Management: Capturing learnings from documentation
- Token Efficiency: Concise yet complete documentation