diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/NOTES.org | 247 | ||||
| -rw-r--r-- | docs/previous-session-history.org | 13 | ||||
| -rw-r--r-- | docs/protocols.org | 360 | ||||
| -rw-r--r-- | docs/scripts/eml-view-and-extract-attachments.py | 53 | ||||
| -rw-r--r-- | docs/someday-maybe.org | 0 | ||||
| -rw-r--r-- | docs/workflows/create-v2mom.org | 691 | ||||
| -rw-r--r-- | docs/workflows/create-workflow.org | 354 | ||||
| -rw-r--r-- | docs/workflows/journal-entry.org | 209 | ||||
| -rw-r--r-- | docs/workflows/refactor.org | 617 | ||||
| -rw-r--r-- | docs/workflows/session-start.org | 540 | ||||
| -rw-r--r-- | docs/workflows/session-wrap-up.org | 484 | ||||
| -rw-r--r-- | docs/workflows/v2mom.org | 1 | ||||
| -rw-r--r-- | docs/workflows/whats-next.org | 146 |
13 files changed, 3715 insertions, 0 deletions
diff --git a/docs/NOTES.org b/docs/NOTES.org new file mode 100644 index 0000000..f56e7bd --- /dev/null +++ b/docs/NOTES.org @@ -0,0 +1,247 @@ +#+TITLE: Claude Code Notes - [Project Name] +#+AUTHOR: Craig Jennings & Claude +#+DATE: [Date] + +* About This File + +This file contains project-specific information for this project. + +**When to read this:** +- At the start of EVERY session (after reading protocols.org) +- When needing project context or history +- When checking reminders or pending decisions + +**What's in this file:** +- Project-specific context and goals +- Available workflows for this project +- Active reminders +- Pending decisions +- Session history + +**For protocols and conventions, see:** [[file:protocols.org][protocols.org]] + +* Project-Specific Context + +This is where context regarding this project is placed. + +Examples of what goes here: +- Project overview and goals +- People and their relationships to the user +- Contact information for companies and people +- Current state of the project +- Status report +- Links to important documents +- Technical architecture notes +- Key decisions and rationale + +** Welcome to Your First Session! + +This is your first session with Craig on this project. + +**First session checklist:** +1. **Determine project type and git/docs policy:** + - Is this project in a git repository? + - **Is this a code project** (Emacs package, library, software project)? + - **YES (code project):** Add docs/ to .gitignore (private notes, not part of codebase) + - Examples: org-msg, chime.el, wttrin, or any future Emacs packages/libraries + - docs/ contains session notes and should remain private + - **NO (non-code project):** Commit docs/ normally (part of the project documentation) + - Examples: personal projects, business planning, documentation projects + - docs/ is project documentation and should be versioned + - What are the remote repositories (if any)? + +2. **Understand the project:** + - Ask what the project is about + - Ask what the goals of the project are + - Ask any clarifying questions along the way + +3. **Brainstorm how to help:** + - Discuss approaches and strategies + - Identify immediate next steps + +4. **Document learnings:** + - Record what you learned in relevant sections of this document + - Add project-specific context below this section + +5. **Clean up:** + - Remove this "Welcome to Your First Session!" heading and its content + - Update Project-Specific Context section with actual project information + +* AVAILABLE WORKFLOWS + +This section lists all documented workflows for this project. Update this section whenever a new workflow is created. + +** create-workflow +File: [[file:workflows/create-workflow.org][docs/workflows/create-workflow.org]] + +Meta-workflow for creating new workflows. Use this when identifying repetitive workflows that would benefit from documentation. + +Workflow: +1. Q&A discovery (4 core questions) +2. Assess completeness +3. Name the workflow +4. Document it +5. Update NOTES.org +6. Validate by execution + +Created: [Date when workflow was created] + +** create-v2mom +File: [[file:workflows/create-v2mom.org][docs/workflows/create-v2mom.org]] + +Workflow for creating a V2MOM (Vision, Values, Methods, Obstacles, Metrics) strategic framework for any project or goal. + +Workflow: +1. Understand V2MOM framework +2. Create document structure +3. Define Vision (aspirational picture of success) +4. Define Values (2-4 principles with concrete definitions) +5. Define Methods (4-7 approaches ordered by priority) +6. Identify Obstacles (honest personal/technical challenges) +7. Define Metrics (measurable outcomes) +8. Review and refine +9. Commit and use immediately + +Time: ~2-3 hours total +Applicable to: Any project (health, finance, software, personal infrastructure, etc.) + +Created: 2025-11-05 + +** session-start +File: [[file:workflows/session-start.org][docs/workflows/session-start.org]] + +Workflow for beginning a Claude Code session with proper context and priorities. + +Triggered by: **Automatically at the start of EVERY session** + +Workflow: +1. Add session start timestamp (check for interrupted sessions) +2. Sync with templates (exclude NOTES.org and previous-session-history.org) +3. Scan workflows directory for available workflows +4. Read key NOTES.org sections (NOT entire file) +5. Process inbox (mandatory) +6. Ask about priorities (urgent work vs what's-next workflow) + +Ensures: Full context, current templates, processed inbox, clear session direction + +Created: 2025-11-14 + +** session-wrap-up +File: [[file:workflows/session-wrap-up.org][docs/workflows/session-wrap-up.org]] + +Workflow for ending a Claude Code session cleanly with proper documentation and version control. + +Triggered by: "wrap it up," "that's a wrap," "let's call it a wrap," or similar phrases + +Workflow: +1. Write session notes to NOTES.org Session History section +2. Archive sessions older than 5 sessions to previous-session-history.org +3. Git commit and push all changes (NO Claude attribution) +4. Provide brief valediction with accomplishments and next steps + +Ensures: Clean handoff between sessions, nothing lost, clear git history, proper documentation + +Created: 2025-11-14 + +** [Add more workflows as they are created] + +Format for new entries: +#+begin_example +** workflow-name +File: [[file:workflows/workflow-name.org][docs/workflows/workflow-name.org]] + +Brief description of what this workflow does. + +Workflow: +1. Step 1 +2. Step 2 +3. Step 3 + +Created: YYYY-MM-DD +#+end_example + +* PENDING DECISIONS + +This section tracks decisions that need Craig's input before work can proceed. + +**Instructions:** +- Add pending decisions as they arise during sessions +- Format: =** [Topic/Feature Name]= +- Include: What needs to be decided, options available, why it matters +- Remove decisions once resolved (document resolution in Session History) + +**Example format:** +#+begin_example +** Feature Name or Topic + +Craig needs to decide on [specific question]. + +Options: +1. Option A - [brief description, pros/cons] +2. Option B - [brief description, pros/cons] + +Why this matters: [impact on project] + +Implementation is ready - just need Craig's preference. +#+end_example + +** Current Pending Decisions + +(None currently - will be added as they arise) + +* Active Reminders + +** Current Reminders + +(None currently - will be added as needed) + +** Instructions for This Section + +When Craig says "remind me" about something: +1. Add it here with timestamp and description +2. If it's a TODO, also add to =/home/cjennings/sync/org/roam/inbox.org= scheduled for today +3. Check this section at start of every session +4. Remove reminders once addressed + +Format: +- =[YYYY-MM-DD]= Description of what to remind Craig about + +* Session History + +This section contains notes from each session with Craig. Sessions are logged in reverse chronological order (most recent first). + +**Note:** Sessions older than 5 sessions are archived in [[file:previous-session-history.org][Previous Session History]] + +** Format for Session History Entries + +Each entry should use this format: + +- **Timestamp:** =*** YYYY-MM-DD Day @ HH:MM TZ= (get TZ with =date +%z=) +- **Time estimate:** How long the session took +- **Status:** COMPLETE / IN PROGRESS / PAUSED +- **What We Completed:** Bulleted list of accomplishments +- **Key Decisions:** Any important decisions made +- **Files Modified:** Links to changed files (use relative paths) +- **Next Steps:** What to do next session (if applicable) + +**Best practices:** +- Keep entries concise but informative +- Include enough context to resume work later +- Document important technical insights +- Note any new patterns or preferences discovered +- Link to files using org-mode =file:= links + +** Session Entries + +*** [First session date] + +*Time:* Initial setup +*Status:* COMPLETE - Template created + +*What We Completed:* +- Project initialized with Claude Code templates +- Ready for first work session + +*Next Steps:* +- Begin first actual work session +- Follow "Welcome to Your First Session!" checklist above diff --git a/docs/previous-session-history.org b/docs/previous-session-history.org new file mode 100644 index 0000000..ae0e090 --- /dev/null +++ b/docs/previous-session-history.org @@ -0,0 +1,13 @@ +#+TITLE: Previous Session History +#+AUTHOR: Craig Jennings & Claude +#+DATE: 2025-11-14 + +* About This File + +This file contains archived session history entries older than 2 weeks from the current date. Sessions are automatically moved here during the wrap-up workflow to keep NOTES.org at a manageable size. + +Sessions are listed in reverse chronological order (most recent first). + +* Archived Sessions + +(Sessions older than 2 weeks will be moved here automatically) diff --git a/docs/protocols.org b/docs/protocols.org new file mode 100644 index 0000000..6a35196 --- /dev/null +++ b/docs/protocols.org @@ -0,0 +1,360 @@ +#+TITLE: Claude Code Protocols +#+AUTHOR: Craig Jennings & Claude +#+DATE: 2025-11-05 + +* About This File + +This file contains instructions and protocols for how Claude should behave when working with Craig. These protocols are consistent across all projects. + +**When to read this:** +- At the start of EVERY session (before NOTES.org) +- Before making any significant decisions +- When unclear about user preferences or conventions + +**What's in this file:** +- Session management protocols (context files, compacting) +- Terminology and trigger phrases +- User information and preferences +- Git commit requirements +- File format and naming conventions + +**What's NOT in this file:** +- Project-specific context (see NOTES.org) +- Session history (see NOTES.org) +- Active reminders (see NOTES.org) +- Pending decisions (see NOTES.org) + +* IMPORTANT - MUST DO + +** CRITICAL: Session Context File (docs/session-context.org) + +***THIS IS NON-NEGOTIABLE. FAILURE TO MAINTAIN THIS FILE CAUSES LOST WORK.*** + +The session context file is your lifeline for crash recovery. Without it, interrupted sessions lose all context. + +*** Location +=docs/session-context.org= (always this exact path) + +*** When to Update - EVERY OTHER EXCHANGE +After every other interaction with Craig, update the session context file. This is not optional. Set a mental counter: respond, respond, UPDATE FILE, respond, respond, UPDATE FILE. + +*** What to Include +- Current task/goal being worked on +- Key decisions made this session +- Data collected (vitals, measurements, etc.) +- Files modified +- Next steps planned +- Any context needed to resume if session crashes + +*** Why This Matters +If the power goes out, the network drops, or Claude crashes, the ONLY way to recover context is this file. Session history in NOTES.org is written at wrap-up - if we never reach wrap-up, that context is LOST unless it's in session-context.org. + +*** At Session Start - CHECK FOR THIS FILE +If =docs/session-context.org= exists when starting a new session, it means the previous session was interrupted. Read it immediately to recover context. + +** Before Compacting +If you know you're about to compact, update the session context file FIRST, with enough detail that you can pick up the discussion without having lost any essential information. + +** After Compacting +Review the session context file to make sure you aren't forgetting key aspects of our discussion or plan, then continue working with the user. + +** When Session Ends (Wrap-Up Workflow) +Write your session summary to NOTES.org, leveraging the session context file. Delete session-context.org ONLY AFTER you've written the session history entry. The file's existence indicates an interrupted session, so it must be deleted at the end of each successful wrap-up. + +* Important Terminology + +** "Let's run the [X] workflow" vs "I want to create an [X] workflow" + +These phrases mean DIFFERENT things! + +*** "Let's run/do the [workflow name] workflow" +This means: **Execute the existing workflow** for that process. + +*Example:* +- "Let's run the refactor workflow" -> Read docs/workflows/refactor.org and guide through workflow +- "Let's do a refactor workflow" -> Same as above + +*** "I want to create an [X] workflow" +This means: **CREATE a new workflow definition** for doing X (meta-work). +This does **NOT** mean "let's DO X right now." + +*Example:* +- "I want to create a refactor workflow" -> Create docs/workflows/refactor.org using create-workflow process + +When Craig uses this phrasing, trigger the create-workflow process from docs/workflows/create-workflow.org. + +** "Wrap it up" / "That's a wrap" / "Let's call it a wrap" + +Execute the wrap-up workflow (details in Session Protocols section below): +1. Write session notes to NOTES.org +2. Git commit and push all changes +3. Valediction summary + +* User Information + +** Calendar Location +Craig's calendar is available at: =/home/cjennings/sync/org/gcal.org= + +Use this to: +- Check meeting times and schedules +- Verify when events occurred +- See what's upcoming + +If there are tasks or events to schedule, put them in the todo.org file in the project root, not in Craig's calendar. + +** Task List Location +Craig's global task list is available at: =/home/cjennings/sync/org/roam/inbox.org= + +Use this to: +- See all the tasks that he's working on outside of projects like this one + +**Note:** Some projects may have a project-specific task file (e.g., =todo.org= at project root). Check NOTES.org for project-specific task locations. + +** Working Style + +*** General Preferences +- Prefers detailed preparation before high-stakes meetings +- Values practice/role-play for negotiations and general learning +- Makes decisions based on principles and timeline arguments +- Prefers written documentation over verbal agreements + +*** Emacs as a Primary Working Tool +- Craig uses Emacs as his primary tool (most everything Craig does is inside Emacs) +- Consider Emacs packages along with other software when recommending software solutions +- Look for ways to streamline routine work with Emacs custom code if no packages exist + +** Miscellaneous Information +- Craig currently lives in New Orleans, LA +- Craig's phone number: 510-316-9357 +- Craig maintains a remote server at the cjennings.net domain +- This project is in a git repository which is associated with a remote repository on cjennings.net + +** Shell Functions - Alarms + +Craig has a shell function for setting reminders. + +**IMPORTANT:** Always check the current date and time (=date=) before setting alarms to ensure accurate calculations. + +*** alarm (PERSISTENT - use for reminders) +Sets an alarm at a specific time using the =at= daemon. Persists after session ends. +#+begin_example +alarm 10:10am "Take BP reading" +alarm 2:00pm "Leave for PT" +#+end_example + +*** Managing alarms +- =atq= - list all scheduled alarms +- =atrm [number]= - remove an alarm by its queue number + +* Session Protocols + +** CRITICAL: Git Commit Requirements + +***IMPORTANT: ALL commits must be made as Craig, NOT as Claude.*** + +***CRITICAL: NO Claude Code or Anthropic attribution ANYWHERE in commits.*** + +When creating commits: + +1. **Author Identity**: NEVER commit as Claude. All commits must use Craig's identity. + - Git will use the configured user.name and user.email + - Do NOT modify git config + - **ABSOLUTELY NO** Co-Authored-By lines + - **ABSOLUTELY NO** "Generated with Claude Code" text + - **ABSOLUTELY NO** Anthropic attribution of any kind + - Write commits AS CRAIG, not as Claude Code + +2. **Commit Message Format**: + - Use project-specific commit format if defined + - Otherwise: concise subject line and terse description only + - **ONLY subject line and terse description - NO Claude Code attribution** + - Keep messages clear and informative + +3. **Validation**: + - Claude should validate commit message format before committing + - Ensure no AI attribution appears anywhere in commit + +** IMPORTANT: Reminders Protocol + +When starting a new session: +- Check "Active Reminders" section in NOTES.org +- Remind Craig of outstanding tasks he's asked to be reminded about +- This ensures important follow-up actions aren't forgotten between sessions + +When Craig says "remind me" about something: +1. Add it to Active Reminders section in NOTES.org +2. If it's something he needs to DO, also add to the todo.org file in the project root as an org-mode task (e.g., =* TODO [description]=). If this project does not have a todo.org at the project root, alert Craig and offer to create it. +3. If not already provided, ask for the priority and a date for scheduled or deadline. + +** Workflows: "Let's run/do the [workflow name] workflow" + +When Craig says this phrase: + +1. **Check for exact match** in docs/workflows/ directory + - If exact match found: Read =docs/workflows/[workflow-name].org= and guide through process + - Example: "refactor workflow" -> read docs/workflows/refactor.org + +2. **If no exact match but similar word exists:** Ask for clarification + - Example: User says "empty inbox" but we have "inbox-zero.org" + - Ask: "Did you mean the 'inbox zero' workflow, or create new 'empty inbox'?" + +3. **If no match at all:** Offer to create it + - Say: "I don't see '[workflow-name]' yet. Create it using create-workflow process?" + - If yes: Run create-workflow to define it, then use immediately (validates new workflow) + +** "Wrap it up" / "That's a wrap" / "Let's call it a wrap" + +When Craig says any of these phrases (or variations), execute wrap-up workflow: + +1. **Write session notes** to NOTES.org (Session History section) + - Key decisions made + - Work completed + - Context needed for next session + - Any pending issues or blockers + - New conventions or preferences learned + - Critical reminders for tomorrow go in Active Reminders section + +2. **Git commit and push** (if project is in git repository) + - Check git status and diff + - Create commit message following requirements (see "Git Commit Requirements" above) + - **ONLY subject line and terse description - NO Claude Code attribution** + - Commit as Craig (NOT as Claude) + - **ABSOLUTELY NO** Co-Authored-By, Claude Code, or Anthropic attribution + - Push to ALL remotes (check with =git remote -v=) + - Ensure working tree is clean + - Confirm push succeeded to all remotes + +3. **Valediction** - Brief, warm goodbye + - Acknowledge the day's work + - What was accomplished + - What's ready for next session + - Any important reminders + - Keep it warm but concise + +This ensures clean handoff between sessions and nothing gets lost. + +** The docs/ Directory + +Claude needs to add information to NOTES.org. For large amounts of information: + +- Create separate document in docs/ directory +- Link it in NOTES.org with explanation of document's purpose +- **Project-specific decision:** Should docs/ be committed to git or added to .gitignore? + - Ask Craig on first session if not specified + - Some projects keep docs/ private, others commit it +- Unless specified otherwise, all Claude-generated documents go in docs/ folder + +**When to break out documents:** +- If NOTES.org gets very large (> 1500 lines) +- If information isn't all relevant anymore +- Example: Keep only last 3-4 months of session history here, move rest to separate file + +* File Format Preferences + +** ALWAYS Use Org-Mode Format + +Craig uses Emacs as primary tool. **ALWAYS** create new documentation files in =.org= format, not =.md= (markdown). + +*Rationale:* +- Org-mode files are well-supported in Emacs +- Can be easily exported to any other format (HTML, PDF, Markdown, etc.) +- Better integration with user's workflow + +*Exception:* Only use .md if specifically requested or if file is intended for GitHub/web display where markdown is expected. + +** NEVER Use Spaces in Filenames + +**ALWAYS** use hyphens (=-=) to separate words in filenames. Underscores (=_=) are also acceptable. + +*Rationale:* +- Spaces cause problems with links across different operating systems +- User works with Mac, Windows, Linux, and potentially other systems +- Hyphens create more reliable, portable filenames +- Easier to work with in command-line tools + +*Examples:* +- Good: =project-meeting-notes.org= +- Good: =change-log-2025-11-04.md= +- Bad: =project meeting notes.org= +- Bad: =change log 2025.11.04.md= + +* File Naming Conventions + +** Files Too Large to Read + +PDFs or other files that are too large for Claude to read should be prefixed with =TOOLARGE-= to prevent read errors that halt the session. + +Example: +- Original: =assets/large-architectural-plans.pdf= +- Renamed: =assets/TOOLARGE-large-architectural-plans.pdf= + +** Unreadable Binary Files (.docx Format) + +Binary .docx files cannot be read directly by Claude. When encountering these: +- Convert to markdown format using pandoc: =pandoc file.docx -o file.md= +- Keep the original .docx file for reference +- Work with the converted .md file for analysis and editing + +** CRITICAL: Always Keep Links Current + +Many documents are linked in org files using org-mode =file:= links. Craig relies on these links being valid at all times. + +**MANDATORY WORKFLOW - When renaming or moving ANY file:** + +1. **BEFORE renaming:** Search ALL org files for references to that file + - Use grep or search tools to find both filename and partial matches + - Check in TODO items and event log sections + +2. **Rename or move the file** + +3. **IMMEDIATELY AFTER:** Update ALL =file:= links to new path/filename + - Update links in task files + - Update links in event logs + - Update links in reference sections + +4. **Verify:** Test a few updated links to ensure they point to valid files + +Example workflow: +#+begin_example +# Step 1: Search before renaming +grep -rn "2025-10-15-invoice.pdf" *.org + +# Step 2: Rename the file +mv documents/2025-10-15-invoice.pdf documents/2025-10-15-vendor-invoice.pdf + +# Step 3: Update all references in affected .org files +# Edit to change: +# file:documents/2025-10-15-invoice.pdf +# to: +# file:documents/2025-10-15-vendor-invoice.pdf + +# Step 4: Verify links work +#+end_example + +*Why This is Critical:* +- Org files are primary task tracking and reference system +- Event logs document complete history with file references +- Craig depends on clicking links to access documents quickly +- Broken links disrupt workflow and make documentation unreliable + +**NEVER rename or move files without updating links in the same session.** + +* Session Start - AUTOMATIC + +**IMPORTANT: At the start of EVERY session, Claude MUST:** + +1. **Read this file (protocols.org)** - You're doing this now +2. **Read NOTES.org** - For project-specific context, reminders, and history +3. **Execute the session-start workflow** - Defined in [[file:workflows/session-start.org][docs/workflows/session-start.org]] + +**Do NOT ask** if Craig wants to run the session-start workflow. Just do it automatically and report the results. + +The session-start workflow includes: +- Checking for interrupted previous sessions +- Syncing with templates +- Scanning available workflows +- Processing inbox +- Surfacing active reminders +- Asking about priorities + +See [[file:workflows/session-start.org][session-start.org]] for full details. diff --git a/docs/scripts/eml-view-and-extract-attachments.py b/docs/scripts/eml-view-and-extract-attachments.py new file mode 100644 index 0000000..f498b83 --- /dev/null +++ b/docs/scripts/eml-view-and-extract-attachments.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +import email +import sys +import os + +def extract_attachments(eml_file): + with open(eml_file, 'rb') as f: + msg = email.message_from_binary_file(f) + + # Extract plain text body + body_text = "" + for part in msg.walk(): + if part.get_content_type() == "text/plain": + body_text = part.get_payload(decode=True).decode('utf-8', errors='ignore') + break + elif part.get_content_type() == "text/html": + # Fallback to HTML if no plain text + if not body_text: + body_text = part.get_payload(decode=True).decode('utf-8', errors='ignore') + + # Print email metadata and body + print(f"From: {msg.get('From')}") + print(f"To: {msg.get('To')}") + print(f"Subject: {msg.get('Subject')}") + print(f"Date: {msg.get('Date')}") + print() + print(body_text) + print() + + # Extract attachments + attachments = [] + for part in msg.walk(): + if part.get_content_maintype() == 'multipart': + continue + if part.get('Content-Disposition') is None: + continue + + filename = part.get_filename() + if filename: + filepath = os.path.join(os.path.dirname(eml_file), filename) + with open(filepath, 'wb') as f: + f.write(part.get_payload(decode=True)) + attachments.append(filename) + print(f"Extracted attachment: {filename}") + + return attachments + +if __name__ == "__main__": + if len(sys.argv) < 2: + print("Usage: extract_attachments.py <eml_file>") + sys.exit(1) + + extract_attachments(sys.argv[1]) diff --git a/docs/someday-maybe.org b/docs/someday-maybe.org new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/someday-maybe.org diff --git a/docs/workflows/create-v2mom.org b/docs/workflows/create-v2mom.org new file mode 100644 index 0000000..6a0cb87 --- /dev/null +++ b/docs/workflows/create-v2mom.org @@ -0,0 +1,691 @@ +#+TITLE: Creating a V2MOM Strategic Framework +#+AUTHOR: Craig Jennings & Claude +#+DATE: 2025-11-05 + +* Overview + +This session creates a V2MOM (Vision, Values, Methods, Obstacles, Metrics) strategic framework for any project or goal. V2MOM provides clarity for decision-making, ruthless prioritization, and measuring progress. It transforms vague intentions into concrete action plans. + +The framework originated at Salesforce and works for any domain: personal projects, business strategy, health goals, financial planning, software development, or life planning. + +* Problem We're Solving + +Without a strategic framework, projects suffer from: + +** Unclear Direction +- "Get healthier" or "improve my finances" is too vague to act on +- Every idea feels equally important +- No principled way to say "no" to distractions +- Difficult to know what to work on next + +** Priority Inflation +- Everything feels urgent or important +- Research and planning without execution +- Hard to distinguish signal from noise +- Active todo list grows beyond manageability + +** No Decision Framework +- When faced with choice between A and B, no principled way to decide +- Debates about approach waste time +- Second-guessing decisions after making them +- Perfectionism masquerading as thoroughness + +** Unmeasurable Progress +- Can't tell if work is actually making things better +- No objective way to know when you're "done" +- Metrics are either absent or vanity metrics +- Difficult to celebrate wins or identify blockers + +*Impact:* Unfocused work, slow progress, frustration, and the nagging feeling that you're always working on the wrong thing. + +* Exit Criteria + +The V2MOM is complete when: + +1. **All 5 sections are filled with concrete content:** + - Vision: Clear, aspirational picture of success + - Values: 2-4 principles that guide decisions + - Methods: 4-7 concrete approaches with specific actions + - Obstacles: Honest personal/technical challenges + - Metrics: Measurable outcomes (not vanity metrics) + +2. **You can use it for decision-making:** + - Can answer "does X fit this V2MOM?" quickly + - Provides clarity on priorities (Method 1 > Method 2 > etc.) + - Identifies what NOT to do + +3. **Both parties agree it's ready:** + - Feels complete, not rushed + - Actionable enough to start execution + - Honest about obstacles (not sugar-coated) + +*Measurable validation:* +- Can you articulate the vision in one sentence? +- Do the values help you say "no" to things? +- Are methods ordered by priority? +- Can you immediately identify 3-5 tasks from Method 1? +- Do metrics tell you if you're succeeding? + +* When to Use This Session + +Trigger this V2MOM creation workflow when: + +- Starting a significant project (new business, new habit, new system) +- Existing project has accumulated many competing priorities without clear focus +- You find yourself constantly context-switching between ideas +- Someone asks "what are you trying to accomplish?" and answer is vague +- You want to apply ruthless prioritization but lack framework +- Annual/quarterly planning for ongoing projects or life goals + +*V2MOM is particularly valuable for:* +- Personal infrastructure projects (tooling, systems, workflows) +- Health and fitness goals +- Financial planning and wealth building +- Software package development +- Business strategy +- Career development +- Any long-running project where you're making the decisions + +* Approach: How We Work Together + +** Phase 1: Understand the V2MOM Framework + +Before starting, ensure both parties understand what each section means: + +- *Vision:* What you want to achieve (aspirational, clear picture of success) +- *Values:* Principles that guide decisions (2-4 values, defined concretely) +- *Methods:* How you'll achieve the vision (4-7 approaches, ordered by priority) +- *Obstacles:* What's in your way (honest, personal, specific) +- *Metrics:* How you'll measure success (objective, not vanity metrics) + +*Important:* V2MOM sections are completed IN ORDER. Vision informs Values. Values inform Methods. Methods reveal Obstacles. Everything together defines Metrics. + +** Phase 2: Create the Document Structure + +1. Create file: =docs/[project-name]-v2mom.org= or appropriate location +2. Add metadata: #+TITLE, #+AUTHOR, #+DATE, #+FILETAGS +3. Create section headings for all 5 components +4. Add "What is V2MOM?" overview section at top + +*Save incrementally:* V2MOM discussions can be lengthy. Save after completing each section to prevent data loss. + +** Phase 3: Define the Vision + +*Ask:* "What do you want to achieve? What does success look like?" + +*Goal:* Get a clear, aspirational picture. Should be 1-3 paragraphs describing the end state. + +*Claude's role:* +- Help articulate what's described +- Push for specificity ("works great" → what specifically works?) +- Identify scope (what's included, what's explicitly out of scope) +- Capture concrete examples mentioned + +*Good vision characteristics:* +- Paints a picture you can visualize +- Describes outcomes, not implementation +- Aspirational but grounded in reality +- Specific enough to know what's included + +*Examples across domains:* +- Health: "Wake up with energy, complete a 5K without stopping, feel strong in daily activities, and have stable mood throughout the day" +- Finance: "Six months emergency fund, debt-free except mortgage, automatic retirement savings, and financial decisions that don't cause anxiety" +- Software: "A package that integrates seamlessly, has comprehensive documentation, handles edge cases gracefully, and maintainers of other packages want to depend on" + +*Time estimate:* 15-30 minutes if vision is mostly clear; 45-60 minutes if needs exploration + +** Phase 4: Define the Values + +*Ask:* "What principles guide your decisions? When faced with choice A vs B, what values help you decide?" + +*Goal:* Identify 2-4 values with concrete definitions and examples. + +*Claude's role:* +- Suggest values based on vision discussion +- Push for concrete definitions (not just the word, but what it MEANS) +- Help distinguish between overlapping values +- Identify when examples contradict stated values + +*Common pitfall:* Listing generic words without defining them. +- Bad: "Quality, Speed, Innovation" +- Good: "Sustainable means can maintain this for 10+ years without burning out. No crash diets, no 80-hour weeks, no technical debt I can't service." + +*For each value, capture:* +1. **The value name** (1-2 words) +2. **Definition** (what this means in context of this project) +3. **Concrete examples** (how this manifests) +4. **What breaks this value** (anti-patterns) + +*Method:* +- Start with 3-5 candidate values +- For each one, ask: "What does [value] mean to you in this context?" +- Discuss until definition is concrete +- Write definition with examples +- Refine/merge/remove until 2-4 remain + +*Examples across domains:* +- Health V2MOM: "Sustainable: Can do this at 80 years old. No extreme diets. Focus on habits that compound over decades." +- Finance V2MOM: "Automatic: Set up once, runs forever. Don't rely on willpower for recurring decisions. Automate savings and investments." +- Software V2MOM: "Boring: Use proven patterns. No clever code. Maintainable by intermediate developers. Boring is reliable." + +*Time estimate:* 30-45 minutes + +** Phase 5: Define the Methods + +*Ask:* "How will you achieve the vision? What approaches will you take?" + +*Goal:* Identify 4-7 methods (concrete approaches) ordered by priority. + +*Claude's role:* +- Extract methods from vision and values discussion +- Help order by priority (what must happen first?) +- Ensure methods are actionable (not just categories) +- Push for concrete actions under each method +- Watch for method ordering that creates dependencies + +*Structure for each method:* +1. **Method name** (verb phrase: "Build X", "Eliminate Y", "Establish Z") +2. **Aspirational description** (1-2 sentences: why this matters) + +*Method ordering matters:* +- Method 1 should be highest priority (blocking everything else) +- Lower-numbered methods should enable higher-numbered ones +- Common patterns: + - Fix → Stabilize → Build → Enhance → Sustain + - Eliminate → Replace → Optimize → Automate → Maintain + - Learn → Practice → Apply → Teach → Systematize + +*Examples across domains:* + +Health V2MOM: +- Method 1: Eliminate Daily Energy Drains (fix sleep, reduce inflammatory foods, address vitamin deficiencies) +- Method 2: Build Baseline Strength (3x/week resistance training, progressive overload, focus on compound movements) +- Method 3: Establish Sustainable Nutrition (meal prep system, protein targets, vegetable servings) + +Finance V2MOM: +- Method 1: Stop the Bleeding (identify and eliminate wasteful subscriptions, high-interest debt, impulse purchases) +- Method 2: Build the Safety Net (automate savings, reach $1000 emergency fund, then 3 months expenses) +- Method 3: Invest for the Future (max employer 401k match, open IRA, set automatic contributions) + +Software Package V2MOM: +- Method 1: Nail the Core Use Case (solve one problem extremely well, clear documentation, handles errors gracefully) +- Method 2: Ensure Quality and Stability (comprehensive test suite, CI/CD, semantic versioning) +- Method 3: Build Community and Documentation (contribution guide, examples, responsive to issues) + +*Method Ordering is Flexible:* After defining all methods, you may realize the ordering is wrong. For example, security (Method 5) might be more important than tool modernization (Method 4). Methods can be swapped - the order represents priority, so getting it right matters more than preserving the initial order. + +*Time estimate:* 45-90 minutes (longest section) + +** Phase 5.6: Brainstorm Additional Tasks for Each Method + +Brainstorm what's missing to achieve the method. + +*Ask:* "What else would help achieve this method's goal?" + +*Claude's role:* +- Suggest additional tasks based on method's aspirational description +- Consider edge cases and error scenarios +- Identify automation opportunities +- Propose monitoring/visibility improvements +- Challenge if list feels incomplete, meaning the list isn't sufficient to reach the goal +- Challenge if the list feels too much, meaning items on the list aren't necessary to reach the goal +- Create sub-tasks using *** for items with multiple steps +- Ensure priorities reflect contribution to method goal + +*For each brainstormed task:* +- Describe what it does and why it matters +- Assign priority based on contribution to method +- Add technical details if known +- Get user agreement before adding + + +*Priority System:* +- [#A]: Critical blockers - must be done first, blocks everything else +- [#B]: High-impact reliability - directly enables method goal +- [#C]: Quality improvements - valuable but not blocking +- [#D]: Nice-to-have - low priority, can defer + + +*Time estimate:* 10-15 minutes per method (50-75 minutes for 5 methods) + +** Phase 6: Identify the Obstacles + +*Ask:* "What's in your way? What makes this hard?" + +*Goal:* Honest, specific obstacles (both personal and technical/external). + +*Claude's role:* +- Encourage honesty (obstacles are not failures, they're reality) +- Help distinguish between symptoms and root causes +- Identify patterns in behavior that create obstacles +- Acknowledge challenges without judgment + +*Good obstacle characteristics:* +- Honest about personal patterns +- Specific, not generic +- Acknowledges both internal and external obstacles +- States real stakes (not just "might happen") + +*Common obstacle categories:* +- Personal: perfectionism, hard to say no, gets bored, procrastinates +- Knowledge: missing skills, unclear how to proceed, need to learn +- External: limited time, limited budget, competing priorities +- Systemic: environmental constraints, lack of tools, dependencies on others + +*For each obstacle:* +- Name it clearly +- Describe how it manifests in this project +- Acknowledge the stakes (what happens because of this obstacle) + +*Examples across domains:* + +Health V2MOM obstacles: +- "I get excited about new workout programs and switch before seeing results (pattern: 6 weeks into a program)" +- "Social events involve food and alcohol - saying no feels awkward and isolating" +- "When stressed at work, I skip workouts and eat convenient junk food" + +Finance V2MOM obstacles: +- "Viewing budget as restriction rather than freedom - triggers rebellion and impulse spending" +- "Fear of missing out on lifestyle experiences my peers have" +- "Limited financial literacy - don't understand investing beyond 'put money in account'" + +Software Package V2MOM obstacles: +- "Perfectionism delays releases - always 'one more feature' before v1.0" +- "Maintaining documentation feels boring compared to writing features" +- "Limited time (2-4 hours/week) and competing projects" + +*Time estimate:* 15-30 minutes + +** Phase 7: Define the Metrics + +*Ask:* "How will you measure success? What numbers tell you if this is working?" + +*Goal:* 5-10 metrics that are objective, measurable, and aligned with vision/values. + +*Claude's role:* +- Suggest metrics based on vision, values, and methods +- Push for measurable numbers (not "better", but concrete targets) +- Identify vanity metrics (look good but don't measure real progress) +- Ensure metrics align with values and methods + +*Metric categories:* +- **Performance metrics:** Measurable outcomes of the work +- **Discipline metrics:** Process adherence, consistency, focus +- **Quality metrics:** Standards maintained, sustainability indicators + +*Good metric characteristics:* +- Objective (not subjective opinion) +- Measurable (can actually collect the data) +- Actionable (can change behavior to improve it) +- Aligned with values and methods + +*For each metric:* +- Name it clearly +- Specify current state (if known) +- Specify target state +- Describe how to measure it +- Specify measurement frequency + +*Examples across domains:* + +Health V2MOM metrics: +- Resting heart rate: 70 bpm → 60 bpm (measure: daily via fitness tracker) +- Workout consistency: 3x/week strength training for 12 consecutive weeks +- Sleep quality: 7+ hours per night 6+ nights per week (measure: sleep tracker) +- Energy rating: subjective 1-10 scale, target 7+ average over week + +Finance V2MOM metrics: +- Emergency fund: $0 → $6000 (measure: monthly) +- High-interest debt: $8000 → $0 (measure: monthly) +- Savings rate: 5% → 20% of gross income (measure: monthly) +- Financial anxiety: weekly check-in, target "comfortable with financial decisions" + +Software Package V2MOM metrics: +- Test coverage: 0% → 80% (measure: coverage tool) +- Issue response time: median < 48 hours (measure: GitHub stats) +- Documentation completeness: all public APIs documented with examples +- Adoption: 10+ GitHub stars, 3+ projects depending on it + +*Time estimate:* 20-30 minutes + +** Phase 8: Migrate Existing Tasks (If Applicable) + +If you have an existing TODO.org file with tasks, migrate them into the V2MOM methods. + +*Goal:* Consolidate all project tasks under V2MOM methods, eliminate duplicates, move non-fitting items to someday-maybe. + +*Process:* + +1. **Identify Duplicates:** + - Read existing TODO.org + - Find tasks already in V2MOM methods + - Check if V2MOM task has all technical details from TODO version + - Enhance V2MOM task with any missing details + - Mark TODO task for deletion + +2. **Map Tasks to Methods:** + - For each remaining TODO task, ask: "Which method does this serve?" + - Add task under appropriate method with priority + - Capture all technical details from original task + - If task has state (DOING, VERIFY), preserve that state + +3. **Review Someday-Maybe Candidates One-by-One:** + Present each task that doesn't fit methods and ask: + - Keep in V2MOM (which method)? + - Move to someday-maybe? + - Delete entirely? + +*Decision Criteria for Someday-Maybe:* +- Doesn't directly serve any method's goal +- Nice-to-have enhancement without clear benefit +- Research task without actionable outcome +- Architectural change decided not to pursue +- Personal task not related to project + +*Keep in V2MOM (don't move to someday-maybe):* +- DOING tasks - work in progress must continue +- VERIFY tasks - need testing/verification +- Tasks that enable method goals + +*Delete entirely:* +- Obsolete tasks (feature removed, problem solved elsewhere) +- Duplicate of something already done +- Task that no longer makes sense + +*For each task decision:* +- Present task with full context +- Wait for user decision +- Don't batch - review one by one +- Capture reasoning for future reference + +4. **Final Steps:** + - Append someday-maybe items to docs/someday-maybe.org + - Copy completed V2MOM to TODO.org (overwrite) + - V2MOM is now the single source of truth + +*Time estimate:* Highly variable +- Small TODO.org (20 tasks): 30-45 minutes +- Medium TODO.org (50 tasks): 60-90 minutes +- Large TODO.org (100+ tasks): 2-3 hours + +*Note:* This phase is optional - only needed if existing TODO.org has substantial content to migrate. + +** Phase 9: Review and Refine + +Once all sections are complete (including task migration if applicable), review the whole V2MOM together: + +*Ask together:* +1. **Does the vision excite you?** (If not, why not? What's missing?) +2. **Do the values guide decisions?** (Can you use them to say no to things?) +3. **Are the methods ordered by priority?** (Is Method 1 truly most important?) +4. **Are the obstacles honest?** (Or are you sugar-coating?) +5. **Will the metrics tell you if you're succeeding?** (Or are they vanity metrics?) +6. **Does this V2MOM make you want to DO THE WORK?** (If not, something is wrong) + +*Refinement:* +- Merge overlapping methods +- Reorder methods if priorities are wrong +- Add missing concrete actions +- Strengthen weak definitions +- Remove fluff + +*Red flags:* +- Vision doesn't excite you → Need to dig deeper into what you really want +- Values are generic → Need concrete definitions and examples +- Methods have no concrete actions → Too vague, need specifics +- Obstacles are all external → Need honesty about personal patterns +- Metrics are subjective → Need objective measurements + +** Phase 10: Commit and Use + +Once the V2MOM feels complete: + +1. **Save the document** in appropriate location +2. **Share with stakeholders** (if applicable) +3. **Use it immediately** (start Method 1 execution or first triage) +4. **Schedule first review** (1 week out: is this working?) + +*Why use immediately:* Validates the V2MOM is practical, not theoretical. Execution reveals gaps that discussion misses. + +* Principles to Follow + +** Honesty Over Aspiration + +V2MOM requires brutal honesty, especially in Obstacles section. + +*Examples:* +- "I get bored after 6 weeks" (honest) vs "Maintaining focus is challenging" (bland) +- "I have 3 hours per week max" (honest) vs "Time is limited" (vague) +- "I impulse-spend when stressed" (honest) vs "Budget adherence needs work" (passive) + +**Honesty enables solutions.** If you can't name the obstacle, you can't overcome it. + +** Concrete Over Abstract + +Every section should have concrete examples and definitions. + +*Bad:* +- Vision: "Be successful" +- Values: "Quality, Speed, Innovation" +- Methods: "Improve things" +- Metrics: "Do better" + +*Good:* +- Vision: "Complete a 5K in under 30 minutes, have energy to play with kids after work, sleep 7+ hours consistently" +- Values: "Sustainable: Can maintain for 10+ years. No crash diets, no injury-risking overtraining." +- Methods: "Method 1: Fix sleep quality (blackout curtains, consistent bedtime, no screens 1hr before bed)" +- Metrics: "5K time: current 38min → target 29min (measure: monthly timed run)" + +** Priority Ordering is Strategic + +Method ordering determines what happens first. Get it wrong and you'll waste effort. + +*Common patterns:* +- **Fix → Build → Enhance → Sustain** (eliminate problems before building) +- **Eliminate → Replace → Optimize** (stop damage before improving) +- **Learn → Practice → Apply → Teach** (build skill progressively) + +*Why Method 1 must address the blocker:* +- If foundation is broken, can't build on it +- High-impact quick wins build momentum +- Must stop the bleeding before starting rehab + +** Methods Need Concrete Actions + +If you can't list 3-8 concrete actions for a method, it's too vague. + +*Test:* Can you start working on Method 1 immediately after completing the V2MOM? + +If answer is "I need to think about what to do first", the method needs more concrete actions. + +*Example:* +- Too vague: "Method 1: Improve health" +- Concrete: "Method 1: Fix sleep quality → blackout curtains, consistent 10pm bedtime, no screens after 9pm, magnesium supplement, sleep tracking" + +** Metrics Must Be Measurable + +"Better" is not a metric. "Bench press 135 lbs" is a metric. + +*For each metric, you must be able to answer:* +1. How do I measure this? (exact method or tool) +2. What's the current state? +3. What's the target state? +4. How often do I measure it? +5. What does this metric actually tell me? + +If you can't answer these, it's not a metric yet. + +** V2MOM is Living Document + +V2MOM is not set in stone. As you execute: + +- Methods may need reordering (new information reveals priorities) +- Metrics may need adjustment (too aggressive or too conservative) +- New obstacles emerge (capture them) +- Values get refined (concrete examples clarify definitions) + +*Update the V2MOM when:* +- Major priority shift occurs +- New obstacle emerges that changes approach +- Metric targets prove unrealistic or too easy +- Method completion opens new possibilities +- Quarterly review reveals misalignment + +*But don't update frivolously:* Changing the V2MOM every week defeats the purpose. Update when major shifts occur, not when minor tactics change. + +** Use It or Lose It + +V2MOM only works if you use it for decisions. + +*Use it for:* +- Weekly reviews (am I working on right things?) +- Priority decisions (which method does this serve?) +- Saying no to distractions (not in the methods) +- Celebrating wins (shipped Method 1 items!) +- Identifying blockers (obstacles getting worse?) + +*If 2 weeks pass without referencing the V2MOM, something is wrong.* Either the V2MOM isn't serving you, or you're not using it. + +* Living Document + +This is a living document. After creating V2MOMs for different projects, consider: +- Did the process work well? +- Were any sections harder than expected? +- Did we discover better questions to ask? +- Should sections be created in different order? +- What patterns emerge across different domains? + +Update this session document with learnings to make future V2MOM creation smoother. + +* Examples: V2MOMs Across Different Domains + +** Example 1: Health and Fitness V2MOM (Brief) + +*Vision:* Wake up with energy, complete 5K comfortably, feel strong in daily activities, stable mood, no afternoon crashes. + +*Values:* +- Sustainable: Can do this at 80 years old +- Compound: Small daily habits over quick fixes + +*Methods:* +1. Fix Sleep Quality (blackout curtains, consistent bedtime, track metrics) +2. Build Baseline Strength (3x/week, compound movements, progressive overload) +3. Establish Nutrition System (meal prep, protein targets, hydration) + +*Obstacles:* +- Get excited about new programs, switch before results (6-week pattern) +- Social events involve alcohol and junk food +- Skip workouts when stressed at work + +*Metrics:* +- Resting heart rate: 70 → 60 bpm +- Workout consistency: 3x/week for 12 consecutive weeks +- 5K time: 38min → 29min + +** Example 2: Financial Independence V2MOM (Brief) + +*Vision:* Six months emergency fund, debt-free except mortgage, automatic investing, financial decisions without anxiety. + +*Values:* +- Automatic: Set up once, runs forever (don't rely on willpower) +- Freedom: Budget enables choices, not restricts them + +*Methods:* +1. Stop the Bleeding (eliminate subscriptions, high-interest debt, impulse purchases) +2. Build Safety Net ($1000 emergency fund → 3 months → 6 months) +3. Automate Investing (max 401k match, IRA, automatic contributions) + +*Obstacles:* +- View budget as restriction → triggers rebellion spending +- FOMO on experiences peers have +- Limited financial literacy + +*Metrics:* +- Emergency fund: $0 → $6000 +- Savings rate: 5% → 20% +- High-interest debt: $8000 → $0 + +** Example 3: Emacs Configuration V2MOM (Detailed) + +This V2MOM was created over 2 sessions in late 2025 and led to significant improvements in config quality and maintainability. + +*** The Context + +Craig's Emacs configuration had grown to ~50+ todo items, unclear priorities, and performance issues. Config was his most-used software (email, calendar, tasks, programming, reading, music) so breakage blocked all work. + +*** The Process (2 Sessions, ~2.5 Hours Total) + +*Session 1 (2025-10-30, ~1 hour):* +- Vision: Already clear from existing draft, kept as-is +- Values: Deep Q&A to define "Intuitive", "Fast", "Simple" + - Each value got concrete definition + examples + anti-patterns + - Intuitive: muscle memory + mnemonics + which-key timing + - Fast: < 3s startup, org-agenda is THE BOTTLENECK + - Simple: production practices, simplicity produces reliability + +*Session 2 (2025-10-31, ~1.5 hours):* +- Methods: Identified 6 methods through Q&A + - Method 1: Make Using Emacs Frictionless (fix daily pain) + - Method 2: Stop Problems Before They Appear (stability) + - Method 3: Make Fixing Emacs Frictionless (tooling) + - Method 4: Contribute to Ecosystem (package maintenance) + - Method 5: Be Kind To Future Self (new features) + - Method 6: Develop Disciplined Practices (meta-method) +- Obstacles: Honest personal patterns + - "Getting irritated at mistakes and pushing on" + - "Hard to say no to fun ideas" + - "Perfectionism delays shipping" +- Metrics: Measurable outcomes + - Startup time: 6.2s → < 3s + - Org-agenda rebuild: 30s → < 5s + - Active todos: 50+ → < 20 + - Weekly triage consistency + - Research:shipped ratio > 1:1 + +*** Immediate Impact + +After completing V2MOM: +- Ruthlessly triaged 50 todos → 23 (under < 20 target) +- Archived items not serving vision to someday-maybe.org +- Immediate execution: removed network check (2s improvement!) +- Clear decision framework for weekly inbox triage +- Startup improved: 6.19s → 4.16s → 3.8s (approaching target) + +*** Key Learnings + +1. **Vision was easy:** Already had clear picture of success +2. **Values took work:** Required concrete definitions, not just words +3. **Methods needed ordering:** Priority emerged from dependency discussion +4. **Obstacles required honesty:** Hardest to name personal patterns +5. **Metrics aligned with values:** "Fast" value → fast metrics (startup, org-agenda) + +*** Why It Worked + +- V2MOM provided framework to say "no" ruthlessly +- Method ordering prevented building on broken foundation +- Metrics were objective (seconds, counts) not subjective +- Obstacles acknowledged personal patterns enabling better strategies +- Used immediately for inbox triage (validated practicality) + +* Conclusion + +Creating a V2MOM transforms vague intentions into concrete strategy. It provides: + +- **Clarity** on what you're actually trying to achieve +- **Decision framework** for ruthless prioritization +- **Measurable progress** through objective metrics +- **Honest obstacles** that can be addressed +- **Ordered methods** that build on each other + +**The framework takes 2-3 hours to create. It saves weeks of unfocused work.** + +The V2MOM works across domains because the structure is universal: +- Vision: Where am I going? +- Values: What principles guide me? +- Methods: How do I get there? +- Obstacles: What's in my way? +- Metrics: How do I know it's working? + +*Remember:* V2MOM is a tool, not a trophy. Create it, use it, update it, and let it guide your work. If you're not using it weekly, either fix the V2MOM or admit you don't need one. + +*Final test:* Can you say "no" to something you would have said "yes" to before? If so, the V2MOM is working. diff --git a/docs/workflows/create-workflow.org b/docs/workflows/create-workflow.org new file mode 100644 index 0000000..9d2d739 --- /dev/null +++ b/docs/workflows/create-workflow.org @@ -0,0 +1,354 @@ +#+TITLE: Creating New Workflows +#+AUTHOR: Craig Jennings +#+DATE: 2025-11-01 + +* Overview + +This document describes the meta-workflow for creating new workflows. When we identify a repetitive workflow or collaborative pattern, we use this process to formalize it into a documented workflow that we can reference and reuse. + +Note the definitions: "sessions" are the time Claude spends with the user, i.e., the user starts a "session" with Claude, does some work, then ends the "session". A workflow is a routine or pattern of doing tasks within a session to accomplish a goal. + +Workflows are living documents that capture how we work together on specific types of tasks. They build our shared vocabulary and enable efficient collaboration across multiple work sessions. + +* Problem We're Solving + +Without a formal workflow creation process, we encounter several issues: + +** Inefficient Use of Intelligence +- Craig leads the process based solely on his knowledge +- We don't leverage Claude's expertise to improve or validate the approach +- Miss opportunities to apply software engineering and process best practices + +** Time Waste and Repetition +- Craig must re-explain the workflow each time we work together +- No persistent memory of how we've agreed to work +- Each session starts from scratch instead of building on previous work + +** Error-Prone Execution +- Important steps may be forgotten or omitted +- No checklist to verify completeness +- Mistakes lead to incomplete work or failed goals + +** Missed Learning Opportunities +- Don't capture lessons learned from our collaboration +- Can't improve processes based on what works/doesn't work +- Lose insights that emerge during execution + +** Limited Shared Vocabulary +- No deep, documented understanding of what terms mean +- "Let's do a refactor workflow" has no precise definition +- Can't efficiently communicate about workflows + +*Impact:* Inefficiency, errors, and lost opportunity to continuously improve our collaborative workflows. + +* Exit Criteria + +We know a workflow definition is complete when: + +1. **Information is logically arranged** - The structure makes sense and flows naturally +2. **Both parties understand how to work together** - We can articulate the workflow +3. **Agreement on effectiveness** - We both agree that following this workflow will lead to exit criteria and resolve the stated problem +4. **Tasks are clearly defined** - Steps are actionable, not vague +5. **Problem resolution path** - Completing the tasks either: + - Fixes the problem permanently, OR + - Provides a process for keeping the problem at bay + +*Measurable validation:* +- Can we both articulate the workflow without referring to the document? +- Do we agree it will solve the problem? +- Are the tasks actionable enough to start immediately? +- Does the workflow get used soon after creation (validation by execution)? + +* When to Use This Workflow + +Trigger this workflow creation workflow when: + +- You notice a repetitive workflow that keeps coming up +- A collaborative pattern emerges that would benefit from documentation +- Craig says "let's create/define/design a workflow for [activity]" +- You identify a new type of work that doesn't fit existing workflows +- An existing workflow needs significant restructuring (treat as creating a new one) + +Examples: +- "Let's create a workflow where we inbox zero" +- "We should define a code review workflow" +- "Let's design a workflow for weekly planning" + +* Approach: How We Work Together + +** Phase 1: Question and Answer Discovery + +Walk through these four core questions collaboratively. Take notes on the answers. + +*IMPORTANT: Save answers as you go!* + +The Q&A phase can take time—Craig may need to think through answers, and discussions can be lengthy. To prevent data loss from terminal crashes or process quits: + +1. Create a draft file at =docs/workflows/[name]-draft.org= after deciding on the name +2. After each question is answered, save the Q&A content to the draft file +3. If workflow is interrupted, you can resume from the saved answers +4. Once complete, the draft becomes the final workflow document + +This protects against losing substantial thinking work if the workflow is interrupted. + +*** Question 1: What problem are we solving in this type of workflow? + +Ask Craig: "What problem are we solving in this type of workflow? What would happen without this workflow?" + +The answer reveals: +- Overview and goal of the workflow +- Why this work matters (motivation) +- Impact/priority compared to other work +- What happens if we don't do this work + +Example from refactor workflow: +#+begin_quote +"My Emacs configuration isn't resilient enough. There's lots of custom code, and I'm even developing some as Emacs packages. Yet Emacs is my most-used software, so when Emacs breaks, I become unproductive. I need to make Emacs more resilient through good unit tests and refactoring." +#+end_quote + +*** Question 2: How do we know when we're done? + +Ask Craig: "How do we know when we're done?" + +The answer reveals: +- Exit criteria +- Results/completion criteria +- Measurable outcomes + +*Your role:* +- Push back if the answer is vague or unmeasurable +- Propose specific measurements based on context +- Iterate together until criteria are clear +- Fallback (hopefully rare): "when Craig says we're done" + +Example from refactor workflow: +#+begin_quote +"When we've reviewed all methods, decided which to test and refactor, run all tests, and fixed all failures including bugs we find." +#+end_quote + +Claude might add: "How about a code coverage goal of 70%+?" + +*** Question 3: How do you see us working together in this kind of workflow? + +Ask Craig: "How do you see us working together in this kind of workflow?" + +The answer reveals: +- Steps or phases we'll go through +- The general approach to the work +- How tasks flow from one to another + +*Your role:* +- As steps emerge, ask yourself: + - "Do these steps lead to solving the real problem?" + - "What is missing from these steps?" +- If the answers aren't "yes" and "nothing", raise concerns +- Propose additions based on your knowledge +- Suggest concrete improvements + +Example from refactor workflow: +#+begin_quote +"We'll analyze test coverage, categorize functions by testability, write tests systematically using Normal/Boundary/Error categories, run tests, analyze failures, fix bugs, and repeat." +#+end_quote + +Claude might suggest: "Should we install a code coverage tool as part of this process?" + +*** Question 4: Are there any principles we should be following while doing this? + +Ask Craig: "Are there any principles we should be following while doing this kind of workflow?" + +The answer reveals: +- Principles to follow +- Decision frameworks +- Quality standards +- When to choose option A vs option B + +*Your role:* +- Think through all elements of the workflow +- Consider situations that may arise +- Identify what principles would guide decisions +- Suggest decision frameworks from your knowledge + +Example from refactor workflow: +#+begin_quote +Craig: "Treat all test code as production code - same engineering practices apply." + +Claude suggests: "Since we'll refactor methods mixing UI and logic, should we add a principle to separate them for testability?" +#+end_quote + +** Phase 2: Assess Completeness + +After the Q&A, ask together: + +1. **Do we have enough information to formulate steps/process?** + - If yes, proceed to Phase 3 + - If no, identify what's missing and discuss further + +2. **Do we agree following this approach will resolve/mitigate the problem?** + - Both parties must agree + - If not, identify concerns and iterate + +** Phase 3: Name the Workflow + +Decide on a name for this workflow. + +*Naming convention:* Action-oriented (verb form) +- Examples: "refactor", "inbox-zero", "create-workflow", "review-code" +- Why: Shorter, natural when saying "let's do a [name] workflow" +- Filename: =docs/workflows/[name].org= + +** Phase 4: Document the Workflow + +Write the workflow file at =docs/workflows/[name].org= using this structure: + +*** Recommended Structure +1. *Title and metadata* (=#+TITLE=, =#+AUTHOR=, =#+DATE=) +2. *Overview* - Brief description of the workflow +3. *Problem We're Solving* - From Q&A, with context and impact +4. *Exit Criteria* - Measurable outcomes, how we know we're done +5. *When to Use This Workflow* - Triggers, circumstances, examples +6. *Approach: How We Work Together* + - Phases/steps derived from Q&A + - Decision frameworks + - Concrete examples woven throughout +7. *Principles to Follow* - Guidelines from Q&A +8. *Living Document Notice* - Reminder to update with learnings + +*** Important Notes +- Weave concrete examples into sections (don't separate them) +- Use examples from actual workflows when available +- Make tasks actionable, not vague +- Include decision frameworks for common situations +- Note that this is a living document + +** Phase 5: Update Project State + +Update =NOTES.org=: +1. Add new workflow to "Available Workflows" section +2. Include brief description and reference to file +3. Note creation date + +Example entry: +#+begin_src org +,** inbox-zero +File: =docs/workflows/inbox-zero.org= + +Workflow for processing inbox to zero: +1. [Brief workflow summary] +2. [Key steps] + +Created: 2025-11-01 +#+end_src + +** Phase 6: Validate by Execution + +*Critical step:* Use the workflow soon after creating it. + +- Schedule the workflow for immediate use +- Follow the documented workflow +- Note what works well +- Identify gaps or unclear areas +- Update the workflow document with learnings + +*This validates the workflow definition and ensures it's practical, not theoretical.* + +* Principles to Follow + +These principles guide us while creating new workflows: + +** Collaboration Through Discussion +- Be proactive about collaboration +- Suggest everything on your mind +- Ask all relevant questions +- Push back when something seems wrong, inconsistent, or unclear +- Misunderstandings are learning opportunities + +** Reviewing the Whole as Well as the Pieces +- May get into weeds while identifying each step +- Stop to look at the whole thing at the end +- Ask the big questions: Does this actually solve the problem? +- Verify all pieces connect logically + +** Concrete Over Abstract +- Use examples liberally within explanations +- Weave concrete examples into Q&A answers +- Don't just describe abstractly +- "When nil input crashes, ask..." is better than "handle edge cases" + +** Actionable Tasks Over Vague Direction +- Steps should be clear enough to know what to do next +- "Ask: how do you see us working together?" is actionable +- "Figure out the approach" is too vague +- Test: Could someone execute this without further explanation? + +** Validate Early +- "Use it soon afterward" catches problems early +- Don't let workflow definitions sit unused and untested +- Real execution reveals gaps that theory misses +- Update immediately based on first use + +** Decision Frameworks Over Rigid Steps +- Workflows are frameworks (principles + flexibility), not recipes +- Include principles that help case-by-case decisions +- "When X happens, ask Y" is a decision framework +- "Always do X" is too rigid for most workflows + +** Question Assumptions +- If something doesn't make sense, speak up +- If a step seems to skip something, point it out +- Better to question during creation than discover gaps during execution +- No assumption is too basic to verify + +* Living Document + +This is a living document. As we create new workflows and learn what works (and what doesn't), we update this file with: + +- New insights about workflow creation +- Improvements to the Q&A process +- Better examples +- Additional principles discovered +- Refinements to the structure + +Every time we create a workflow, we have an opportunity to improve this meta-process. + +** Updates and Learnings + +*** 2025-11-01: Save Q&A answers incrementally +*Learning:* During emacs-inbox-zero workflow creation, we discovered that Q&A discussions can be lengthy and make Craig think deeply. Terminal crashes or process quits can lose substantial work. + +*Improvement:* Added guidance in Phase 1 to create a draft file and save Q&A answers after each question. This protects against data loss and allows resuming interrupted workflows. + +*Impact:* Reduces risk of losing 10-15 minutes of thinking work if workflow is interrupted. + +*** 2025-11-01: Validation by execution works! +*Learning:* Immediately after creating the emacs-inbox-zero workflow, we validated it by actually running the workflow. This caught unclear areas and validated that the 10-minute target was realistic. + +*Key insight from validation:* When Craig provides useful context during workflows (impact estimates, theories, examples), that context should be captured in task descriptions. This wasn't obvious during workflow creation but became clear during execution. + +*Impact:* Validation catches what theory misses. Always use Phase 6 (validate by execution) soon after creating a workflow. + +* Example: Creating the "Create-Workflow" Workflow + +This very document was created using the process it describes (recursive!). + +** The Q&A +- *Problem:* Time waste, errors, missed learning from informal processes +- *Exit criteria:* Logical arrangement, mutual understanding, agreement on effectiveness, actionable tasks +- *Approach:* Four-question Q&A, assess completeness, name it, document it, update NOTES.org, validate by use +- *Principles:* Collaboration through discussion, review the whole, concrete over abstract, actionable tasks, validate early, decision frameworks, question assumptions + +** The Result +We identified what was needed, collaborated on answers, and captured it in this document. Then we immediately used it to create the next workflow (validation). + +* Conclusion + +Creating workflows is a meta-skill that improves all our collaboration. By formalizing how we work together, we: + +- Build shared vocabulary +- Eliminate repeated explanations +- Capture lessons learned +- Enable continuous improvement +- Make our partnership more efficient + +Each new workflow we create adds to our collaborative toolkit and deepens our ability to work together effectively. + +*Remember:* Workflows are frameworks, not rigid recipes. They provide structure while allowing flexibility for case-by-case decisions. The goal is effectiveness, not perfection. diff --git a/docs/workflows/journal-entry.org b/docs/workflows/journal-entry.org new file mode 100644 index 0000000..2a184af --- /dev/null +++ b/docs/workflows/journal-entry.org @@ -0,0 +1,209 @@ +#+TITLE: Journal Entry Workflow +#+AUTHOR: Craig Jennings & Claude +#+DATE: 2025-11-07 + +* Overview + +This workflow captures the day's work in Craig's personal journal. Journal entries serve as a searchable record for retrospectives, timelines, and trend analysis, while also providing context to Claude about relationships, priorities, mood, and goals that improve our collaboration. + +* Problem We're Solving + +Without regular journal entries, several problems emerge: + +** Limited Memory and Searchability +- Craig's memory is limited, but what's recorded is always available +- Finding when specific events occurred becomes difficult +- Creating project timelines and retrospectives requires manual reconstruction +- Identifying work patterns (weekday vs weekend, morning vs evening) is impossible + +** Missing Context for Collaboration +- Claude lacks understanding of relationships (Julie is Craig's aunt, Laura is his sister) +- Important contextual details that seem minor become critical unexpectedly +- Craig's mood, frustrations, and satisfaction levels remain hidden +- What Craig finds important vs unimportant isn't explicitly communicated +- Claude can't identify where to help Craig focus attention to avoid mistakes + +** Lost Insights +- Decisions made and reasoning behind them aren't captured +- Big picture goals and upcoming plans remain undocumented +- Patterns in what Craig is good at vs struggles with aren't tracked + +*Impact:* Without journal entries, Craig loses valuable personal records and Claude operates with incomplete context, reducing collaboration effectiveness. + +* Exit Criteria + +We know a journal entry is complete when: + +1. **Draft has been created** - Claude writes initial first-person draft based on NOTES.org session data +2. **Revisions are complete** - Craig provides corrections and context until satisfied +3. **Entry is added to journal file** - Text is added to the org-roam daily journal at ~/sync/org/roam/journal/YYYY-MM-DD.org +4. **Craig approves** - Craig explicitly approves or indicates no more revisions needed + +*Measurable validation:* +- Journal entry exists in the daily journal file +- Craig has approved the final text +- Entry captures big decisions, accomplishments, and unusual details +- Tone feels personal, vulnerable, and story-like + +* When to Use This Session + +Trigger this workflow when: + +- Craig says "let's do a journal entry" or "create a journal entry" +- At the end of a work session, particularly in the evening +- Craig asks to wrap up the day +- After completing significant work on a project + +This is typically done at the end of the day to capture that day's activities. + +* Approach: How We Work Together + +** Step 1: Review the Day's Work + +Check the project's NOTES.org file for today's session entries. This is your primary source for: +- Accomplishments achieved +- Decisions made +- Meetings or calls attended +- Files created or organized +- Actions planned for the future +- Outstanding items + +** Step 2: Draft the Journal Entry + +Write a first-person journal entry as Craig. The entry should: +- Be 2-3 paragraphs (unless it's an unusually eventful day) +- Focus on big ideas and decisions +- Include unusual or notable details +- Read like a personal journal - it's a little story about how things went +- Use a tone that's personal, genuine, and vulnerably open (never emotional) + +Structure suggestions: +- Start with the big event or decision of the day +- Explain what led to that decision or what work was accomplished +- Include any context about people, mood, or upcoming plans +- End with what's next or how you're feeling about progress + +** Step 3: Display and Request Revisions + +Display the draft to Craig and ask: "Does this capture the day? What would you like me to adjust?" + +This is where important context emerges: +- Corrections about relationships and people +- Clarification of goals and motivations +- Craig's mood and feelings about events +- Plans for the future +- What's important vs not important + +** Step 4: Incorporate Feedback and Iterate + +Make the requested changes and display the revised text. Ask again for revisions. Repeat this process until Craig approves or indicates no more changes are needed. + +During revisions: +- Ask questions if unsure about tone or word choice +- Ask about people mentioned for the first time +- If someone behaves strangely, ask Craig's thoughts to find the right tone +- Record any new context in your notes for future reference + +** Step 5: Add Entry to Journal File + +Once approved: + +1. Find the org-roam daily journal file at ~/sync/org/roam/journal/YYYY-MM-DD.org +2. If it doesn't exist, create it with this header: + ``` + :PROPERTIES: + :ID: [generate UUID using uuidgen] + :END: + #+FILETAGS: Journal + #+TITLE: YYYY-MM-DD + ``` +3. Create a top-level org header with timestamp: + ``` + * YYYY-MM-DD Day @ HH:MM:SS TZ ProjectName - What Kind of Day Has It Been? + ``` + (Get timezone with: date +%z) +4. Add the approved journal text below the header + +** Step 6: Wrap Up + +After adding the journal entry, ask Craig: "Are we done for the evening, or is there anything else that needs to be done?" + +Since journal entries typically happen at end of day, this provides a natural session close. + +* Principles to Follow + +** Personal and Vulnerable +- Write in a genuinely open, vulnerable tone +- Never emotional, but honest about challenges and feelings +- Make it feel like Craig's personal journal, not a work report + +** Brief but Complete +- Default to 2-3 paragraphs +- Capture big ideas and unusual details +- Don't document every minor task +- Longer entries are fine for unusually eventful days + +** Story-Like Quality +- Read like someone telling a story about their day +- Have a narrative flow, not just a bullet list +- Connect events and decisions with context + +** Clarifying Questions Welcome +- Ask about tone, word choice, or what to include when unsure +- Ask about people mentioned for the first time +- Probe for Craig's thoughts when events seem unusual +- Use questions to gather context that improves collaboration + +** Context Capture +- Record new information about relationships, goals, and preferences +- Note what Craig finds important vs unimportant +- Track mood indicators and patterns +- Save insights for future reference + +** Use Session Data +- Start from NOTES.org session entries for the day +- Don't rely on memory - check the documented record +- Include key decisions, accomplishments, and next steps + +* Living Document + +This is a living document. As we create journal entries and learn what works well, we update this file with: + +- Improvements to the drafting approach +- Better examples of tone and style +- Additional principles discovered +- Refinements based on Craig's feedback + +Every journal entry is an opportunity to improve this workflow. + +* Example Journal Entry + +Here's an example from 2025-11-07 (JR-Estate project): + +#+begin_quote +Big day. We sold Gogo's condo. + +This morning I woke up to two counter offers - one from Cortney Arambula at $1,377,000 and another from Rolando Tong Jr. at $1,405,000. Deadline was 3 PM today. + +I had two phone calls with Craig Ratowsky. The first at 11:59 AM, we talked through both offers. Rolando's was clearly better - $28,000 more, already pre-approved, and the buyer is his sister. Craig walked me through the numbers and timeline. + +On the second call at 12:25 PM, I made the decision: accept Rolando's offer at $1,405,000. After all these months of work - dealing with mold, replacing the kitchen, new flooring, staging - we have a buyer. + +Escrow opens Monday (11/10/2025), 30-day close from there. By mid-December, this will be done. + +Net proceeds to the trust will be around $1,099,385 after the mortgage payoff, closing costs, and agent commissions. + +I spent the early evening getting all the files organized so I can figure out exactly how much Christine and I put in for the renovation and get reimbursed. This will also help when I report expenses to Mom and Laura about the estate. + +Now I need to plan the trip to Huntington Beach to handle Gogo's financial affairs - consolidate her accounts into the estate account, pay her bills, distribute her funds, and mail some items from the garage back home. Plus empty the garage for the seller before closing. + +Escrow Monday. Still need to: +- Decide on compensating Craig and Justin for their extra work +- Get the Tax ID number for the estate +- Work on Gogo's final taxes with a CPA +- File the Inventory & Appraisal with probate court + +It's been almost nine months since Gogo passed. Getting this condo sold feels like a huge milestone. +#+end_quote + +Note the personal tone, narrative flow, big decision (accepting the offer), context about people (Gogo, Craig Ratowsky, Christine), mood (milestone feeling), and what's next. diff --git a/docs/workflows/refactor.org b/docs/workflows/refactor.org new file mode 100644 index 0000000..0adb337 --- /dev/null +++ b/docs/workflows/refactor.org @@ -0,0 +1,617 @@ +#+TITLE: Test-Driven Quality Engineering Workflow +#+AUTHOR: Craig Jennings & Claude +#+DATE: 2025-11-01 + +* Overview + +This document describes a comprehensive test-driven quality engineering workflow applicable to any source code module. The workflow demonstrates systematic testing practices, refactoring for testability, bug discovery through tests, and decision-making processes when tests fail. + +* Workflow Goals + +1. Add comprehensive unit test coverage for testable functions in your module +2. Discover and fix bugs through systematic testing +3. Follow quality engineering principles from =ai-prompts/quality-engineer.org= (analyze this now) +4. Demonstrate refactoring patterns for testability +5. Document the decision-making process for test vs production code issues + +* Phase 1: Feature Addition with Testability in Mind + +** The Feature Request + +Add new functionality that requires user interaction combined with business logic. + +Example requirements: +- Present user with options (e.g., interactive selection) +- Allow cancellation +- Perform an operation with the selected input +- Provide clear success/failure feedback + +** Refactoring for Testability + +Following the "Interactive vs Non-Interactive Function Pattern" from =quality-engineer.org=: + +*Problem:* Directly implementing as an interactive function would require: +- Mocking user interface components +- Mocking framework-specific APIs +- Testing UI functionality, not core business logic + +*Solution:* Split into two functions: + +1. *Helper Function* (internal implementation): + - Pure, deterministic + - Takes explicit parameters + - No user interaction + - Returns values or signals errors naturally + - 100% testable, no mocking needed + +2. *Interactive Wrapper* (public interface): + - Thin layer handling only user interaction + - Gets input from user/context + - Presents UI (prompts, selections, etc.) + - Catches errors and displays messages + - Delegates all business logic to helper + - No tests needed (just testing framework UI) + +** Benefits of This Pattern + +From =quality-engineer.org=: +#+begin_quote +When writing functions that combine business logic with user interaction: +- Split into internal implementation and interactive wrapper +- Internal function: Pure logic, takes all parameters explicitly +- Dramatically simpler testing (no interactive mocking) +- Code reusable programmatically without prompts +- Clear separation of concerns (logic vs UI) +#+end_quote + +This pattern enables: +- Zero mocking in tests +- Fast, deterministic tests +- Easy reasoning about correctness +- Reusable helper function + +* Phase 2: Writing the First Test + +** Test File Naming + +Following the naming convention from =quality-engineer.org=: +- Pattern: =test-<module>-<function>.<ext>= +- One test file per function for easy discovery when tests fail +- Developer sees failure → immediately knows which file to open + +** Test Organization + +Following the three-category structure: + +*** Normal Cases +- Standard expected inputs +- Common use case scenarios +- Happy path operations +- Multiple operations in sequence + +*** Boundary Cases +- Very long inputs +- Unicode characters (中文, emoji) +- Special characters and edge cases +- Empty or minimal data +- Maximum values + +*** Error Cases +- Invalid inputs +- Nonexistent resources +- Permission denied scenarios +- Wrong type of input + +** Writing Tests with Zero Mocking + +Key principle: "Don't mock what you're testing" (from =quality-engineer.org=) + +Example test structure: +#+begin_src +test_function_normal_case_expected_result() + setup() + try: + # Arrange + input_data = create_test_data() + expected_output = define_expected_result() + + # Act + actual_output = function_under_test(input_data) + + # Assert + assert actual_output == expected_output + finally: + teardown() +#+end_src + +Key characteristics: +- No mocks for the function being tested +- Real resources (files, data structures) using test utilities +- Tests actual function behavior +- Clean setup/teardown +- Clear arrange-act-assert structure + +** Result + +When helper functions are well-factored and deterministic, tests often pass on first run. + +* Phase 3: Systematic Test Coverage Analysis + +** Identifying Testable Functions + +Review all functions in your module and categorize by testability: + +*** Easy to Test (Pure/Deterministic) +- Input validation functions +- String manipulation/formatting +- Data structure transformations +- File parsing (read-only operations) +- Configuration/option processing + +*** Medium Complexity (Need External Resources) +- File I/O operations +- Recursive algorithms +- Data structure generation +- Cache or state management + +*** Hard to Test (Framework/Context Dependencies) +- Functions requiring specific runtime environment +- UI/buffer/window management +- Functions tightly coupled to framework internals +- Functions requiring complex mocking setup + +*Decision:* Test easy and medium complexity functions. Skip framework-dependent functions that would require extensive mocking/setup (diminishing returns). + +** File Organization Principle + +From =quality-engineer.org=: +#+begin_quote +*Unit Tests*: One file per method +- Naming: =test-<filename>-<methodname>.<ext>= +- Example: =test-module--function.ext= +#+end_quote + +*Rationale:* When a test fails in CI: +1. Developer sees: =test-module--function-normal-case-returns-result FAILED= +2. Immediately knows: Look for =test-module--function.<ext>= +3. Opens file and fixes issue - *fast cognitive path* + +If combined files: +1. Test fails: =test-module--function-normal-case-returns-result FAILED= +2. Which file? =test-module--helpers.<ext>=? =test-module--combined.<ext>=? +3. Developer wastes time searching - *slower, frustrating* + +*The 1:1 mapping is a usability feature for developers under pressure.* + +* Phase 4: Testing Function by Function + +** Example 1: Input Validation Function + +*** Test Categories + +*Normal Cases:* +- Valid inputs +- Case variations +- Common use cases + +*Boundary Cases:* +- Edge cases in input format +- Multiple delimiters or separators +- Empty or minimal input +- Very long input + +*Error Cases:* +- Nil/null input +- Wrong type +- Malformed input + +*** First Run: Most Passed, Some FAILED + +*Example Failure:* +#+begin_src +test-module--validate-input-error-nil-input-returns-nil +Expected: Returns nil gracefully +Actual: (TypeError/NullPointerException) - CRASHED +#+end_src + +*** Bug Analysis: Test or Production Code? + +*Process:* +1. Read the test expectation: "nil input returns nil/false gracefully" +2. Read the production code: + #+begin_src + function validate_input(input): + extension = get_extension(input) # ← Crashes here on nil/null + return extension in valid_extensions + #+end_src +3. Identify issue: Function expects string, crashes on nil/null +4. Consider context: This is defensive validation code, called in various contexts + +*Decision: Fix production code* + +*Rationale:* +- Function should be defensive (validation code) +- Returning false/nil for invalid input is more robust than crashing +- Common pattern in validation functions +- Better user experience + +*Fix:* +#+begin_src +function validate_input(input): + if input is None or not isinstance(input, str): # ← Guard added + return False + extension = get_extension(input) + return extension in valid_extensions +#+end_src + +Result: All tests pass after adding defensive checks. + +** Example 2: Another Validation Function + +*** First Run: Most Passed, Multiple FAILED + +*Failures:* +1. Nil input crashed (same pattern as previous function) +2. Empty string returned unexpected value (edge case not handled) + +*Fix:* +#+begin_src +function validate_resource(resource): + # Guards added for nil/null and empty string + if not resource or not isinstance(resource, str) or resource.strip() == "": + return False + + # Original validation logic + return is_valid_resource(resource) and meets_criteria(resource) +#+end_src + +Result: All tests pass after adding comprehensive guards. + +** Example 3: String Sanitization Function + +*** First Run: Most Passed, 1 FAILED + +*Failure:* +#+begin_src +test-module--sanitize-boundary-special-chars-replaced +Expected: "output__________" (10 underscores) +Actual: "output_________" (9 underscores) +#+end_src + +*** Bug Analysis: Test or Production Code? + +*Process:* +1. Count special chars in test input: 9 characters +2. Test expected 10 replacements, but input only has 9 +3. Production code is working correctly + +*Decision: Fix test code* + +*The bug was in the test expectation, not the implementation.* + +Result: All tests pass after correcting test expectations. + +** Example 4: File/Data Parser Function + +This is where a **significant bug** was discovered through testing! + +*** Test Categories + +*Normal Cases:* +- Absolute paths/references +- Relative paths (expanded to base directory) +- URLs/URIs preserved as-is +- Mixed types of references + +*Boundary Cases:* +- Empty lines ignored +- Whitespace-only lines ignored +- Comments ignored (format-specific) +- Leading/trailing whitespace trimmed +- Order preserved + +*Error Cases:* +- Nonexistent file +- Nil/null input + +*** First Run: Majority Passed, Multiple FAILED + +All failures related to URL/URI handling: + +*Failure Pattern:* +#+begin_src +Expected: "http://example.com/resource" +Actual: "/base/path/http:/example.com/resource" +#+end_src + +URLs were being treated as relative paths and corrupted! + +*** Root Cause Analysis + +*Production code:* +#+begin_src +if line.matches("^\(https?|mms\)://"): # Pattern detection + # Handle as URL +#+end_src + +*Problem:* Pattern matching is incorrect! + +The pattern/regex has an error: +- Incorrect escaping or syntax +- Pattern fails to match valid URLs +- All URLs fall through to the "relative path" handler + +The pattern never matched, so URLs were incorrectly processed as relative paths. + +*Correct version:* +#+begin_src +if line.matches("^(https?|mms)://"): # Fixed pattern + # Handle as URL +#+end_src + +Common causes of this type of bug: +- String escaping issues in the language +- Incorrect regex syntax +- Copy-paste errors in patterns + +*** Impact Assessment + +*This is a significant bug:* +- Remote resources (URLs) would be broken +- Data corruption: URLs transformed into invalid paths +- Function worked for local/simple cases, so bug went unnoticed +- Users would see mysterious errors when using remote resources +- Potential data loss or corruption in production + +*Tests caught a real production bug that could have caused user data corruption!* + +Result: All tests pass after fixing the pattern matching logic. + +* Phase 5: Continuing Through the Test Suite + +** Additional Functions Tested Successfully + +As testing continues through the module, patterns emerge: + +*Function: Directory/File Listing* + - Learning: Directory listing order may be filesystem-dependent + - Solution: Sort results before comparing in tests + +*Function: Data Extraction* + - Keep as separate test file (don't combine with related functions) + - Reason: Usability when tests fail + +*Function: Recursive Operations* + - Medium complexity: Required creating test data structures/trees + - Use test utilities for setup/teardown + - Well-factored functions often pass all tests initially + +*Function: Higher-Order Functions* + - Test functions that return functions/callbacks + - Initially may misunderstand framework/protocol behavior + - Fix test expectations to match actual framework behavior + +* Key Principles Applied + +** 1. Refactor for Testability BEFORE Writing Tests + +The Interactive vs Non-Interactive pattern from =quality-engineer.org= made testing trivial: +- No mocking required +- Fast, deterministic tests +- Clear separation of concerns + +** 2. Systematic Test Organization + +Every test file followed the same structure: +- Normal Cases +- Boundary Cases +- Error Cases + +This makes it easy to: +- Identify coverage gaps +- Add new tests +- Understand what's being tested + +** 3. Test Naming Convention + +Pattern: =test-<module>-<function>-<category>-<scenario>-<expected-result>= + +Examples: +- =test-module--validate-input-normal-valid-extension-returns-true= +- =test-module--parse-data-boundary-empty-lines-ignored= +- =test-module--sanitize-error-nil-input-signals-error= + +Benefits: +- Self-documenting +- Easy to understand what failed +- Searchable/grepable +- Clear category organization + +** 4. Zero Mocking for Pure Functions + +From =quality-engineer.org=: +#+begin_quote +DON'T MOCK WHAT YOU'RE TESTING +- Only mock external side-effects and dependencies, not the domain logic itself +- If mocking removes the actual work the function performs, you're testing the mock +- Use real data structures that the function is designed to operate on +- Rule of thumb: If the function body could be =(error "not implemented")= and tests still pass, you've over-mocked +#+end_quote + +Our tests used: +- Real file I/O +- Real strings +- Real data structures +- Actual function behavior + +Result: Tests caught real bugs, not mock configuration issues. + +** 5. Test vs Production Code Bug Decision Framework + +When a test fails, ask: + +1. *What is the test expecting?* + - Read the test name and assertions + - Understand the intended behavior + +2. *What is the production code doing?* + - Read the implementation + - Trace through the logic + +3. *Which is correct?* + - Is the test expectation reasonable? + - Is the production behavior defensive/robust? + - What is the usage context? + +4. *Consider the impact:* + - Defensive code: Fix production to handle edge cases + - Wrong expectation: Fix test + - Unclear spec: Ask user for clarification + +Examples from our session: +- *Nil input crashes* → Fix production (defensive coding) +- *Empty string treated as valid* → Fix production (defensive coding) +- *Wrong count in test* → Fix test (test bug) +- *Regex escaping wrong* → Fix production (real bug!) + +** 6. Fast Feedback Loop + +Pattern: "Write tests, run them all, report errors, and see where we are!" + +This became a mantra during the session: +1. Write comprehensive tests for one function +2. Run immediately +3. Analyze failures +4. Fix bugs (test or production) +5. Verify all tests pass +6. Move to next function + +Benefits: +- Caught bugs immediately +- Small iteration cycles +- Clear progress +- High confidence in changes + +* Final Results + +** Test Coverage Example + +*Multiple functions tested with comprehensive coverage:* +1. File operation helper - ~10-15 tests +2. Input validation function - ~15 tests +3. Resource validation function - ~13 tests +4. String sanitization function - ~13 tests +5. File/data parser function - ~15 tests +6. Directory listing function - ~7 tests +7. Data extraction function - ~6 tests +8. Recursive operation function - ~12 tests +9. Higher-order function - ~12 tests + +Total: Comprehensive test suite covering all testable functions + +** Bugs Discovered and Fixed + +1. *Input Validation Function* + - Issue: Crashed on nil/null input + - Fix: Added nil/type guards + - Impact: Prevents crashes in validation code + +2. *Resource Validation Function* + - Issue: Crashed on nil, treated empty string as valid + - Fix: Added guards for nil and empty string + - Impact: More robust validation + +3. *File/Data Parser Function* ⚠️ *SIGNIFICANT BUG* + - Issue: Pattern matching wrong - URLs/URIs corrupted as relative paths + - Fix: Corrected pattern matching logic + - Impact: Remote resources now work correctly + - *This bug would have corrupted user data in production* + +** Code Quality Improvements + +- All testable helper functions now have comprehensive test coverage +- More defensive error handling (nil guards) +- Clear separation of concerns (pure helpers vs interactive wrappers) +- Systematic boundary condition testing +- Unicode and special character handling verified + +* Lessons Learned + +** 1. Tests as Bug Discovery Tools + +Tests aren't just for preventing regressions - they actively *discover existing bugs*: +- Pattern matching bugs may exist in production +- Nil/null handling bugs manifest in edge cases +- Tests make these issues visible immediately +- Bugs caught before users encounter them + +** 2. Refactoring Enables Testing + +The decision to split functions into pure helpers + interactive wrappers: +- Made testing dramatically simpler +- Enabled 100+ tests with zero mocking +- Improved code reusability +- Clarified function responsibilities + +** 3. Systematic Process Matters + +Following the same pattern for each function: +- Reduced cognitive load +- Made it easy to maintain consistency +- Enabled quick iteration +- Built confidence in coverage + +** 4. File Organization Aids Debugging + +One test file per function: +- Fast discovery when tests fail +- Clear ownership +- Easy to maintain +- Follows user's mental model + +** 5. Test Quality Equals Production Quality + +Quality tests: +- Use real resources (not mocks) +- Test actual behavior +- Cover edge cases systematically +- Find real bugs + +This is only possible with well-factored, testable code. + +* Applying These Principles + +When adding tests to other modules: + +1. *Identify testable functions* - Look for pure helpers, file I/O, string manipulation +2. *Refactor if needed* - Split interactive functions into pure helpers +3. *Write systematically* - Normal, Boundary, Error categories +4. *Run frequently* - Fast feedback loop +5. *Analyze failures carefully* - Test bug vs production bug +6. *Fix immediately* - Don't accumulate technical debt +7. *Maintain organization* - One file per function, clear naming + +* Reference + +See =ai-prompts/quality-engineer.org= for comprehensive quality engineering guidelines, including: +- Test organization and structure +- Test naming conventions +- Mocking and stubbing best practices +- Interactive vs non-interactive function patterns +- Integration testing guidelines +- Test maintenance strategies + +Note: =quality-engineer.org= evolves as we learn more quality best practices. This document captures principles applied during this specific session. + +* Conclusion + +This workflow process demonstrates how systematic testing combined with refactoring for testability can: +- Discover real bugs before they reach users +- Improve code quality and robustness +- Build confidence in changes +- Create maintainable test suites +- Follow industry best practices + +A comprehensive test suite with multiple bug fixes represents significant quality improvement to any module. Critical bugs (like the pattern matching issue in the example) alone can justify the entire testing effort - such bugs can cause data corruption and break major features. + +*Testing is not just about preventing future bugs - it's about finding bugs that already exist.* diff --git a/docs/workflows/session-start.org b/docs/workflows/session-start.org new file mode 100644 index 0000000..66973ab --- /dev/null +++ b/docs/workflows/session-start.org @@ -0,0 +1,540 @@ +#+TITLE: Session Start Workflow +#+AUTHOR: Craig Jennings & Claude +#+DATE: 2025-11-14 + +* Overview + +This workflow defines the process for beginning a Claude Code session. It ensures Claude has the necessary context, is aware of current priorities, and can work effectively with Craig from the start. + +This workflow runs **automatically at the beginning of EVERY session** without needing to be triggered by Craig. + +* Problem We're Solving + +Without a structured session start process, sessions can begin poorly: + +** Missing Context +- Claude doesn't know what happened in previous sessions +- Important reminders or decisions are overlooked +- No awareness of project-specific conventions or preferences +- Time wasted re-explaining project context + +** Outdated Information +- Missing protocol updates from template improvements +- Unaware of new workflows available in the project +- Using old conventions that have been superseded +- Templates and project drift out of sync + +** Missed Priorities +- New documents in inbox go unnoticed +- Critical reminders aren't surfaced +- Pending decisions remain unaddressed +- User has urgent work but Claude suggests non-urgent tasks + +** Inefficient Start +- Reading entire NOTES.org file (wasting tokens on static content) +- No clear next steps or priorities +- User must orient Claude manually +- Lack of structure for beginning work + +*Impact:* Slow session starts, missed context, wasted time, and frustration from having to repeat information. + +* Exit Criteria + +The session start is complete when: + +1. **Claude has current context:** + - Knows project-specific information and goals + - Aware of how user prefers to work + - Understanding of recent session history (last 2-3 sessions) + - Current reminders and pending decisions surfaced + +2. **Templates are synced:** + - Checked for updates from claude-templates + - Any new workflows or improvements identified + - Project templates directory is current + +3. **Inbox is processed:** + - New documents identified and reviewed + - Recommendations provided for each + - Documents filed appropriately + +4. **Next steps are clear:** + - User has stated urgent work, OR + - Claude has suggested following what's-next workflow + - Session has clear direction + +*Measurable validation:* +- Active Reminders have been surfaced to user +- Pending Decisions have been mentioned +- Inbox is empty or user has deferred processing +- User has confirmed what to work on OR agreed to what's-next workflow + +* When to Use This Workflow + +**IMPORTANT: This workflow runs AUTOMATICALLY at the start of EVERY session.** + +Do NOT ask the user if they want to run it - just execute it immediately when a new session begins. + +The only exception is if the user immediately provides urgent instructions that require immediate action (e.g., "the server is down, help me debug it right now"). + +* First Time Setup + +If this is the first time using this workflow in a project, perform this one-time cleanup: + +** Clean Up Old "Session Start" Documentation + +Before using this workflow, check if NOTES.org contains old/redundant session start instructions: + +1. **Search NOTES.org for duplicate content:** + #+begin_src bash + grep -n "Session Start\|session start" docs/NOTES.org + #+end_src + +2. **Look for sections that duplicate this workflow:** + - Detailed "Session Start Routine" instructions + - Step-by-step template sync instructions + - Inline instructions for reading NOTES.org sections + - Inbox processing instructions + +3. **Replace with link to this workflow:** + - Remove the detailed inline instructions + - Replace with: "See [[file:docs/workflows/session-start.org][Session Start Workflow]]" + - Keep brief summary if helpful for quick reference + +4. **Why this matters:** + - Prevents conflicting instructions (e.g., different diff commands) + - Single source of truth for session start process + - Easier to maintain and update in one place + - Reduces NOTES.org file size + +**Example cleanup:** + +Before: +#+begin_example +* Session Start Routine + +When starting a new session with Craig, follow these steps: + +1. Add Timestamp for Session History + [detailed instructions...] +2. Sync with Templates + [detailed instructions...] +3. Scan workflows directory + [detailed instructions...] +[30+ lines of detailed instructions] +#+end_example + +After: +#+begin_example +* Session Start Routine + +**IMPORTANT: ALWAYS run this routine automatically at the start of EVERY session.** + +Execute the session start workflow defined in [[file:docs/workflows/session-start.org][session-start.org]]. + +Brief summary: Add timestamp, sync templates, scan workflows, read key NOTES.org sections, process inbox, ask about priorities. +#+end_example + +This cleanup should only be done ONCE when first adopting this workflow. + +* The Workflow + +** Step 1: Add Session Start Timestamp + +Record when the session begins for tracking purposes. + +*** Why This Matters + +- Helps identify if previous session was interrupted (no end timestamp) +- Provides session duration tracking +- Creates clear session boundaries in history + +*** How to Add Timestamp + +1. **Navigate to Session History section** in =docs/NOTES.org= + +2. **Check the last session entry:** + - If it has a start timestamp but NO end timestamp → previous session was interrupted + - If it has both start and end timestamps → previous session completed normally + +3. **Prepare for new session entry** (will be written during wrap-up): + - Note the current time for internal reference + - Session entry will be created at wrap-up, not now + - This step is just to CHECK for interrupted sessions + +4. **If previous session was interrupted:** + - Mention to user: "I notice the last session (DATE) didn't complete normally. Should I review what was being worked on?" + - This helps recover context if something went wrong + +*** Format + +Session timestamps follow this format (added during wrap-up, not session start): +- Start: Recorded at beginning of session +- End: Recorded during wrap-up workflow + +Example: +#+begin_example +** Session: November 14, 2025 (Morning) +Started: 09:30 AM +Ended: 11:45 AM +#+end_example + +** Step 2: Sync with Templates + +Keep the project aligned with latest best practices from claude-templates. + +*** CRITICAL: Template is Authoritative + +**The template is the single source of truth.** Do not review diffs or decide whether to apply changes - just copy from template to project. There should NEVER be differences between template files and project files, not even cosmetic differences like trailing whitespace. + +If a project needs project-specific protocol additions, put them in NOTES.org under a "Project-Specific Protocols" section - NEVER modify protocols.org in the project. + +*** Why This Matters + +- Ensures consistent behavior across all projects +- Eliminates drift between template and projects +- Protocol improvements automatically propagate to all projects +- Single source of truth prevents confusion + +*** How to Copy + +Copy template files directly to the project's docs/ directory: + +#+begin_src bash +cp ~/projects/claude-templates/docs/protocols.org docs/protocols.org +cp -r ~/projects/claude-templates/docs/workflows docs/ +cp -r ~/projects/claude-templates/docs/scripts docs/ +#+end_src + +**Mention any significant updates** if you notice them: +- If protocols.org has new sections, mention briefly +- If new workflows were added, mention them +- Example: "protocols.org now includes alarm instructions" + +That's it. No diff review, no decisions - template always wins. + +*** Workflow Directory Structure + +There are TWO workflow directories: + +**=docs/workflows/=** - Template workflows (standard across all projects) +- Copied from template on every session start +- NEVER edit these in a project - edit in template instead +- Safe to overwrite completely during copy +- Examples: session-start.org, session-wrap-up.org, create-workflow.org + +**=docs/project-workflows/=** - Project-specific workflows (unique to this project) +- NEVER copied or touched by template sync +- Created and maintained within the project only +- Examples: morning-checkin.org (health), danneel-inbox-zero.org (danneel) + +*** What Gets Copied (Template → Project) + +- **protocols.org** - Always overwrite from template +- **workflows/** - Template workflows (overwritten completely) +- **scripts/** - Template scripts (overwritten completely) + +*** What Is NEVER Copied (Project-Specific) + +- **NOTES.org** - Project-specific content (context, history, reminders) +- **previous-session-history.org** - Project-specific history +- **session-context.org** - Project-specific live session data +- **someday-maybe.org** - Project-specific ideas +- **project-workflows/** - Project-specific workflows (separate directory, never touched) + +** Step 3: Scan Workflows Directory + +Understand what workflows are available in this project. + +*** Why This Matters + +- Enables Claude to suggest appropriate workflows +- Builds vocabulary for understanding user requests +- Shows what standardized processes exist +- Helps answer "how do we do X?" questions + +*** How to Scan + +1. **List workflow files:** + #+begin_src bash + ls -1 docs/workflows/ + #+end_src + +2. **Note the workflow names** (just filenames, don't read contents): + - create-workflow.org + - create-v2mom.org + - session-start.org + - session-wrap-up.org + - [project-specific workflows] + +3. **Remember these exist** for suggesting to user later + +4. **Do NOT read full workflow contents** - they're long and will be read when actually executing a workflow + +*** When User Says "Let's Run the X Workflow" + +1. Check if workflow exists in docs/workflows/ +2. If yes: Read that specific workflow file and execute it +3. If no: Offer to create it using create-workflow process + +** Step 4: Read protocols.org and NOTES.org + +Get behavioral instructions and project context. + +*** Why Two Files? + +Documentation is now split into two files: +- **protocols.org** - How Claude should behave (consistent across all projects) +- **NOTES.org** - Project-specific content (unique to each project) + +This separation allows protocol updates to sync automatically without affecting project data. + +*** Read protocols.org First + +Read the entire =docs/protocols.org= file. It contains: +- Session management protocols (context files, compacting) +- Important terminology and trigger phrases +- User information and preferences +- Git commit requirements +- File format and naming conventions +- Session start instructions + +This file is relatively short and should be read in full. + +*** Then Read NOTES.org + +NOTES.org now contains only project-specific content: + +1. **Project-Specific Context** section + - **THIS IS THE KEY SECTION** - contains what the project is about + - People involved and their roles + - Current state of the project + - Goals and objectives + - Important background information + - Technical architecture or key decisions + +2. **Active Reminders** section + - Critical items to surface to user + - Time-sensitive follow-ups + - Important tasks user asked to be reminded about + +3. **Pending Decisions** section + - Decisions awaiting user input + - Blockers that need resolution + - Questions that need answering + +4. **Session History - Last 2-3 entries only** + - Recent work completed + - Recent decisions made + - Context from previous sessions + - What was being worked on + - **Do NOT read entire session history** - older entries are archived + +*** What to SKIP in NOTES.org + +- About This File (brief, just links to protocols.org) +- Available Workflows catalog (just scanned in Step 3) +- Session History format instructions (reference material) +- Full Session History (only read last 2-3 entries) +- Archived sessions in previous-session-history.org (unless specifically needed) + +*** How to Read Efficiently + +#+begin_example +1. Read docs/protocols.org (entire file - it's the behavioral guide) +2. Read docs/NOTES.org Project-Specific Context section +3. Read docs/NOTES.org Active Reminders section +4. Read docs/NOTES.org Pending Decisions section +5. Read last 2-3 Session History entries (count backwards from end) +#+end_example + +** Step 5: Process Inbox + +Check for new documents and help user file them appropriately. + +*** Why This Matters + +- New documents need to be reviewed and filed +- Unprocessed inbox items can contain important information +- Helps maintain organized project structure +- Ensures nothing gets missed + +*** Inbox Location + +Default inbox location: =./inbox/= (at project root) + +Some projects may have different locations - check NOTES.org or ask user on first session. + +*** How to Process + +1. **Check inbox directory:** + #+begin_src bash + ls -lh inbox/ + #+end_src + +2. **If inbox is empty:** + - No action needed + - Continue to Step 6 + +3. **If inbox contains files:** + - **Do NOT ask if user wants to process** - process is MANDATORY + - Say: "I see X items in your inbox. Let me review them." + +4. **For each file in inbox:** + - Read the file to understand content + - Determine: + - Who it's from (if applicable) + - What it's about + - What action should be taken + - Consider project history and context + - Recommend appropriate action: + - File to =assets/emails/= if it's an email + - File to =assets/= if it's a document/attachment + - File to =docs/= if it's project documentation + - Add TODO items if action is needed + - Recommend appropriate filename: + - Format: =YYYY-MM-DD-Source-Description.ext= + - Example: =2025-11-14-Mark-Response-To-Settlement.txt= + - Get user approval before filing + +5. **File the document:** + - Move (not copy) from inbox to destination + - Use approved filename + - Update any relevant TODO items or event logs + +6. **Repeat for all inbox items** until inbox is empty + +*** Inbox Processing Workflow + +Some projects may have a specific inbox-zero workflow (e.g., =docs/workflows/danneel-inbox-zero.org=). + +If it exists: +- Use that workflow instead of the generic process above +- It may have project-specific filing conventions + +** Step 6: Ask About Priorities + +Determine what to work on this session. + +*** Why This Matters + +- User may have urgent work that takes priority +- Prevents suggesting V2MOM tasks when there's a crisis +- Gives user control over session direction +- Enables following structured workflow if no urgent work + +*** How to Ask + +**Say to user:** + +"Is there something urgent you'd like to work on, or should we follow the what's-next workflow to identify priorities?" + +Wait for user response. + +*** If User Has Urgent Work + +- Proceed with the urgent work immediately +- Skip what's-next workflow +- Focus session on user's stated priority + +*** If User Says Follow What's-Next + +- Check if =docs/workflows/whats-next.org= exists +- If yes: Execute that workflow +- If no: Check if V2MOM exists and suggest working on top priority method +- If no V2MOM: Offer to create one using create-v2mom workflow + +*** If User is Unsure + +Provide helpful context: +- Remind them of Active Reminders (from Step 4) +- Mention any Pending Decisions (from Step 4) +- Reference recent session history (what was being worked on) +- Suggest continuing previous work if it's unfinished + +** Session Start Complete + +Once all steps are done: +- Claude has full context +- User knows what's being worked on +- Session can proceed productively + +Don't announce "session start complete" - just begin working on the chosen task. + +* Tips for Effective Session Starts + +** Template Sync + +1. **Don't panic about changes** - Most are improvements +2. **Review carefully** - Understand what changed before applying +3. **Project-specific workflows** - Don't overwrite if customized +4. **Mention significant updates** - User should know about workflow improvements +5. **First sync is clean** - No diff needed, just copy + +** Reading NOTES.org + +1. **Use line numbers** - More efficient than searching +2. **Read in order** - Builds context progressively +3. **Focus on Project-Specific Context** - This is the most important section +4. **Surface reminders immediately** - Don't wait until later +5. **Note interrupted sessions** - Helps recover from crashes + +** Inbox Processing + +1. **Be thorough** - Read files completely to understand context +2. **Consider history** - Recommendations should fit project patterns +3. **Suggest good filenames** - Use established conventions +4. **Don't delete without asking** - User may want to review first +5. **Update related systems** - Add TODOs, update event logs as needed + +** Priorities Discussion + +1. **Ask clearly** - Don't be vague about what's being offered +2. **Respect urgency** - If user has crisis, drop everything else +3. **Provide context** - Remind user of reminders and decisions +4. **Don't assume** - Even if previous session had direction, ask +5. **Be helpful** - If user is unsure, provide gentle guidance + +* Common Mistakes to Avoid + +1. **Reading entire NOTES.org file** - Wastes tokens on static content +2. **Skipping template sync** - Miss important updates +3. **Not checking for interrupted sessions** - Lose context from crashes +4. **Forgetting to surface Active Reminders** - User misses critical items +5. **Asking if user wants inbox processed** - It's mandatory, not optional +6. **Processing inbox after asking about priorities** - Should be before +7. **Not excluding NOTES.org from template diff** - Creates noise +8. **Not excluding previous-session-history.org from diff** - Project-specific content +9. **Announcing "session start complete"** - Just begin working +10. **Reading full workflow files during scan** - Just note filenames + +* Validation Checklist + +Before considering session start complete, verify: + +- [ ] Checked for interrupted previous session (missing end timestamp) +- [ ] Template sync executed (diff or first-time copy) +- [ ] Template changes reviewed and applied if needed +- [ ] Workflows directory scanned (filenames noted) +- [ ] IMPORTANT TERMINOLOGY section read +- [ ] User Information section read +- [ ] Project-Specific Context section read (CRITICAL) +- [ ] Active Reminders section read and surfaced to user +- [ ] Pending Decisions section read and mentioned to user +- [ ] Last 2-3 Session History entries read +- [ ] Inbox checked for new files +- [ ] Inbox processed (if contained files) or confirmed empty +- [ ] Asked user about urgent work vs what's-next workflow +- [ ] User has confirmed what to work on OR agreed to follow workflow +- [ ] Ready to begin productive work + +* Meta Notes + +This workflow should evolve based on experience: + +- If session starts consistently miss something important, update the checklist +- If reading NOTES.org sections takes too long, further optimize what's read +- If template sync creates too much noise, refine what's excluded +- Craig can modify this workflow at any time to better fit needs + +The goal is efficient session starts with full context, not rigid adherence to format. diff --git a/docs/workflows/session-wrap-up.org b/docs/workflows/session-wrap-up.org new file mode 100644 index 0000000..ff1d703 --- /dev/null +++ b/docs/workflows/session-wrap-up.org @@ -0,0 +1,484 @@ +#+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/session-wrap-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/session-wrap-up.org][session-wrap-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: 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 + +* 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 "working tree clean" +- [ ] Push confirmed successful to all remotes +- [ ] 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. diff --git a/docs/workflows/v2mom.org b/docs/workflows/v2mom.org new file mode 100644 index 0000000..d39e932 --- /dev/null +++ b/docs/workflows/v2mom.org @@ -0,0 +1 @@ +this is placeholder text. when the v2mom is created, this should be removed. diff --git a/docs/workflows/whats-next.org b/docs/workflows/whats-next.org new file mode 100644 index 0000000..f1870bf --- /dev/null +++ b/docs/workflows/whats-next.org @@ -0,0 +1,146 @@ +#+TITLE: What's Next Workflow +#+AUTHOR: Craig Jennings & Claude +#+DATE: 2025-11-10 + +* Overview + +The "what's next" workflow helps identify the most urgent and important task to work on next. It reduces decision fatigue by having Claude apply objective prioritization criteria (deadlines, priorities, method order) instead of relying on subjective feelings (what's fun, what's quick). + +* Problem We're Solving + +Without a "what's next" workflow, choosing the next task creates friction: + +** Decision Fatigue +- Scanning through todo.org to find high-priority items +- Remembering context from previous sessions (what's blocked, what's ready) +- Mentally prioritizing competing tasks + +** Distraction by Easy Wins +- Natural tendency to pick fun/quick tasks for dopamine hits +- Important work gets postponed in favor of satisfying but less critical tasks +- Momentum is broken by choosing easier tasks + +** Missing Time-Sensitive Work +- Deadlines can be overlooked when scanning manually +- Follow-up tasks from reminders get forgotten +- In-progress tasks may not get finished before starting new work + +*Impact:* Less gets done per session, important work is delayed, and flow is disrupted by analysis paralysis. + +* Exit Criteria + +Success: User asks "what's next" and immediately receives a clear, actionable recommendation. + +We know this workflow succeeded when: +- Claude provides **one task recommendation** (occasionally 2-3 if truly can't decide) +- The recommendation is **urgent+important** (deadline-driven) or **important** (priority+method order) +- User can **start working immediately** without second-guessing the choice +- User **stays in flow** and gets more done per session + +* When to Use This Workflow + +Trigger "what's next" when: +- Starting a work session and need to choose first task +- Completing a task and ready for the next one +- Feeling uncertain about priorities +- Tempted to pick an easy/fun task instead of important work +- Want external validation of task choice + +User says: "what's next" or "what should I work on next?" + +* Approach: How We Work Together + +** Prioritization Cascade + +Follow this decision tree in order: + +*** 1. Check for Incomplete In-Progress Tasks +- Look for tasks marked as in-progress or partially complete +- **If found:** Recommend that task (always finish what's started) +- **If user declines:** Continue to next step + +*** 2. Check Active Reminders +- Review Active Reminders section in project's NOTES.org (if it exists) +- **If found:** Recommend reminder task +- **If user declines:** Ask for priority and add to todo.org, then continue + +*** 3. Check for Deadline-Driven Tasks +- Scan todo.org for tasks with explicit deadlines +- **If found:** Recommend task with closest deadline +- **If none:** Continue to next step + +*** 4. Prioritize by V2MOM Method Order (if applicable) +If todo.org is structured with V2MOM methods: +- Method 1 priority A tasks first +- Then Method 2 priority A, Method 3 priority A, etc. +- Then Method 1 priority B, Method 2 priority B, etc. +- Continue pattern through priorities C and D + +*** 5. Prioritize by Priority Only (simple list) +If todo.org is a simple flat list: +- Evaluate all priority A tasks, pick most important +- If no priority A, evaluate priority B tasks +- Continue through priorities C and D + +*** 6. All Tasks Complete +- **If no tasks remain:** Report "All done! No more tasks in todo.org" + +** Handling Multiple Tasks at Same Level + +When multiple tasks have same priority/method position: + +Pick one based on: +1. **Blocks other work** - Dependencies matter +2. **Recently discussed** - Mentioned in recent conversation +3. **Most foundational** - Enables other tasks +4. **If truly uncertain** - Show 2-3 options and let user choose + +** Providing Context + +Keep recommendations concise but informative: +- Task name/description +- One-line reasoning +- Progress indicator (for V2MOM-structured todos) + +**Example:** +``` +Next: Fix org-noter reliability (Method 1, Priority A, 8/18 complete) +Reason: Blocks daily reading/annotation workflow +``` + +** Speed and Efficiency + +- Complete workflow in **< 30 seconds** +- Don't re-read files if recently accessed (use recent context) +- Trust objective criteria over subjective assessment +- If uncertain, ask clarifying question rather than guessing + +* Workflow Steps + +1. **Scan in-progress tasks** - Check for incomplete work from previous session +2. **Check reminders** - Review Active Reminders in NOTES.org +3. **Scan for deadlines** - Look for time-sensitive tasks in todo.org +4. **Apply priority cascade** - Use V2MOM method order or simple priority ranking +5. **Make recommendation** - One task (or 2-3 if uncertain) +6. **Show context** - Brief reasoning and progress indicator +7. **Accept user decision** - If user declines, move to next candidate + +* Tips for Success + +** For Users +- Trust the recommendation - it's based on objective criteria +- If you decline, ask "what else?" to get next candidate +- Update priorities/deadlines in todo.org regularly for best results +- Use Active Reminders for important follow-ups + +** For Claude +- Be decisive - one clear recommendation is better than analysis +- Show your reasoning - builds trust in the process +- Respect the cascade - don't skip steps +- Keep it fast - this should reduce friction, not add it + +* Related Workflows + +- **emacs-inbox-zero** - Triage todo.org against V2MOM framework +- **create-v2mom** - Build strategic framework for prioritization +- **wrap-it-up** - End session with clean handoff to next session |