diff options
Diffstat (limited to 'docs/workflows/wrap-it-up.org')
| -rw-r--r-- | docs/workflows/wrap-it-up.org | 527 |
1 files changed, 527 insertions, 0 deletions
diff --git a/docs/workflows/wrap-it-up.org b/docs/workflows/wrap-it-up.org new file mode 100644 index 0000000..1ab31ec --- /dev/null +++ b/docs/workflows/wrap-it-up.org @@ -0,0 +1,527 @@ +#+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. |