diff options
| -rw-r--r-- | docs/NOTES.org | 54 | ||||
| -rw-r--r-- | docs/NOTES.org.backup | 1306 | ||||
| -rw-r--r-- | docs/workflows/create-v2mom.org (renamed from docs/sessions/create-v2mom.org) | 0 | ||||
| -rw-r--r-- | docs/workflows/create-workflow.org (renamed from docs/sessions/create-session.org) | 26 | ||||
| -rw-r--r-- | docs/workflows/emacs-inbox-zero.org (renamed from docs/sessions/emacs-inbox-zero.org) | 18 | ||||
| -rw-r--r-- | docs/workflows/refactor.org (renamed from docs/sessions/refactor.org) | 8 |
6 files changed, 1359 insertions, 53 deletions
diff --git a/docs/NOTES.org b/docs/NOTES.org index ea3a5ca2..68439ef4 100644 --- a/docs/NOTES.org +++ b/docs/NOTES.org @@ -70,8 +70,8 @@ When starting a new session with Craig: 2. **Check Active Reminders section** - Remind Craig of outstanding tasks 3. **Check Pending Decisions section** - Follow up on decisions needed 4. **Check V2MOM Progress** - Offer to work on top method/priority task - - If no V2MOM exists, offer to create one using docs/sessions/create-v2mom.org -5. **Scan docs/sessions/ directory** for available session types (see "Session Types" section below) + - If no V2MOM exists, offer to create one using docs/workflows/create-v2mom.org +5. **Scan docs/workflows/ directory** for available workflows (see "Available Workflows" section below) ** IMPORTANT: Reminders Protocol @@ -84,35 +84,35 @@ When Craig says "remind me" about something: 1. Add it to Active Reminders section in this file 2. If it's something he needs to DO, also add to =/home/cjennings/sync/org/roam/inbox.org= as TODO scheduled for today -** Session Types: "Let's do a [session type] session" +** Workflows: "Let's run/do the [workflow name] workflow" When Craig says this phrase: -1. **Check for exact match** in docs/sessions/ directory - - If exact match found: Read that session file and guide through workflow - - Example: "refactor session" → read docs/sessions/refactor.org +1. **Check for exact match** in docs/workflows/ directory + - If exact match found: Read that workflow file 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' session, or create new 'empty inbox'?" + - 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 '[session-type]' yet. Create it using create-session workflow?" - - If yes: Do create-session session, then use immediately (validates workflow) + - Say: "I don't see '[workflow-name]' yet. Create it using create-workflow process?" + - If yes: Do create-workflow workflow, then use immediately (validates new workflow) -** "I want to do an X session with you" - DIFFERENT MEANING! +** "I want to create an X workflow" - Creating New Workflows -⚠️ **IMPORTANT:** This phrase means something different! +⚠️ **IMPORTANT:** This is different from running an existing workflow! -When Craig says "I want to do an X session with you": -- This means: **CREATE a session definition** for doing X (meta-work) +When Craig says "I want to create an X workflow": +- This means: **CREATE a workflow definition** for doing X (meta-work) - This does **NOT** mean: "let's DO X right now" (the actual work) -- Triggers the create-session workflow from docs/sessions/create-session.org +- Triggers the create-workflow process from docs/workflows/create-workflow.org *Examples:* -- "I want to do an emacs inbox zero session" → Create docs/sessions/inbox-zero.org -- "I want to do a refactor session" → Create docs/sessions/refactor.org -- "I want to do a code review session" → Create docs/sessions/code-review.org +- "I want to create an inbox zero workflow" → Create docs/workflows/inbox-zero.org +- "I want to create a refactor workflow" → Create docs/workflows/refactor.org +- "I want to create a code review workflow" → Create docs/workflows/code-review.org ** "What Kind of Day Has It Been?" - Summary and Journal Routine @@ -490,12 +490,12 @@ make reset # Reset to first launch (destructive!) Created: 2025-11-03 Adapted from chime.el Makefile with config-specific enhancements -* 📋 AVAILABLE SESSION TYPES +* 📋 AVAILABLE WORKFLOWS -** create-session -File: [[file:sessions/create-session.org][docs/sessions/create-session.org]] +** create-workflow +File: [[file:workflows/create-workflow.org][docs/workflows/create-workflow.org]] -Meta-workflow for creating new session types. Use this when identifying repetitive workflows that would benefit from documentation. +Meta-workflow for creating new workflow definitions. Use this when identifying repetitive processes that would benefit from documentation. Workflow: 1. Q&A discovery (4 core questions) @@ -508,7 +508,7 @@ Workflow: Created: 2025-11-01 (pre-existing) ** create-v2mom -File: [[file:sessions/create-v2mom.org][docs/sessions/create-v2mom.org]] +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. Generic process applicable to Emacs config, health goals, financial planning, software development, or any long-running project. @@ -528,7 +528,7 @@ Time: ~2-3 hours total Created: 2025-11-05 ** emacs-inbox-zero -File: [[file:sessions/emacs-inbox-zero.org][docs/sessions/emacs-inbox-zero.org]] +File: [[file:workflows/emacs-inbox-zero.org][docs/workflows/emacs-inbox-zero.org]] Weekly workflow for processing the "Emacs Config Inbox" heading in =todo.org= to zero by filtering through V2MOM framework. @@ -826,13 +826,13 @@ Each entry should use this format: ** 2025-11-05 Tue @ 14:00 -0600 -*** Session: Create V2MOM Session Document +*** Session: Create V2MOM Workflow Document *Time:* ~30 minutes -*Status:* ✅ COMPLETE - Generic V2MOM session workflow documented +*Status:* ✅ COMPLETE - Generic V2MOM workflow documented *What We Completed:* -1. ✅ **Created docs/sessions/create-v2mom.org** +1. ✅ **Created docs/workflows/create-v2mom.org** - Fully generic workflow applicable to any project/goal - Works for health, finance, software, personal infrastructure, etc. - Comprehensive 8-phase process with examples across domains @@ -858,7 +858,7 @@ Each entry should use this format: - Time commitment (2-3 hours) justified by weeks of focused work it enables *Files Created:* -- docs/sessions/create-v2mom.org (comprehensive generic V2MOM workflow) +- docs/workflows/create-v2mom.org (comprehensive generic V2MOM workflow) *Next Steps:* - V2MOM workflow is now available for any future project diff --git a/docs/NOTES.org.backup b/docs/NOTES.org.backup new file mode 100644 index 00000000..ea3a5ca2 --- /dev/null +++ b/docs/NOTES.org.backup @@ -0,0 +1,1306 @@ +#+TITLE: 🚨 EMACS CONFIG - ACTIVE PROJECT NOTES 🚨 +#+AUTHOR: Claude Code Session Notes +#+DATE: 2025-10-30 + +* About This File + +This file contains important information for Claude to remember between sessions working on Craig's Emacs configuration. + +**When to read this:** +- At the start of EVERY session +- Before making any significant decisions +- When unclear about project direction or user preferences + +**What's in this file:** +- User information (calendar, task list, working style) +- Session protocols (how we start, wrap up, and work together) +- File preferences and naming conventions +- Emacs-specific development best practices +- Project status, goals, and history +- Active reminders and pending decisions + +Claude can modify this document to make collaboration more efficient and effective. + +* 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 + +** Task List Location +Craig's main task list is available at: =/home/cjennings/sync/org/roam/inbox.org= + +Use this to: +- Add tasks to Craig's task list +- Add reminders for Craig before next session +- See all tasks he's working on outside this project + +** Working Style + +*** General Preferences +- Prefers detailed preparation before high-stakes meetings +- Values practice/role-play for negotiations and learning +- Makes decisions based on principles and timeline arguments +- Prefers written documentation over verbal agreements + +*** Emacs as Primary Working Tool +- Craig uses Emacs for EVERYTHING (most-used software by significant margin) +- Consider Emacs packages alongside other software when recommending solutions +- Look for ways to streamline routine work with Emacs custom code if no packages exist +- Config breakage blocks ALL work (email, calendar, tasks, programming, reading, music) + +** Miscellaneous Information +- Craig currently lives in New Orleans, LA +- Craig's phone number: 510-316-9357 +- Maintains remote server at cjennings.net domain +- This project is in a git repository with remote at cjennings.net +- Also pushes to GitHub as backup remote + +* Session Protocols + +** Session Start Routine + +When starting a new session with Craig: + +1. **Read this file completely** to understand project context +2. **Check Active Reminders section** - Remind Craig of outstanding tasks +3. **Check Pending Decisions section** - Follow up on decisions needed +4. **Check V2MOM Progress** - Offer to work on top method/priority task + - If no V2MOM exists, offer to create one using docs/sessions/create-v2mom.org +5. **Scan docs/sessions/ directory** for available session types (see "Session Types" section below) + +** IMPORTANT: Reminders Protocol + +When starting a new session: +- Check "Active Reminders" section below +- Remind Craig of outstanding tasks he's asked to be reminded about +- This ensures important follow-up actions aren't forgotten + +When Craig says "remind me" about something: +1. Add it to Active Reminders section in this file +2. If it's something he needs to DO, also add to =/home/cjennings/sync/org/roam/inbox.org= as TODO scheduled for today + +** Session Types: "Let's do a [session type] session" + +When Craig says this phrase: + +1. **Check for exact match** in docs/sessions/ directory + - If exact match found: Read that session file and guide through workflow + - Example: "refactor session" → read docs/sessions/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' session, or create new 'empty inbox'?" + +3. **If no match at all:** Offer to create it + - Say: "I don't see '[session-type]' yet. Create it using create-session workflow?" + - If yes: Do create-session session, then use immediately (validates workflow) + +** "I want to do an X session with you" - DIFFERENT MEANING! + +⚠️ **IMPORTANT:** This phrase means something different! + +When Craig says "I want to do an X session with you": +- This means: **CREATE a session definition** for doing X (meta-work) +- This does **NOT** mean: "let's DO X right now" (the actual work) +- Triggers the create-session workflow from docs/sessions/create-session.org + +*Examples:* +- "I want to do an emacs inbox zero session" → Create docs/sessions/inbox-zero.org +- "I want to do a refactor session" → Create docs/sessions/refactor.org +- "I want to do a code review session" → Create docs/sessions/code-review.org + +** "What Kind of Day Has It Been?" - Summary and Journal Routine + +When Craig asks this: + +1. **Display summary** of work done and discussions + - Include: events, accomplishments, decisions, observations + - Write in Craig's voice (as if you were Craig) + - He'll review and approve or adjust + +2. **Add to Session History** below + - Use timestamp format: =YYYY-MM-DD Day @ HH:MM TZ= (get TZ with =date +%z=) + - Include summary from step 1 + - This creates permanent record for retrospectives + +3. **Note:** This info can also be part of wrap-up summary + +** "Wrap it up" / "That's a wrap" / "Let's call it a wrap" - End Session + +When Craig says any of these phrases (or variations), execute wrap-up workflow: + +1. **Write session notes** to this file (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 all changes** + - Check git status and diff + - Create descriptive commit message + - Include co-author attribution: =Co-Authored-By: Claude <noreply@anthropic.com>= + - Push to ALL remotes (origin at cjennings.net + github) + - Ensure working tree is clean + - Confirm push succeeded + +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 + +*Slash command:* =/wrap-it-up= triggers this same workflow + +** 🔔 Desktop Notifications Workflow + +**IMPORTANT: How Claude notifies Craig** + +Long-running tasks (> 1 minute) or blocking questions trigger desktop notifications via =notify-send=: + +#+BEGIN_SRC bash +notify-send "Claude Code" "Question: [Your input needed]" --urgency=normal +#+END_SRC + +**When notifications ARE sent:** +- ✅ When explicitly needing decision/input (blocking questions) +- ✅ When multiple valid approaches exist and choice affects implementation +- ✅ When encountering errors that require user guidance +- ✅ **ONLY** when Claude cannot proceed without user input + +**When notifications are NOT sent:** +- ❌ After completing tasks (informational updates) +- ❌ During normal progress updates +- ❌ When milestones are reached +- ❌ For status messages or completion notices +- ❌ ANY informational alerts + +**Setup:** +- Requires =dunst= or similar notification daemon +- Works with =notify-send= command +- Always uses =--urgency=normal= (not critical) + +**Purpose:** +Allows Craig to context-switch to other work while Claude runs long tasks. Get notified ONLY when input is needed. Check back when convenient for status updates. + +** The docs/ Directory + +Claude needs to add information to this NOTES file. For large amounts of information: + +- Create separate document in docs/ directory +- Link it here with explanation of document's purpose +- The docs/ directory should **never be committed** to git repository +- Unless specified otherwise, all Claude-generated documents go in docs/ folder + +**When to break out documents:** +- If this file 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 various 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 +# Edit affected .org files to change paths + +# 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.** + +* 🤔 PENDING DECISIONS + +** Flymake/Flycheck Modeline Integration + +Craig was interested in adding error/warning counts to the modeline but hasn't decided on implementation details yet. + +**Questions to decide:** + +1. **Flymake vs Flycheck?** + - Flymake is built-in and works with LSP (eglot) + - Flycheck requires installation but has more checker backends + +2. **Format preference?** + - Just counts: =E:3 W:5= + - With symbols: =⚠ 3 ✖ 5= + - Clickable to show diagnostics buffer? + +3. **Placement?** + - Left side near major-mode, or right side with VC branch? + +4. **Active window only?** + - Like your VC branch - only show in selected window + +**Implementation is ready** - just need Craig's preferences and Claude can add it exactly how he wants it. + +* 🧩 EMACS LISP DEVELOPMENT BEST PRACTICES + +**Critical Lessons: Preventing Parenthesis Errors** + +Both humans and AI struggle with balanced parentheses in deeply nested Emacs Lisp code. Here are proven strategies to prevent this: + +** For AI Code Generation + +*** 1. Write Small, Focused Functions +- Keep functions under 15 lines when possible +- Each function should do ONE thing +- Easier to verify parentheses at a glance +- Easier to test in isolation + +#+BEGIN_EXAMPLE +Bad (deeply nested, hard to verify): +(defun process-data (data) + (when (valid-p data) + (let ((result (transform data))) + (when result + (let ((final (format result))) + (when final + (save final))))))) + +Good (broken into helpers): +(defun process-data (data) + (when (valid-p data) + (save-result (format-result (transform-data data))))) + +(defun transform-data (data) ...) +(defun format-result (result) ...) +(defun save-result (final) ...) +#+END_EXAMPLE + +*** 2. Test Immediately After Each Write +- Write function → check-parens → test load → repeat +- Don't batch multiple functions before testing +- Catch errors early when context is fresh + +#+BEGIN_SRC bash +# After writing each function: +emacs --batch file.el --eval '(check-parens)' && echo "✓" +#+END_SRC + +*** 3. Prefer Write Over Multiple Edits +- For complex new code: use Write tool (complete file) +- Only use Edit for small, simple changes +- Incremental edits can introduce subtle paren mismatches +- Complete file Write is easier to verify + +*** 4. Validate Before Committing +- Use pre-commit hooks to validate all .el files +- Prevents committing broken code +- Example in chime.el repository: .git/hooks/pre-commit + +*** 5. Test Emacs Launch After Non-Trivial Changes +**CRITICAL: Always test that Emacs launches without errors after making changes** + +After completing any non-trivial code changes (new modules, integrations, etc.): + +#+BEGIN_SRC bash +# 1. Run unit tests (if applicable) +make test + +# 2. Test that Emacs launches without backtrace +emacs --eval "(kill-emacs)" +#+END_SRC + +This catches: +- Syntax errors in :command specifications +- Missing dependencies at load time +- Invalid use-package configurations +- Broken requires/provides + +**When to do this:** +- ✅ After adding new checker definitions (flycheck, flymake) +- ✅ After creating new modules +- ✅ After modifying init.el or early-init.el +- ✅ Before committing changes +- ✅ After running all unit tests + +**Example lesson:** The LanguageTool integration used =(eval (expand-file-name ...))= in +a =:command= specification, which caused a backtrace on startup. Testing Emacs launch +would have caught this immediately instead of discovering it on next restart. + +** For Human Developers + +*** 1. Use Structural Editing Modes +These PREVENT unbalanced parens: +- **paredit** - Classic, strict structural editing +- **smartparens** - More flexible, works with multiple languages +- **lispy** - Modal editing for lisps +- **electric-pair-mode** - Built-in, auto-closes parens + +*** 2. Enable Real-time Validation +- **flycheck** + **flycheck-package** - Shows errors as you type +- **flymake** - Built-in alternative +- **rainbow-delimiters-mode** - Colors matching parens + +*** 3. Quick Validation Commands +#+BEGIN_SRC elisp +M-x check-parens ; Check current buffer +M-x byte-compile-file ; More comprehensive checking +#+END_SRC + +** Lessons from chime-org-contacts.el Development + +*** Original Problem +Complex nested function with 6 levels of nesting: +- Hard to count parentheses manually +- AI kept adding/removing wrong number of closing parens +- Functions weren't defined after file load +- Wasted significant debugging time + +*** Solution That Worked +Refactored into 3 helper functions: +1. =chime-org-contacts--parse-birthday= (10 lines) +2. =chime-org-contacts--format-timestamp= (4 lines) +3. =chime-org-contacts--insert-timestamp-after-drawer= (12 lines) + +Main function became simple composition (10 lines). + +**Result:** +- All functions defined correctly +- Easy to verify parens by eye +- Each function testable independently +- 24 tests written covering all cases + +*** Key Insight +Breaking complex code into small helpers: +- ✅ Easier to verify correctness +- ✅ Easier to test +- ✅ Easier to maintain +- ✅ Self-documenting through function names +- ✅ AI and humans both succeed + +Deeply nested code: +- ❌ Hard to verify +- ❌ Hard to test +- ❌ AI frequently makes paren errors +- ❌ Humans make mistakes too + +** Tools and Workflow Summary + +| Stage | Tool | Purpose | +|-------+------+---------| +| Writing | paredit/smartparens | Prevent errors | +| Editing | rainbow-delimiters | Visual verification | +| Testing | check-parens | Quick syntax check | +| Testing | emacs --eval "(kill-emacs)" | Verify Emacs launches | +| CI/CD | pre-commit hooks | Prevent bad commits | +| Review | byte-compile-file | Comprehensive check | + +** Makefile - Comprehensive Testing & Validation Tool + +A comprehensive Makefile is available in the repository root with targets for testing, validation, and utilities. + +#+BEGIN_SRC bash +make # Show all available targets +make test # Run all tests (unit + integration) +make test-file FILE=... # Run specific test file +make test-name TEST=... # Run tests matching pattern +make validate-parens # Check for unbalanced parentheses +make validate-modules # Load all modules to verify compilation +make compile # Byte-compile all modules +make lint # Run checkdoc, package-lint, elisp-lint +make profile # Profile Emacs startup +make clean # Remove test artifacts and compiled files +make reset # Reset to first launch (destructive!) +#+END_SRC + +Created: 2025-11-03 +Adapted from chime.el Makefile with config-specific enhancements + +* 📋 AVAILABLE SESSION TYPES + +** create-session +File: [[file:sessions/create-session.org][docs/sessions/create-session.org]] + +Meta-workflow for creating new session types. 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 session +4. Document it +5. Update NOTES.org +6. Validate by execution + +Created: 2025-11-01 (pre-existing) + +** create-v2mom +File: [[file:sessions/create-v2mom.org][docs/sessions/create-v2mom.org]] + +Workflow for creating a V2MOM (Vision, Values, Methods, Obstacles, Metrics) strategic framework for any project or goal. Generic process applicable to Emacs config, health goals, financial planning, software development, or any long-running project. + +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 + +Created: 2025-11-05 + +** emacs-inbox-zero +File: [[file:sessions/emacs-inbox-zero.org][docs/sessions/emacs-inbox-zero.org]] + +Weekly workflow for processing the "Emacs Config Inbox" heading in =todo.org= to zero by filtering through V2MOM framework. + +Workflow: +1. Sort by priority (A → B → C → none → D) +2. Claude rereads V2MOM +3. Process each item through 3 questions: + - Does this need to be done? → DELETE if no + - Related to V2MOM? → Move to someday-maybe if no + - Which method? → Move to appropriate method +4. Done when inbox heading is empty + +Target: 10 minutes active work time +Cadence: Every Sunday, no longer than 7 days between sessions +Maintains metrics: Active todos < 20, weekly triage consistency + +Created: 2025-11-01 + +* CURRENT PROJECT STATUS + +** 🎯 What We're Doing +Working through a systematic approach to clean up and prioritize Craig's Emacs config work: + +1. ✅ *COMPLETE V2MOM* (Vision, Values, Methods, Obstacles, Metrics) - DONE +2. ✅ *TRIAGE todo.org* - Used V2MOM to ruthlessly cancel ~60% of tasks +3. ⏳ *EXECUTE METHODS* - Working through prioritized tasks systematically +4. ⏳ *BUILD OBSERVABILITY* - Create profiling infrastructure (Method 3) +5. ⏳ *SYSTEMATIC EXECUTION* - Work through prioritized tasks one by one + +** 📍 Where We Are Right Now +*Session Started:* 2025-10-30 +*Current Step:* ✅ V2MOM COMPLETE - Executing methods systematically +*Time Committed:* Multiple sessions since 2025-10-30 +*Status:* V2MOM complete, executing Method 1 & 2 tasks, good progress on metrics + +** 📄 Key Documents + +*** Primary Working Documents +- *V2MOM:* [[file:EMACS-CONFIG-V2MOM.org][EMACS-CONFIG-V2MOM.org]] - Strategic framework for Emacs config (✅ COMPLETE) + - Vision, Values, Methods, Obstacles, Metrics + - Used for decision-making and weekly triage + - Read this first to understand strategic direction +- *Issues Analysis:* [[file:../issues.org][../issues.org]] - Claude's detailed analysis with TIER system and implementations +- *Current Inbox:* [[file:../inbox.org][../inbox.org]] - V2MOM-aligned tasks (~23 items after ruthless triage) + +*** Reference Documents +- *Config Root:* [[file:../init.el][../init.el]] +- *Modules:* [[file:../modules/][../modules/]] +- *Tests:* [[file:../tests/][../tests/]] + +** 🔑 Key Insights About Craig's Work Patterns + +*** Strengths +- Thoughtful and strategic thinker +- Good research skills (thorough specs, complete code examples) +- Does ship things (dashboard, dirvish, network check fixes, transcription) +- Recognizes need for V2MOM framework +- Uses config daily for real work + +*** Patterns to Address +1. *Research > Execution* - Had complete code for several features, still TODO +2. *Priority Inflation* - Too many [#A]/[#B] items, unclear what's actually urgent +3. *Hard to Say No* - [#C]/[#D] items should be CANCELLED but remain in list +4. *Side Projects Compete* - Dupre theme work competes with core config maintenance + +*** What Craig Told Us About Himself +> "I am building tools both because they solve problems, but also because I enjoy building." + +This is healthy! But need balance: +- Fix rough edges FIRST (daily pain points) +- Build fun stuff SECOND (after maintenance) +- Cancel distractions ALWAYS (Signal client, minimap, etc.) + +** 🎯 Agreed Goals for This Project + +*** Immediate (Next 2-3 Sessions) +1. ✅ Complete V2MOM +2. ✅ Triage todo.org using V2MOM as filter +3. ⏳ Execute quick wins: network check, bug fixes, integrations +4. ⏳ Build debug-profiling.el infrastructure + +*** Short Term (Next Month) +5. Profile and optimize org-agenda performance +6. Ship reveal.js presentation workflow +7. Establish weekly triage ritual + +*** Long Term (Ongoing) +8. Ship more than research +9. Maintain < 20 active todos +10. Measure metrics from V2MOM + +** 📋 TIER System from issues.org + +*** TIER 1: Do These First (High Impact, Low Effort) - 1 weekend +- Remove network check (15 min) - ✅ DONE +- Fix missing functions (30 min) - ✅ DONE +- Corfu migration (2 hours) - Deferred (Company works fine) +- Mood-line switch (30 min) - ✅ DONE +- Bug fixes (1 hour) - ✅ DONE + +*** TIER 2: Build Observability (HIGHEST VALUE) - 1 week +- Create debug-profiling.el module (3-4 hours) +- Profile org-agenda-rebuild (1 hour) +- Add instrumentation and caching (2 hours) +- Test org-agenda filtering functions (2-3 hours) + +*** TIER 3: Quick Wins (After Profiling) - 1-2 hours each +- Reveal.js presentation workflow (2 hours) +- Difftastic integration (30 min) - ✅ DONE +- Local package development workflow (1 hour) + +*** TIER 4: Maybe/Someday (Probably Never) +- Code-maat reimplementation (HOLD) +- LaTeX config (HOLD until concrete need) +- Elfeed dashboard (HOLD - unclear if actually used) +- DWIM shell integration (HOLD - current solution works) +- Jumper package (HOLD - already maintaining chime + org-msg) + +** 🚫 Items That Should Be CANCELLED + +From todo.org, these don't serve the vision: +- [#D] Signal Client - Not in vision +- [#D] Awesome-tray / mode-icons - Already have modeline +- [#C] Minimap - Interesting, not important +- [#C] Install Magit TODOs - Already works fine +- [#C] Git Timemachine litters buffers - Minor annoyance +- Many Dupre theme TODOs - Side project competing with maintenance + +** 💡 Key Recommendations for Craig + +*** Week 1: Strategy + Quick Wins +1. ✅ Complete V2MOM (2-3 hours) +2. ✅ Triage todo.org using V2MOM (1-2 hours) +3. ✅ Execute items you already have code for (2-3 hours) + +*** Week 2: Observability Infrastructure +4. Build debug-profiling.el (3-4 hours) +5. Profile org-agenda (1 hour) + +*** Week 3: Fix Performance + Ship Presentation +6. Fix org-agenda based on profiling (2-3 hours) +7. Ship reveal.js workflow (2 hours) + +*** Ongoing: Maintenance Discipline +- Weekly triage ritual (30 min every Sunday) +- Measure metrics (startup time, agenda time, todo count) +- Ship > Research + +** 🔄 Next Session Pickup Points + +When starting next session, Claude should: + +1. **Read this document first** to understand context +2. **Check Active Reminders** - Follow up on pending items +3. **Check Pending Decisions** - See if Craig has made decisions +4. **Check V2MOM status** - Continue with next priority method/task +5. **Ask Craig:** "What would you like to work on today?" + +** 🎯 Success Metrics for This Project + +We'll know this is working when: +- ✅ V2MOM is complete and provides clear strategic direction +- ✅ todo.org shrinks from ~50 to < 20 active items +- ✅ Craig ships 3-5 items per week (small but consistent) +- ⏳ Craig has profiling infrastructure to measure performance +- ⏳ Org agenda rebuild time is measured and improving +- ⏳ Weekly triage becomes habit + +** 💬 Craig's Words to Remember + +> "I think you should adjust issues.org with all your recommendations. They are exciting, eye-opening, and just feel right. Add even your guidance on latex. spot on. thanks for your honesty. I did ask for it and am genuinely grateful for your responses. I'll take action on them." + +> "What I need help with is integrating this in with my existing todo.org file... Some of the tasks I've listed should probably just be deleted or better yet, marked CANCELLED." + +> "I have about an hour to devote. You could lead me through it, I could do some questions/answer rounds with you to clarify my thinking." + +> "There will always be cool ideas out there to implement and they will always be a web search away." + +Craig is ready to execute. He asked for honesty and took it well. He recognizes the patterns and wants systematic help. + +** 🛠️ Technical Context + +*** Current Pain Points +1. Org agenda is slow (performance bottleneck) - Need profiling +2. ✅ Network check removed (was adding 1+ seconds to startup) +3. ✅ Missing functions fixed (cj/log-silently, cj/goto-git-gutter-diff-hunks) +4. Mail attachments workflow needs improvement +5. No profiling infrastructure to measure performance + +*** Items Craig Already Has Code For +These can be executed immediately - just paste and test: +- ✅ Transcription workflow (implemented 2025-11-04) +- ✅ Difftastic integration (implemented 2025-11-03) +- Corfu migration (complete config, but deferred - Company works fine) + +*** Architecture +- Modular structure: modules/*.el +- Good test coverage for utilities +- Modern packages: Vertico/Consult/Embark stack +- Local package development: chime.el, org-msg + +** 📚 Related Reading + +If Craig or Claude need more context: +- [[file:../issues.org::*Second Opinion: Ruthless Prioritization & Reality Checks][Second Opinion section in issues.org]] - Full analysis and recommendations +- [[file:../issues.org::*TIER 1: Do These First][TIER 1-4 breakdown]] - Prioritized task system +- [[file:../quality-engineer.org][quality-engineer.org]] - Testing philosophy + +* 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). + +** Format for Session History Entries + +Each entry should use this format: +- **Timestamp:** =*** YYYY-MM-DD Day @ HH:MM TZ-INFO= (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 +- **Next Steps:** What to do next session (if applicable) + +** 2025-11-05 Tue @ 15:30 -0600 + +*** Session: NOTES.org Consolidation & Template Integration + +*Time:* ~45 minutes +*Status:* ✅ COMPLETE - Single comprehensive NOTES.org with generic protocols + +*What We Completed:* +1. ✅ **Consolidated two NOTES.org files** + - Deleted root ~/.emacs.d/NOTES.org (older 184-line version) + - Kept docs/NOTES.org (comprehensive 1017-line version) as single source of truth + - Eliminated duplicate/conflicting documentation + +2. ✅ **Enhanced docs/NOTES.org with template sections** + - Reviewed template at ~/documents/claude/NOTES.org for generic best practices + - Added "About This File" introduction with clear purpose + - Added User Information section (calendar, task list, working style) + - Enhanced Session Protocols: + - Session Start Routine with checklist + - **IMPORTANT: Reminders Protocol** (check at start, add to both files) + - "What Kind of Day Has It Been?" journal routine + - Enhanced "Wrap it up" workflow with detailed steps + - The docs/ directory management guidance + - Added File Format Preferences (always .org, no spaces in filenames) + - Added File Naming Conventions (TOOLARGE- prefix, .docx handling, link maintenance) + - Added Active Reminders section with instructions + - Improved Session History format guidance + +3. ✅ **Preserved all Emacs-specific content** + - Kept all development best practices + - Kept entire project status and history + - Kept all session notes from previous work + - Final file: 1252 lines of comprehensive guidance + +*Key Decisions:* +- Single NOTES.org file in docs/ directory (not root) is canonical +- Template at ~/documents/claude/ remains unchanged (as requested) +- Generic protocols now available for all Craig's projects with Claude +- NOTES.org serves as both project-specific and general collaboration guide + +*Files Modified:* +- docs/NOTES.org - Enhanced with template protocols (1017 → 1252 lines) + +*Files Deleted:* +- NOTES.org (root directory) - Removed duplicate + +*Files NOT Modified (as requested):* +- ~/documents/claude/NOTES.org - Template preserved unchanged + +*Impact:* +- Single comprehensive reference for all Claude Code sessions on Emacs config +- Generic session protocols now documented and reusable +- Clear guidance on reminders, wrap-up, file naming, and link maintenance +- Future sessions will have better structure and consistency + +** 2025-11-05 Tue @ 14:00 -0600 + +*** Session: Create V2MOM Session Document + +*Time:* ~30 minutes +*Status:* ✅ COMPLETE - Generic V2MOM session workflow documented + +*What We Completed:* +1. ✅ **Created docs/sessions/create-v2mom.org** + - Fully generic workflow applicable to any project/goal + - Works for health, finance, software, personal infrastructure, etc. + - Comprehensive 8-phase process with examples across domains + - Time estimate: ~2-3 hours to create a V2MOM + +2. ✅ **Genericized from Emacs-specific version** + - Removed all Emacs-specific instructions from process + - Added diverse examples: health V2MOM, finance V2MOM, software V2MOM + - Kept detailed Emacs config V2MOM as one example case study + - Universal patterns identified: Fix → Stabilize → Build → Enhance → Sustain + +3. ✅ **Comprehensive documentation** + - Clear phase-by-phase instructions + - Decision frameworks for common situations + - Principles to follow (honesty over aspiration, concrete over abstract) + - Living document guidance + - Multiple real-world examples + +*Key Decisions:* +- V2MOM process should be project-agnostic at its core +- Examples should span multiple domains to show universality +- Emacs config V2MOM serves as detailed case study showing impact +- Time commitment (2-3 hours) justified by weeks of focused work it enables + +*Files Created:* +- docs/sessions/create-v2mom.org (comprehensive generic V2MOM workflow) + +*Next Steps:* +- V2MOM workflow is now available for any future project +- Can be used to create V2MOMs for: chime.el, org-msg, health goals, finances, etc. +- Ready to use whenever Craig needs strategic framework for new initiative + +** 2025-11-05 Tue @ 09:00 -0600 + +*** Session 2 - Scratch Buffer Configuration + +*Time:* ~5 minutes +*Status:* ✅ COMPLETE - Scratch buffer opens in org-mode with cursor at end + +*Problem:* +- Scratch buffer opened in lisp-interaction-mode +- Cursor positioned at beginning of buffer +- Craig wanted org-mode with cursor ready to type at end + +*Solution:* +1. **Set scratch buffer to org-mode** - =(setopt initial-major-mode 'org-mode)= +2. **Move cursor to end on startup** - Added =emacs-startup-hook= to position cursor +3. **Updated comment syntax** - Changed =;;= to =#= in greeting messages for org-mode + +*Files Modified:* +- modules/system-utils.el:186-203 + - Added =initial-major-mode= configuration + - Added startup hook for cursor positioning + - Updated greeting message comment syntax for org-mode compatibility + +*Technical Details:* +- Used =emacs-startup-hook= to run after init completes +- Buffer name check ensures we only affect *scratch* buffer +- Greeting message now uses org-mode comment syntax (#) + +*** Session 1 - Fix Google Calendar Password Prompts + +*Time:* ~15 minutes +*Status:* ✅ COMPLETE - Fixed irritating password prompts every 10 minutes + +*Problem:* +- Google Calendar auto-sync timer prompting for oauth2-auto.plist passphrase every ~10 minutes +- Interrupting workflow with pinentry dialogs +- Despite having gpg-agent configured with 400-day cache timeout + +*Root Cause:* +- Line 27 in modules/auth-config.el: =(setenv "GPG_AGENT_INFO" nil)= +- This was telling Emacs to IGNORE the gpg-agent entirely +- Result: gpg-agent's 400-day cache was being bypassed +- Plstore (used by oauth2-auto) was loading too late in org-gcal-config + +*Solution:* +1. **Disabled GPG_AGENT_INFO override** - Commented out line preventing agent use +2. **Added auth-source-cache-expiry** - 24-hour cache for decrypted credentials +3. **Moved plstore configuration** - From org-gcal-config to auth-config (loads earlier) +4. **Set plstore caching globally** - =plstore-cache-passphrase-for-symmetric-encryption t= + +*Files Modified:* +- modules/auth-config.el: + - Commented out =(setenv "GPG_AGENT_INFO" nil)= (was preventing cache) + - Added =(setq auth-source-cache-expiry 86400)= (24-hour cache) + - Added new plstore use-package block with caching enabled +- modules/org-gcal-config.el: + - Removed plstore configuration (now in auth-config.el) + - Updated comments to reference global config + +*Technical Details:* +- oauth2-auto.plist uses symmetric encryption (passphrase-based) +- gpg-agent.conf already had =default-cache-ttl 34560000= (400 days) +- gpg-agent needed to be reloaded: =gpgconf --reload gpg-agent= +- Plstore now caches passphrase indefinitely via gpg-agent + +*User Quote:* +> "It's making me crazy!" + +Totally valid! Getting interrupted every 10 minutes is legitimately maddening. Fixed! ✅ + +** 2025-11-04 Mon @ 15:00 -0600 + +*** Session 4 - External Dependencies Audit + +*Time:* ~30 minutes +*Status:* ✅ COMPLETE - Comprehensive dependency analysis documented + +*What We Completed:* + +1. ✅ **Comprehensive External Dependencies Analysis** + - Systematically analyzed entire codebase for external tool dependencies + - Identified ~50 external dependencies across all feature areas + - Organized by functionality: media, email, programming, documents, etc. + - Distinguished required vs optional dependencies + +2. ✅ **Created config-dependencies.org** + - Quick reference commands (minimal, recommended, full install) + - Detailed documentation for each dependency: + - Package names (pacman/yay/pip/npm/go) + - What modules use them + - Functionality enabled + - Required vs optional status + - Installation commands + - Summary table by feature area + - Installation notes for different package managers + +3. ✅ **Next Steps Documented** + - TODO: Compare with archsetup script + - TODO: Create dependency verification script + - TODO: Add to main documentation + +*Key Dependencies Identified:* +- Core: git, ripgrep, fd +- Media: ffmpeg, libpulse, yt-dlp, mpv, python-openai-whisper +- Email: mu, isync, msmtp +- Grammar: languagetool, aspell +- Programming: clang, python-lsp-server, gopls, bash-language-server, shellcheck +- Documents: pandoc, texlive, poppler +- Desktop: dunst, xdg-utils + +*Files Created:* +- config-dependencies.org (comprehensive dependency documentation) + +*** Session 3 - LanguageTool Grammar Checker Test Suite + +*Time:* ~1 hour +*Status:* ✅ COMPLETE - Comprehensive test suite with 15 passing tests + +*What We Completed:* + +1. ✅ **Created Test Fixtures** (tests/fixtures/) + - grammar-errors-basic.txt - Common grammar errors (subject-verb, could of, etc.) + - grammar-errors-punctuation.txt - Punctuation and spacing issues + - grammar-correct.txt - Clean baseline for comparison + - Deterministic fixtures for reliable testing + +2. ✅ **Unit Tests** (test-flycheck-languagetool-setup.el) + - 6 tests verifying LanguageTool installation and setup + - Checks binary availability, wrapper script existence + - Validates wrapper script structure (shebang, imports) + - Tests error handling for missing arguments + - All tests pass ✓ (< 1 second) + +3. ✅ **Integration Tests** (test-integration-grammar-checking.el) + - 9 tests covering end-to-end grammar checking workflow + - Tests wrapper script with real LanguageTool execution + - Validates flycheck-compatible output format + - Normal cases: error detection, output formatting + - Boundary cases: empty files, single word, multiple paragraphs + - Error cases: nonexistent files, missing arguments + - All tests pass ✓ (~35 seconds with real LanguageTool execution) + +4. ✅ **Applied Testing Philosophy** from quality-engineer.org + - Focus on OUR code (wrapper script), not flycheck internals + - Trust external frameworks work correctly + - Test real integration with actual LanguageTool execution + - Comprehensive docstrings listing integrated components + - Clear test categories: Normal, Boundary, Error cases + - No over-mocking of domain logic + +*Key Decisions:* +- Don't test flycheck framework internals (trust it works) +- Test our integration code with real external tools +- Use real fixtures instead of generated test data +- Integration tests run slower but provide high confidence + +*Files Created:* +- tests/test-flycheck-languagetool-setup.el +- tests/test-integration-grammar-checking.el +- tests/fixtures/grammar-errors-basic.txt +- tests/fixtures/grammar-errors-punctuation.txt +- tests/fixtures/grammar-correct.txt + +*Test Results:* +- Unit tests: 6/6 passing +- Integration tests: 9/9 passing +- Total: 15/15 tests ✓ + +*** Session 2 - Emergency Bug Fixes & Modeline Polish + +*Time:* ~30 minutes +*Status:* ✅ COMPLETE - Fixed async buffer error and improved modeline spacing + +*What We Completed:* + +1. ✅ **Fixed Critical Async Buffer Error on Startup** + - Problem: "Selecting deleted buffer" error in async.el during init + - Root cause: wttrin-mode-line-mode starting async HTTP request during init + - Solution: Delayed activation using after-init-hook + - Weather widget now loads AFTER Emacs finishes initializing + - Prevents async buffer from being killed before request completes + +2. ✅ **Fixed Parenthesis Error in weather-config.el** + - Removed extra closing parenthesis that prevented file from loading + - Verified with check-parens + +3. ✅ **Improved Modeline Right-Side Spacing** + - Problem: Right-most icon (weather) appeared flush with window edge + - Discovered: Regular spaces were being trimmed by right-align mechanism + - Solution: Added 2 non-breaking spaces (U+00A0) after misc-info segment + - Provides visual breathing room without being excessive + +*Key Technical Insights:* +- Async operations during init need careful timing (use after-init-hook) +- mode-line-right-align-edge 'right-margin trims trailing regular spaces +- Non-breaking spaces (U+00A0) survive trimming in modeline format + +*Files Modified:* +- modules/weather-config.el - Added after-init-hook delay for mode-line widget +- modules/modeline-config.el - Added 2 non-breaking spaces at end + +*** Session 1 - Complete Transcription Workflow Implementation + +*Time:* ~3 hours +*Status:* ✅ COMPLETE - Full async transcription system with 60 passing tests + +*What We Completed:* + +1. ✅ **Installed Whisper Locally** + - Created install-whisper.sh with AUR support (python-openai-whisper) + - Created uninstall-whisper.sh for clean removal + - Installed via AUR successfully + - Added --yes flag for non-interactive automation + +2. ✅ **Created CLI Transcription Scripts** + - scripts/local-whisper - Uses installed Whisper (works offline) + - scripts/oai-transcribe - Uses OpenAI API (faster, requires API key) + - Both scripts output to stdout, log to stderr + - Proper error handling and validation + +3. ✅ **Implemented Full Transcription Module** (modules/transcription-config.el) + - Async transcription workflow (non-blocking) + - Desktop notifications (started, complete, error) + - Output: audio.txt (transcript) + audio.log (process logs) + - Log cleanup: auto-delete on success (configurable) + - Modeline integration: Shows ⏺count of active transcriptions + - Clickable modeline to view *Transcriptions* buffer + - Process tracking and management + +4. ✅ **Comprehensive Test Suite - 60 Tests, All Passing** + - test-transcription-audio-file.el (16 tests) - Extension detection + - test-transcription-paths.el (11 tests) - File path logic + - test-transcription-log-cleanup.el (5 tests) - Log retention + - test-transcription-duration.el (9 tests) - Time formatting + - test-transcription-counter.el (11 tests) - Active count & modeline + - test-integration-transcription.el (8 tests) - End-to-end workflows + - Tests found and fixed 1 bug (nil handling in audio detection) + - Normal, boundary, and error cases covered + +5. ✅ **Reorganized Keybindings** + - Moved gcal from C-; g/t/r/G to C-; g s/t/r/c submenu + - Created C-; t transcription submenu: + - C-; t a → transcribe audio + - C-; t v → view transcriptions + - C-; t k → kill transcription + - Dired/Dirvish: T → transcribe file at point + - which-key integration for discoverability + +6. ✅ **Added Audio Extensions to user-constants.el** + - Centralized cj/audio-file-extensions list + - Shared across transcription and future audio features + - Used defvar (not defcustom) per Craig's preference + +*Key Decisions:* +- **Simplified UX:** No org-capture integration (initially planned), just file in/out +- **Minimalist approach:** Audio files → .txt transcripts (no complex templates) +- **Testable architecture:** Pure functions separated from I/O +- **defvar over defcustom:** All configuration variables use defvar + +*Files Created:* +- scripts/install-whisper.sh +- scripts/uninstall-whisper.sh +- scripts/local-whisper +- scripts/oai-transcribe +- modules/transcription-config.el +- tests/test-transcription-*.el (5 test files) + +*Files Modified:* +- modules/user-constants.el (added cj/audio-file-extensions) +- modules/org-gcal-config.el (reorganized keybindings to C-; g submenu) + +** 2025-11-03 Sun @ 13:00 -0600 + +*** Modeline Polish & Wrap-Up Workflow + +*Time:* ~30 minutes +*Status:* ✅ COMPLETE - Code quality improvements and workflow automation + +*What We Completed:* +1. ✅ Fixed all checkdoc linting errors in modeline-config.el (8 warnings → 0) + - Removed embedded keycodes from docstrings (mouse-1, mouse-3) + - Added double spaces after periods per Emacs conventions + - Quoted Lisp symbols with backticks (=vc-diff=, =describe-mode=) + - Fixed single quotes in examples to use proper backtick quoting + - File now passes checkdoc and byte-compilation cleanly + +2. ✅ Created =/wrap-it-up= workflow automation + - Slash command: =.claude/commands/wrap-it-up.md= + - Phrase recognition: "let's wrap it up", "that's a wrap", "let's call it a wrap" + - Workflow: Write notes → Git commit & push → Valediction summary + - Documented in both slash command and NOTES.org terminology section + - Ensures clean session endings with no lost work + +3. ✅ Added reminder for Flymake/Flycheck modeline integration + - Created "PENDING DECISIONS" section in NOTES.org + - Questions documented: Flymake vs Flycheck, format, placement, active window + - Implementation ready - just needs user preferences + - Craig will be reminded proactively at next session start + +*Key Decisions:* +- Dual documentation approach (slash command + phrase recognition) for reliability +- Craig expressed gratitude: "my life is genuinely improving while working with you" +- Modeline work quality bar: must pass all linters before shipping + +** 2025-10-31 Thu @ 14:00 -0600 + +*** Session 2 - V2MOM Complete! + +*Time:* ~1.5 hours +*Status:* ✅ COMPLETE - V2MOM finalized and ready for use + +*What We Completed:* +1. ✅ Finalized all 6 Methods with aspirational bodies and concrete actions: + - Method 1: Make Using Emacs Frictionless (performance & functionality fixes) + - Method 2: Stop Problems Before They Appear (proactive package maintenance) + - Method 3: Make *Fixing* Emacs Frictionless (observability/tooling) + - Method 4: Contribute to the Emacs Ecosystem (package maintenance tooling) + - Method 5: Be Kind To Your Future Self (new features) + - Method 6: Develop Disciplined Engineering Practices (meta-method with measurable outcomes) + +2. ✅ Completed Obstacles section (6 honest, personal obstacles with real stakes) + - Building vs fixing tension + - Getting irritated at mistakes + - Hard to say "no" + - Perfectionism + - Limited time sessions + - New habits are hard to sustain + +3. ✅ Completed Metrics section (Performance, Discipline, Quality metrics) + - Startup time: < 3s (currently 6.2s) + - Org-agenda: < 5s (currently 30+s) + - Active todos: < 20 (currently ~50+) + - Weekly triage consistency + - Research:shipped ratio > 1:1 + - Config uptime: never broken > 2 days + - Test coverage: > 70% with justification for uncovered code + +4. ✅ Implemented cj/diff-buffer-with-file + - Added to modules/custom-buffer-file.el + - Bound to C-; b D + - Unified diff format with proper error handling + - TODO comment for future difftastic integration + +5. ✅ Added missing items to Methods based on Craig's research: + - Fixed org-noter (Method 1) + - Added Buttercup (Method 3) + - Added package maintenance tools (Method 4: package-lint, melpazoid, elisp-check, undercover) + - Added wttrin to maintained packages list + +*Key Insights:* +- Craig wants to DELETE research files: "There will always be cool ideas out there to implement and they will always be a web search away" +- Ruthless prioritization is already happening +- Method ordering: fix → stabilize → build infrastructure → contribute → enhance → sustain +- Adjusted startup target from 2s to 3s (more achievable, less perfectionism trap) + +*Key Files Modified:* +- [[file:EMACS-CONFIG-V2MOM.org][EMACS-CONFIG-V2MOM.org]] - Now 100% complete with all sections filled +- [[file:../modules/custom-buffer-file.el][modules/custom-buffer-file.el]] - Added cj/diff-buffer-with-file function + +*** Session 3 - RUTHLESS EXECUTION! 🚀 + +*Time:* ~2 hours +*Status:* Method 1 in progress - shipped 2 wins, discovered 3 bugs + +*What We Completed:* +1. ✅ **RUTHLESS PRIORITIZATION EXECUTED!** + - Moved todo.org → docs/someday-maybe.org (~50 items archived) + - Created fresh inbox.org with ONLY V2MOM-aligned tasks (23 items) + - Already under < 20 active items goal! + +2. ✅ **SHIPPED: Network check removal** (Method 1) + - Deleted =cj/internet-up-p= blocking ping function + - Removed network cache variables + - Simplified to use package priorities instead + - .localrepo (priority 200) ensures offline reproducibility + - **RESULT: 6.19s → 4.16s startup time (2.03 seconds faster!)** + +3. ✅ **SHIPPED: cj/diff-buffer-with-file** (Method 1) + - Implemented in modules/custom-buffer-file.el + - Bound to C-; b D + - Weekly need satisfied + +4. ✅ **Updated reset-to-first-launch.sh** + - Added missing transient files/directories + - Keeps docs/, inbox.org, .localrepo safe + - Ready for testing offline installs + +5. ✅ **Tested .localrepo offline install capability** + - Works perfectly for package.el packages + - Discovered 3 bugs during test (logged in inbox.org) + +*Bugs Discovered (all logged in inbox.org):* +1. **Chime throw/catch error** - High priority + - Error: "(no-catch --cl-block-chime-check-- nil)" + - Fix: Change defun to cl-defun or add catch block + - Currently disabled to unblock startup + +2. **go-ts-mode-map keybinding error** + - Error: "void-variable go-ts-mode-map" + - Fix: Wrap in with-eval-after-load + +3. **Treesitter grammars not in .localrepo** (limitation documented) + - Expected behavior - treesit-auto downloads separately + +*Metrics Update:* +- Startup time: 6.19s → 4.16s (**2.03s improvement!**) +- Only 1.16s away from < 3s target! +- Active todos: ~23 items (hit < 20 goal when excluding tracking tasks!) +- Shipped items: 2 (network check, diff-buffer-with-file) + +*Key Files Modified:* +- [[file:../early-init.el][early-init.el]] - Network check removed, cj/use-online-repos simplified +- [[file:../modules/custom-buffer-file.el][custom-buffer-file.el]] - Added cj/diff-buffer-with-file +- [[file:../inbox.org][inbox.org]] - Fresh V2MOM-aligned todo list created +- [[file:../scripts/reset-to-first-launch.sh][reset-to-first-launch.sh]] - Updated with missing transient files +- [[file:SOMEDAY-MAYBE.org][SOMEDAY-MAYBE.org]] - Old todo.org archived here + +*Craig's Words:* +> "There will always be cool ideas out there to implement and they will always be a web search away." + +Ruthless prioritization in action! Deleted research files, focused execution. + +** 2025-10-30 Wed @ 13:00 -0600 + +*** Session 1 - V2MOM In Progress + +*Time:* ~1 hour +*Status:* PAUSED - V2MOM 60% complete + +*What We Completed:* +1. ✅ Created docs/ directory structure +2. ✅ Created SESSION-HANDOFF-ACTIVE-PROJECT.org +3. ✅ Created emacs-config-v2mom.org +4. ✅ Created values-comparison.org (analysis doc) +5. ✅ Completed Vision (already existed, kept as-is) +6. ✅ Completed Values section (Intuitive, Fast, Simple) + - Intuitive: Muscle memory, mnemonics, which-key timing, "newspaper" code + - Fast: Startup < 2s, org-agenda is THE bottleneck, everything else acceptable + - Simple: Production software practices, simplicity produces reliability diff --git a/docs/sessions/create-v2mom.org b/docs/workflows/create-v2mom.org index d6a82c0e..d6a82c0e 100644 --- a/docs/sessions/create-v2mom.org +++ b/docs/workflows/create-v2mom.org diff --git a/docs/sessions/create-session.org b/docs/workflows/create-workflow.org index a0e4d2fe..b6896fd8 100644 --- a/docs/sessions/create-session.org +++ b/docs/workflows/create-workflow.org @@ -4,7 +4,7 @@ * Overview -This document describes the meta-workflow for creating new session types. When we identify a repetitive workflow or collaborative pattern, we use this process to formalize it into a documented session that we can reference and reuse. +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 session that we can reference and reuse. Session 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. @@ -64,8 +64,8 @@ Trigger this session 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 session for [activity]" -- You identify a new type of work that doesn't fit existing session types -- An existing session type needs significant restructuring (treat as creating a new one) +- 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 session where we inbox zero" @@ -82,7 +82,7 @@ Walk through these four core questions collaboratively. Take notes on the answer 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/sessions/[name]-draft.org= after deciding on the name +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 session is interrupted, you can resume from the saved answers 4. Once complete, the draft becomes the final session document @@ -187,16 +187,16 @@ After the Q&A, ask together: ** Phase 3: Name the Session -Decide on a name for this session type. +Decide on a name for this workflow. *Naming convention:* Action-oriented (verb form) -- Examples: "refactor", "inbox-zero", "create-session", "review-code" +- Examples: "refactor", "inbox-zero", "create-workflow", "review-code" - Why: Shorter, natural when saying "let's do a [name] session" -- Filename: =docs/sessions/[name].org= +- Filename: =docs/workflows/[name].org= ** Phase 4: Document the Session -Write the session file at =docs/sessions/[name].org= using this structure: +Write the session file at =docs/workflows/[name].org= using this structure: *** Recommended Structure 1. *Title and metadata* (=#+TITLE=, =#+AUTHOR=, =#+DATE=) @@ -221,14 +221,14 @@ Write the session file at =docs/sessions/[name].org= using this structure: ** Phase 5: Update Project State Update =NOTES.org=: -1. Add new session type to "Available Session Types" section +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/sessions/inbox-zero.org= +File: =docs/workflows/inbox-zero.org= Workflow for processing inbox to zero: 1. [Brief workflow summary] @@ -241,7 +241,7 @@ Created: 2025-11-01 *Critical step:* Use the session soon after creating it. -- Schedule the session type for immediate use +- Schedule the workflow for immediate use - Follow the documented workflow - Note what works well - Identify gaps or unclear areas @@ -339,7 +339,7 @@ We identified what was needed, collaborated on answers, and captured it in this * Conclusion -Creating session workflows is a meta-skill that improves all our collaboration. By formalizing how we work together, we: +Creating workflows is a meta-skill that improves all our collaboration. By formalizing how we work together, we: - Build shared vocabulary - Eliminate repeated explanations @@ -347,6 +347,6 @@ Creating session workflows is a meta-skill that improves all our collaboration. - Enable continuous improvement - Make our partnership more efficient -Each new session type we create adds to our collaborative toolkit and deepens our ability to work together effectively. +Each new workflow we create adds to our collaborative toolkit and deepens our ability to work together effectively. *Remember:* Sessions 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/sessions/emacs-inbox-zero.org b/docs/workflows/emacs-inbox-zero.org index 4e046eba..7040ddb7 100644 --- a/docs/sessions/emacs-inbox-zero.org +++ b/docs/workflows/emacs-inbox-zero.org @@ -4,7 +4,7 @@ * Overview -This session processes the Emacs Config Inbox to zero by filtering tasks through the V2MOM framework. Items either move to active V2MOM methods, get moved to someday-maybe, or get deleted. This weekly discipline prevents backlog buildup and ensures only strategic work gets done. +This workflow processes the Emacs Config Inbox to zero by filtering tasks through the V2MOM framework. Items either move to active V2MOM methods, get moved to someday-maybe, or get deleted. This weekly discipline prevents backlog buildup and ensures only strategic work gets done. * Problem We're Solving @@ -35,21 +35,21 @@ Without weekly inbox zero: * Exit Criteria -The session is complete when: +The workflow is complete when: - Zero todo items remain under the "* Emacs Config Inbox" heading in =~/.emacs.d/todo.org= - All items have been routed to: V2MOM methods, someday-maybe, or deleted - Can verify by checking the org heading (should be empty or show "0/0" in agenda) -*IMPORTANT:* We are ONLY processing items under the "* Emacs Config Inbox" heading. Items already organized under Method 1-6 headings have already been triaged and should NOT be touched during this session. +*IMPORTANT:* We are ONLY processing items under the "* Emacs Config Inbox" heading. Items already organized under Method 1-6 headings have already been triaged and should NOT be touched during this workflow. *Measurable validation:* - Open =todo.org= and navigate to "* Emacs Config Inbox" heading - Confirm no child tasks exist under this heading only - Bonus: Check that active todo count is < 20 items across entire V2MOM -* When to Use This Session +* When to Use This Workflow -Trigger this session when: +Trigger this workflow when: - It's Sunday and you haven't triaged this week - 7 days have passed since last triage (hard deadline) - "Emacs Config Inbox" has accumulated items @@ -220,13 +220,13 @@ When processing items that ARE aligned with V2MOM: * Living Document -This is a living document. After each emacs-inbox-zero session, consider: +This is a living document. After each emacs-inbox-zero workflow, consider: - Did the workflow make sense? - Were any steps unclear or unnecessary? - Did any new situations arise that need decision frameworks? - Did the 10-minute target work, or should it adjust? -Update this document with learnings to make future sessions smoother. +Update this document with learnings to make future workflows smoother. * Example Session Walkthrough @@ -310,13 +310,13 @@ Emacs inbox zero is not about getting through email or org-capture. It's about * * Living Document -This is a living document. After each emacs-inbox-zero session, consider: +This is a living document. After each emacs-inbox-zero workflow, consider: - Did the workflow make sense? - Were any steps unclear or unnecessary? - Did any new situations arise that need decision frameworks? - Did the 10-minute target work, or should it adjust? -Update this document with learnings to make future sessions smoother. +Update this document with learnings to make future workflows smoother. ** Updates and Learnings diff --git a/docs/sessions/refactor.org b/docs/workflows/refactor.org index 0cdb6841..2467ab99 100644 --- a/docs/sessions/refactor.org +++ b/docs/workflows/refactor.org @@ -1,12 +1,12 @@ -#+TITLE: Test-Driven Quality Engineering Session Process +#+TITLE: Test-Driven Quality Engineering Workflow #+AUTHOR: Craig Jennings & Claude #+DATE: 2025-11-01 * Overview -This document describes a comprehensive test-driven quality engineering session process applicable to any source code module. The session demonstrates systematic testing practices, refactoring for testability, bug discovery through tests, and decision-making processes when tests fail. +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. -* Session Goals +* Workflow Goals 1. Add comprehensive unit test coverage for testable functions in your module 2. Discover and fix bugs through systematic testing @@ -605,7 +605,7 @@ Note: =quality-engineer.org= evolves as we learn more quality best practices. Th * Conclusion -This session process demonstrates how systematic testing combined with refactoring for testability can: +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 |