path: root/docs/NOTES.org

#+TITLE: 🚨 ACTIVE PROJECT - READ THIS FIRST 🚨
#+AUTHOR: Claude Code Session Notes
#+DATE: 2025-10-30

* 🗣️ IMPORTANT TERMINOLOGY

** "I want to do an X session with you"

When Craig says "I want to do an X session with you", this means:
- **CREATE a session definition** for doing X (meta-work)
- **NOT** "let's DO X right now" (the actual work)

This 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

** "Let's wrap it up" / "That's a wrap" / "Let's call it a wrap"

When Craig says any of these phrases, execute the wrap-up workflow:

1. **Write session notes** to docs/NOTES.org
   - Key decisions made
   - Work completed
   - Context needed for next session
   - Any pending issues or blockers

2. **Git commit and push all changes**
   - Check git status and diff
   - Create descriptive commit message
   - Include co-author attribution (Claude)
   - Push to ALL remotes (origin + github)

3. **Valediction**
   - Friendly goodbye summary
   - What was accomplished
   - What's ready for next session
   - Any important reminders

*Slash command:* `/wrap-it-up` triggers this same workflow

* 🤔 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 your preferences and I can add it exactly how you want it.

* 🔔 DESKTOP NOTIFICATIONS WORKFLOW

**IMPORTANT: How Claude notifies you when blocked**

When Claude needs your input on blocking questions, Claude will send a desktop notification 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 your 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:**
This allows you to context-switch to other work while Claude runs long tasks, and get notified ONLY when your input is truly needed to continue. You check back when convenient for status updates.

* 🧩 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

** 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 |
| 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)

** 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) - IN PROGRESS
2. ⏳ *TRIAGE todo.org* - Use V2MOM to ruthlessly cancel ~60% of tasks
3. ⏳ *EXECUTE TIER 1* - Ship quick wins (network check removal, Corfu, bug fixes)
4. ⏳ *BUILD OBSERVABILITY* - Create profiling infrastructure (TIER 2)
5. ⏳ *SYSTEMATIC EXECUTION* - Work through prioritized tasks one by one

** 📍 Where We Are Right Now
*Session Started:* 2025-10-30
*Current Step:* ✅ V2MOM COMPLETE - Ready for execution
*Time Committed:* ~2 sessions, V2MOM finished 2025-10-31
*Status:* V2MOM complete, ready to begin Method 1 execution

** 📄 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)
- Recognizes need for V2MOM framework
- Uses config daily for real work

*** Patterns to Address
1. *Research > Execution* - Has complete code for Corfu, difftastic, transcription workflow... still TODO
2. *Priority Inflation* - Too many [#A]/[#B] items, unclear what's actually urgent
3. *Incomplete Strategy* - V2MOM structure exists but sections are empty
4. *Hard to Say No* - [#C]/[#D] items should be CANCELLED but remain in list
5. *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 (IN PROGRESS)
2. ⏳ Triage todo.org using V2MOM as filter
3. ⏳ Execute quick wins: network check, Corfu migration, bug fixes
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)
- Fix missing functions (30 min)
- Corfu migration (2 hours)
- Mood-line switch (30 min)
- Bug fixes (1 hour)

*** 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)
- 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 V2MOM status** - If incomplete, continue there
3. **Reference issues.org** for detailed technical recommendations
4. **Reference todo.org** for items to triage
5. **Ask Craig:** "Where did we leave off? V2MOM? Triage? Execution?"

** 📞 Questions to Ask Craig Next Session

*IMMEDIATE (when resuming):*
- "Ready to continue V2MOM? We left off at Methods section."
- "How much time do you have?"

*FOR METHODS SECTION:*
Show Craig the draft list and ask:
- "Which methods do you already do consistently?"
- "Which do you want to do but don't yet?"
- "Am I missing any important methods?"

*AFTER V2MOM COMPLETE:*
- "Ready to triage todo.org using the V2MOM?"
- "Should we execute quick wins or continue systematic triage?"

** 🎯 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."

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)
2. Network check adds 1+ seconds to startup (technical debt)
3. Missing functions cause errors (cj/log-silently, cj/goto-git-gutter-diff-hunks)
4. Mail attachments workflow is awkward
5. No profiling infrastructure to measure performance

*** Items Craig Already Has Code For
These can be executed immediately - just paste and test:
- Transcription workflow (complete bash + elisp in todo.org:2-99)
- Difftastic integration (complete config in todo.org:1211-1223)
- Corfu migration (complete config in todo.org:1611-1639)

*** 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 (if exists)

** 🚀 Current Session Notes

*** 2025-10-31 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 This Session:*
- [[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
- [[file:SESSION-HANDOFF-ACTIVE-PROJECT.org][SESSION-HANDOFF-ACTIVE-PROJECT.org]] - This file

*Next Session Starts With:*
1. Continue Method 1 execution - 2 quick wins ready!
2. Fix cj/goto-git-gutter-diff-hunks (15 min)
3. Fix chime throw/catch bug (your package)
4. Fix go-ts-mode-map keybinding error

*** 2025-10-31 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, your package
   - 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

*Next Session (2025-11-01):*
**Two quick wins ready (15 min each):**
1. Fix cj/goto-git-gutter-diff-hunks (missing function)
2. Fix chime throw/catch bug (re-enable chime)

**Then continue Method 1:**
- Optimize org-agenda (THE BOTTLENECK - 30s → <5s target)
- Fix org-noter (daily pain)
- Fix video/audio recording
- Fix mail attachments
- Fix grammar checker

*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 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 (this file)
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