diff options
Diffstat (limited to 'docs/NOTES.org')
| -rw-r--r-- | docs/NOTES.org | 1306 |
1 files changed, 0 insertions, 1306 deletions
diff --git a/docs/NOTES.org b/docs/NOTES.org deleted file mode 100644 index 68439ef4..00000000 --- a/docs/NOTES.org +++ /dev/null @@ -1,1306 +0,0 @@ -#+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/workflows/create-v2mom.org -5. **Scan docs/workflows/ directory** for available workflows (see "Available Workflows" 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 - -** 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 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' 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: Do create-workflow workflow, then use immediately (validates new workflow) - -** "I want to create an X workflow" - Creating New Workflows - -β οΈ **IMPORTANT:** This is different from running an existing workflow! - -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-workflow process from docs/workflows/create-workflow.org - -*Examples:* -- "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 - -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 WORKFLOWS - -** create-workflow -File: [[file:workflows/create-workflow.org][docs/workflows/create-workflow.org]] - -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) -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: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. - -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: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. - -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 Workflow Document - -*Time:* ~30 minutes -*Status:* β
COMPLETE - Generic V2MOM workflow documented - -*What We Completed:* -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 - - 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/workflows/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 |