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.

3b. Check for Rule Candidates

Analyze the session for correction patterns:

Look for instances in this session where:

• Claude suggested syntax that was corrected
• A pattern was established for specific file types
• "Don't do X, do Y instead" was discovered
• Version-specific differences were learned (e.g., v3 → v4)

If rule candidates found, ask:

Correction patterns detected this session:
1. [Pattern]: [Wrong → Right]
   - Would apply to: [file patterns]

Create project rule(s)? (y/n)

If yes:

1. Create directory if needed:

   mkdir -p .claude/rules
   

2. For each rule, determine appropriate file paths (globs)

3. Generate rule file:

   ---
   paths: "[patterns]"
   ---
   
   # [Rule Name]
   
   [Context for why this rule exists]
   
   | If Claude suggests... | Use instead... |
   |----------------------|----------------|
   | `[wrong]` | `[correct]` |
   

4. Create .claude/rules/[name].md

5. Optionally ask: "Also update skill for all future projects? (y/n)"

   • If yes and skill exists, update ~/.claude/skills/[skill]/rules/[name].md

If no rule candidates found: Skip this step silently.

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)
   • [.claude/rules/[name].md] (if created)
   • [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) ✅ Project rules created for correction patterns (if any) ✅ Clear "Next Action" for resuming ✅ User knows exactly what to do next