path: root/docs/workflows/wrap-it-up.org

#+TITLE: Session Wrap-Up Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2025-11-14

* Overview

This workflow defines the process for ending a Claude Code session cleanly. It ensures that all work is documented, committed to version control, and properly handed off to the next session. The wrap-up creates a permanent record and leaves the project in a clean state.

This workflow is triggered by Craig saying "wrap it up," "that's a wrap," "let's call it a wrap," or similar phrases indicating the session should end.

* Problem We're Solving

Without a structured wrap-up process, sessions can end poorly:

** Lost Context
- Key decisions made during the session aren't documented
- Future sessions must reconstruct what happened and why
- Important details fade from memory between sessions
- No record of lessons learned or preferences discovered

** Uncommitted Work
- Files modified but not committed to git
- Changes not pushed to remote repositories
- Working tree left dirty with unclear state
- Risk of losing work if something goes wrong

** Unclear Handoff
- Next session doesn't know what was accomplished
- Unclear what should be worked on next
- Important reminders or blockers not surfaced
- No sense of closure or accomplishment

** Inconsistent Git History
- Commit messages vary in quality and format
- Sometimes includes Claude attribution, sometimes doesn't
- Unclear what changes were made in each commit
- Inconsistent conventions across commits

*Impact:* Poor continuity between sessions, lost work, unclear git history, and wasted time reconstructing context.

* Exit Criteria

The wrap-up is complete when:

1. **Session history is documented:**
   - Key decisions made are recorded in notes.org
   - Work completed is summarized clearly
   - Context needed for next session is captured
   - Pending issues or blockers are noted
   - New conventions or preferences are documented

2. **Git state is clean:**
   - All changes are committed with proper commit message
   - All commits are pushed to all remote repositories
   - Working tree shows no uncommitted changes
   - Push succeeded to all remotes (verified)

3. **Valediction is provided:**
   - Brief, warm goodbye delivered
   - Day's accomplishments acknowledged
   - Next session readiness confirmed
   - Important reminders surfaced

*Measurable validation:*
- =git status= shows "working tree clean"
- =git log -1= shows today's session commit
- Session History section in notes.org has new entry
- User has clear sense of what was accomplished and what's next

* When to Use This Workflow

Trigger this workflow when Craig says any of these phrases (or clear variations):

- "Wrap it up"
- "That's a wrap"
- "Let's call it a wrap"
- "Let's wrap up"
- "Time to wrap"
- "Wrap this session"

Do NOT wait for Craig to explicitly request individual steps. Execute the entire workflow automatically when triggered.

* First Time Setup

If this is the first time using this workflow in a project, perform this one-time cleanup:

** Clean Up Old "Wrap It Up" Documentation

Before using this workflow, check if notes.org contains old/redundant "wrap it up" instructions:

1. **Search notes.org for duplicate content:**
   #+begin_src bash
   grep -n "Wrap it up\|wrap-up" docs/notes.org
   #+end_src

2. **Look for sections that duplicate this workflow:**
   - Old "Wrap it up" protocol descriptions
   - Inline git commit instructions
   - Valediction guidelines
   - Session notes format instructions

3. **Replace with link to this workflow:**
   - Remove the detailed inline instructions
   - Replace with: "See [[file:docs/workflows/wrap-it-up.org][Session Wrap-Up Workflow]]"
   - Keep brief summary if helpful for quick reference

4. **Why this matters:**
   - Prevents conflicting instructions (e.g., different git commit formats)
   - Single source of truth for wrap-up process
   - Easier to maintain and update in one place
   - Reduces notes.org file size

**Example cleanup:**

Before:
#+begin_example
*** "Wrap it up"
When Craig says this:
1. Write session notes with these details...
2. Git commit with this format...
3. Say goodbye like this...
[20+ lines of detailed instructions]
#+end_example

After:
#+begin_example
*** "Wrap it up"
Execute the wrap-up workflow defined in [[file:docs/workflows/wrap-it-up.org][wrap-it-up.org]].

Brief summary: Write session notes, git commit/push (no Claude attribution), valediction.
#+end_example

This cleanup should only be done ONCE when first adopting this workflow.

* The Workflow

** Step 1: Write Session Notes to notes.org

Add new entry to Session History section in =docs/notes.org=

*** Format for Session Entry

#+begin_example
** Session: [Month Day, Year] ([Time of Day if multiple sessions])

**Work Completed**:
- List of major tasks accomplished
- Key decisions made
- Documents created or modified
- Problems solved

**Context for Next Session**:
- What should be worked on next
- Pending decisions or questions
- Deadlines or time-sensitive items
- Files or directories to review

**Key Decisions Made** (if applicable):
- Important choices and rationale
- Strategic pivots
- New approaches or conventions established

**Status**:
Brief summary of where things stand after this session.
#+end_example

*** What to Include in Session Notes

1. **Work Completed:**
   - Major tasks accomplished during session
   - Files created, modified, or deleted
   - Research conducted
   - Problems solved
   - Documents drafted or reviewed

2. **Key Decisions:**
   - Important choices made and why
   - Strategic direction changes
   - Approach or methodology decisions
   - What was decided NOT to do

3. **Context for Next Session:**
   - What should be worked on next
   - Pending issues that need attention
   - Blockers or dependencies
   - Questions that need answering
   - Deadlines approaching

4. **New Conventions or Preferences:**
   - Working style preferences discovered
   - New file naming conventions
   - Process improvements identified
   - Tools or approaches that worked well

5. **Critical Reminders:**
   - Time-sensitive items that need attention soon
   - If truly critical, ALSO add to Active Reminders section
   - Follow-up actions for next session

*** Where to Add Session Notes

- Open =docs/notes.org=
- Navigate to "Session History" section (near end of file)
- Add new =** Session:= entry at the TOP of the session list (most recent first)
- Use today's date in format: "Month Day, Year"
- If multiple sessions same day, add time: "Month Day, Year (Morning)" or "(Afternoon)"

*** Archive Old Sessions (Keep Last 5)

After adding the current session notes, check if there are more than 5 sessions in the Session History section and move older ones to the archive:

1. **Count sessions in Session History:**
   - Count the number of =** Session:= entries in notes.org Session History section
   - If 5 or fewer sessions exist, skip to next step (nothing to archive)

2. **Identify sessions to archive:**
   - Keep the 5 most recent sessions in notes.org
   - Mark all older sessions (6th and beyond) for archiving

3. **Move old sessions to archive:**
   - Check if =docs/previous-session-history.org= exists:
     - If it doesn't exist, create it with this template:
       #+begin_example
       #+TITLE: Previous Session History Archive
       #+AUTHOR: Craig Jennings

       * Archived Sessions

       This file contains archived session history from notes.org.
       Sessions are in reverse chronological order (most recent first).
       #+end_example
   - Open =docs/previous-session-history.org=
   - Cut old session entries from notes.org (6th session and beyond)
   - Paste them at the TOP of "Archived Sessions" section in previous-session-history.org
   - Keep reverse chronological order (most recent archived session first)
   - Save both files

4. **When to skip this step:**
   - If there are 5 or fewer sessions in Session History
   - Just continue to next step

This keeps notes.org focused on recent work while preserving full history.

** Step 2: Git Commit and Push

*** 2.1 Check Git Status

Run these commands to understand what's changed:

#+begin_src bash
git status
#+end_src

#+begin_src bash
git diff
#+end_src

Review the output to understand what files were modified during the session.

*** 2.2 Stage All Changes

#+begin_src bash
git add .
#+end_src

This stages all modified, new, and deleted files.

*** 2.3 Create Commit Message

**IMPORTANT: Commit message requirements:**

1. **Subject line** (first line):
   - Start with lowercase word describing work: "session:", "fix:", "add:", "update:", "refactor:", etc.
   - Brief description of session work (50-72 chars)
   - Example: =session: Strategic pivot to attorney-led demand letter approach=

2. **Body** (after blank line):
   - 1-3 terse sentences describing what was accomplished
   - NO conversational language
   - NO Claude Code attribution
   - NO "Co-Authored-By" line
   - NO emoji or casual language
   - Keep it professional and concise

3. **Author:**
   - Commit as Craig Jennings (NOT as Claude)
   - Use git config user.name and user.email (already configured)

**Example of CORRECT commit message:**

#+begin_example
session: Documentation package prepared for attorney review

Created comprehensive email and supporting documents for Jonathan Schultis.
Includes historical SOVs, contracts, key emails, and meeting notes showing
timeline of dispute and evidence of unapproved charges.
#+end_example

**Example of INCORRECT commit message (DO NOT DO THIS):**

#+begin_example
Session wrap-up! 🤖

Today we had a great session where we prepared documentation for the attorney.
Craig and I worked together to organize all the files.

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
#+end_example

*** 2.4 Execute Commit

Use heredoc format for proper multi-line commit message:

#+begin_src bash
git commit -m "$(cat <<'EOF'
session: [Brief description]

[1-3 terse sentences about work completed]
EOF
)"
#+end_src

Replace bracketed sections with actual content.

*** 2.5 Check Remote Repositories

#+begin_src bash
git remote -v
#+end_src

This shows all configured remote repositories. Note which ones exist (usually =origin=, sometimes others).

*** 2.6 Push to All Remotes

For each remote repository found in step 2.5:

#+begin_src bash
git push [remote-name]
#+end_src

Example if only =origin= exists:
#+begin_src bash
git push origin
#+end_src

If multiple remotes exist, push to each:
#+begin_src bash
git push origin && git push backup
#+end_src

*** 2.7 Verify Clean State

After pushing, verify the working tree is clean:

#+begin_src bash
git status
#+end_src

Should show: "working tree clean" and indicate branch is up to date with remote.

** Step 3: Delete Session Context File

The session context file must be deleted at the end of every successful wrap-up.

*** Why This Is Critical

The existence of =docs/session-context.org= indicates an interrupted session. If you don't delete it:
- Next session will think the previous session crashed
- Context recovery will be triggered unnecessarily
- Creates confusion about session state

*** How to Delete

#+begin_src bash
rm docs/session-context.org
#+end_src

*** When to Skip

NEVER skip this step. If the file doesn't exist, that's fine (the rm command will just report no file). But if it exists, it MUST be deleted.

** Step 4: Verify Clean Git State

*** CRITICAL: Git Status Must Be Completely Clean

Before proceeding to valediction, =git status= MUST show:
- "nothing to commit, working tree clean"
- Branch is up to date with remote(s)

*** If Git Status Is NOT Clean

1. **Untracked files exist:** Ask Craig - "There are untracked files. Should I add and commit them, or leave them untracked?"
2. **Uncommitted changes exist:** Ask Craig - "There are uncommitted changes. Should I commit them now?"
3. **Unpushed commits exist:** Push them (this shouldn't require asking)
4. **Any other unclear state:** Ask Craig before proceeding

*** The Rule

Unless Craig explicitly says "leave git dirty" or "don't worry about that file," the working tree must be clean at session end. When in doubt, ASK.

** Step 5: Valediction

Provide a brief, warm goodbye message to Craig.

*** Format for Valediction

Include these elements (but keep it concise - 3-4 sentences total):

1. **Acknowledge the session:**
   - What was accomplished
   - Key milestone or achievement

2. **Confirm readiness for next session:**
   - What's ready to go
   - What should be worked on next

3. **Surface important reminders:**
   - Critical deadlines approaching
   - Time-sensitive actions needed

4. **Warm closing:**
   - Brief personal touch
   - Looking forward to next session

*** Example Valediction

#+begin_example
That's a wrap! We've prepared a comprehensive documentation package for
Jonathan with all the key evidence showing the $38,060 in unapproved charges.
The package is ready in jonathan-email-and-docs/ for you to review and send
this weekend.

Remember: Axelrad inspection must happen before drywall closes (urgent), and
the $5,000 retainer check should go out when the representation agreement
arrives.

Everything's committed and pushed. Looking forward to seeing how Jonathan's
demand letter strategy works out. Have a good evening!
#+end_example

*** Tone Guidelines

- **Warm but professional** - friendly without being overly casual
- **Concise** - 3-4 sentences, not a long summary
- **Forward-looking** - what's ready for next time
- **Acknowledging** - recognize the work accomplished
- **Helpful** - surface 1-2 critical reminders if they exist

Do NOT:
- Write a long detailed summary (that's in Session History)
- Use emoji or overly casual language
- Be generic ("Good session, see you next time")
- Miss surfacing critical deadlines or reminders

* Tips for Effective Wrap-Ups

** Session Notes

1. **Write notes in Craig's voice** - He's the one who will read them later
2. **Be specific** - "Created docs/MARK-MEETING-REFERENCE-GUIDE.org" not "created some docs"
3. **Include file paths** - Makes it easy to find referenced files
4. **Note decisions and rationale** - Not just what was done, but why
5. **Flag time-sensitive items clearly** - Use "URGENT" or "CRITICAL" when appropriate

** Git Commits

1. **Review the diff before committing** - Make sure you understand what changed
2. **One commit per session** - Don't create multiple commits during wrap-up
3. **Keep subject line under 72 characters** - Follows git best practices
4. **Be descriptive but concise** - Balance brevity with clarity
5. **NEVER include Claude attribution** - Commits are from Craig only

** Valediction

1. **Read the room** - If it was a tough/frustrating session, acknowledge that
2. **Surface critical reminders** - Don't let important deadlines slip
3. **Be genuine** - Sincerity matters more than polish
4. **Keep it brief** - Respect Craig's time at end of session
5. **End on positive note** - Even if session was challenging

* Common Mistakes to Avoid

1. **Forgetting to push to all remotes** - Check =git remote -v= and push to each
2. **Including Claude attribution in commits** - Commits should be from Craig only
3. **Writing session notes in Claude's voice** - Write as if Craig is documenting
4. **Generic valediction** - Be specific about what was accomplished
5. **Skipping context for next session** - Future you/Claude needs to know what's next
6. **Not surfacing critical reminders** - Time-sensitive items must be highlighted
7. **Writing commit message like a conversation** - Keep it professional and terse
8. **Forgetting to verify clean working tree** - Always confirm =git status= shows clean
9. **Making session notes too brief** - Better too much detail than too little
10. **Not checking if files were actually modified** - Run =git status= first
11. **Leaving session-context.org behind** - MUST be deleted at end of every wrap-up
12. **Leaving dirty git state without explicit approval** - Ask Craig if anything is unclear

* Validation Checklist

Before considering wrap-up complete, verify:

- [ ] Session History entry added to notes.org with today's date
- [ ] Work completed is clearly documented
- [ ] Context for next session is captured
- [ ] Key decisions and rationale are recorded
- [ ] Sessions beyond the 5 most recent moved to previous-session-history.org (if any)
- [ ] =git status= showed files to commit (if nothing changed, skip git steps)
- [ ] =git add .= executed to stage all changes
- [ ] Commit message follows required format (no Claude attribution)
- [ ] Commit executed successfully
- [ ] Pushed to ALL remote repositories (checked with =git remote -v=)
- [ ] =git status= shows "nothing to commit, working tree clean" (CRITICAL - ask if unclear)
- [ ] Push confirmed successful to all remotes
- [ ] =docs/session-context.org= DELETED (CRITICAL - file must not exist after wrap-up)
- [ ] Valediction provided with accomplishments, readiness, reminders
- [ ] Critical reminders surfaced if they exist
- [ ] Warm, professional closing provided

* Meta Notes

This workflow should evolve based on experience:

- If wrap-ups consistently miss something important, update the checklist
- If commit message format causes problems, revise the requirements
- If session notes format isn't working, adjust the template
- Craig can modify this workflow at any time to better fit needs

The goal is clean handoffs between sessions, not rigid adherence to format.