gh-jezweb-claude-skills-skills-project-workflow/commands/wrap-session.md

Wrap Session

Automate end-of-session workflow: update SESSION.md, create git checkpoint, and prepare for context clear.

---

Your Task

Follow these steps to wrap up the current session and prepare for a clean handoff.

1. Analyze Current State (Use Task Agent)

Use the Task tool with description "Analyze session state for wrap-up" to gather:

• Read SESSION.md completely
• Run git status to see uncommitted changes
• Run git log -1 --oneline to see last commit
• Run git diff --stat to see what changed
• Extract current phase number, name, and status
• Extract current stage (Implementation/Verification/Debugging)
• Extract "Next Action"
• Extract "Known Issues"

If SESSION.md doesn't exist:

• Stop and output: "❌ No SESSION.md found. Run project-planning skill first to set up session management."
• Do not proceed further

2. Update SESSION.md

Update the following sections:

a) Current Stage

• If tasks completed and ready for verification: Change to "Verification"
• If verification done and ready for next phase: Keep as current
• If debugging: Keep as "Debugging"

b) Progress Section

• Mark any completed tasks with [x]
• Add new tasks discovered during session
• Reorder if priorities changed

c) Known Issues

• Add any new issues discovered this session
• Remove resolved issues
• Update issue descriptions if changed

d) Next Action

• Update to be concrete and specific:
  • Must include: file path + line number (if applicable) + specific action
  • Example: "Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check"
  • NOT vague like: "Continue working on API..."

e) Last Checkpoint

• Update date to today (YYYY-MM-DD format)
• Checkpoint hash will be updated after git commit (step 4)

f) If Phase Complete

• Change phase status from 🔄 to ✅
• Add "Completed" date
• Add "Summary" with 2-3 line accomplishment description
• Collapse phase section to 2-3 lines
• Move to next phase:
  • Change next phase from ⏸️ to 🔄
  • Expand next phase with initial task list
  • Set new "Next Action"

3. Check for Doc Updates

Analyze what changed this session using git diff output.

Ask user about updating these docs (only if relevant changes detected):

If phase completed:

• "Phase [N] complete! Should I add entry to CHANGELOG.md? (y/n)"

If architecture changed (new patterns, major refactoring):

• "Architecture changes detected. Update ARCHITECTURE.md? (y/n)"

If API endpoints added/modified:

• "API changes detected. Update API_ENDPOINTS.md? (y/n)"

If database schema changed:

• "Schema changes detected. Update DATABASE_SCHEMA.md? (y/n)"

If README needs updates (new features, changed usage):

• "User-facing changes detected. Update README.md? (y/n)"

For each "yes":

• Read the relevant doc
• Update with session changes
• Confirm update was made

Note: Don't ask about docs that don't exist or aren't relevant to changes.

4. Create Git Checkpoint

a) Stage all changes:

git add .

b) Check if there are changes to commit:

git status --short

If no changes:

• Output: "ℹ️ No changes to commit. SESSION.md updated, no checkpoint created."
• Skip to step 5

c) Determine checkpoint status:

• If phase complete: Status = "Complete"
• If significant progress: Status = "In Progress"
• If blocked/paused: Status = "Paused"
• Otherwise: Status = "In Progress"

d) Get phase info from SESSION.md:

• Phase number
• Phase name
• What was accomplished this session (from progress updates)
• Files that changed (from git status)

e) Create structured commit message:

git commit -m "$(cat <<'EOF'
checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Phase Name]
Status: [Complete/In Progress/Paused]
Session: [1-2 sentence summary of what was accomplished]

Files Changed:
- path/to/file.ts ([what changed])
- path/to/file2.ts ([what changed])
[... list all significant files]

Next: [Concrete next action from SESSION.md]

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

f) Get commit hash:

git log -1 --format="%h"

g) Update SESSION.md "Last Checkpoint" with new hash

5. Output Handoff Summary

Display a formatted summary:

═══════════════════════════════════════════════
   SESSION WRAP-UP COMPLETE
═══════════════════════════════════════════════

📋 Phase: [N] - [Phase Name] ([Status emoji])
📍 Stage: [Implementation/Verification/Debugging]

✅ Completed This Session:
   • [accomplishment 1]
   • [accomplishment 2]
   • [accomplishment 3]

🎯 Next Action:
   [Concrete next action from SESSION.md]

💾 Checkpoint: [hash] ([date])

📄 Docs Updated:
   • SESSION.md
   • [CHANGELOG.md] (if updated)
   • [other docs] (if updated)

═══════════════════════════════════════════════

6. Ask About Git Push

Ask user: "Push checkpoint to remote? (y/n)"

If yes:

git push

If push succeeds:

• Output: "✅ Pushed to remote successfully"

If push fails:

• Output: "❌ Push failed. Run git push manually when ready."

7. Final Message

Output:

✨ Session wrapped successfully!

Ready to clear context or continue working.

To resume: Run `/continue-session` in your next session.

---

Error Handling

SESSION.md doesn't exist:

• Stop immediately
• Output: "❌ No SESSION.md found. Create it first with project-planning skill."

No IMPLEMENTATION_PHASES.md:

• Warning: "⚠️ No IMPLEMENTATION_PHASES.md found. Continuing with SESSION.md only."
• Proceed without phase verification

Git commit fails:

• Output error message
• Output: "Fix git issue and try again, or commit manually."

Git push fails:

• Output: "⚠️ Push failed. You can run git push manually later."
• Continue (not critical)

Docs update fails:

• Output: "⚠️ Failed to update [doc]. You can update it manually."
• Continue with other updates

---

Success Criteria

✅ SESSION.md updated with current progress ✅ Git checkpoint created with structured message ✅ Relevant docs updated (if needed) ✅ Clear "Next Action" for resuming ✅ User knows exactly what to do next