#+TITLE: Emacs Configuration V2MOM #+AUTHOR: Craig Jennings #+DATE: 2025-10-30 #+FILETAGS: :strategy:planning:v2mom: * What is V2MOM? V2MOM is a strategic framework used to clarify goals and priorities: - *Vision:* What do you want to achieve? - *Values:* What principles guide decisions? - *Methods:* How will you achieve the vision? - *Obstacles:* What's in your way? - *Metrics:* How will you measure success? This document provides strategic clarity for prioritizing Emacs configuration work. * Vision Your personal ideal Emacs configuration allows you to work at the speed of your own thought. It's stable and never needs edge-case bug fixing. The functionality covers your workflow such that you can work all day in Emacs for any of the following task areas: - Programming in any language, including emacs-lisp, common-lisp, scheme, golang, and c - Reading ebooks, including marginalia handling - Listening to music, including playlist management - Listening to podcasts, including saving episodes - Task organizing and planning - Calendaring, including syncing with google calendar - Alerting and notifications on tasks and calendar events - Timer/stopwatch functionality, including pomodoro presets - Audio and desktop recording - Memorization drills - Email, including email-to-task integration - Messaging, i.e., IRC - File-management, including extensive integration, and DWM scratchpad integration outside Emacs - Shell commands, leveraging vterm and eshell with custom methods, and DWM scratchpad integration outside Emacs Anytime you make a change in the config, you have unit tests to tell you quickly if the change created unexpected issues. You have a test-runner that integrates with your workflow. * Values also see: file:values-comparison.org ** Intuitive *Definition:* Intuition comes from muscle memory, clear mnemonics, and just-in-time discovery that reinforces learning without blocking productivity. *** Keybindings Build Intuition Through Layers 1. *Muscle memory first* - C-; on home row becomes automatic habit 2. *Mnemonics provide "aha!" moments* - C-c **m** for mail creates dopamine hits that cement permanent memory 3. *Which-key teaches through active recall* - Appears after you try (not before), forcing attempt without wasting time The timing matters: which-key's delay is calibrated so you're challenged to remember, but not blocked from working. *** What Breaks Intuition - *Physically awkward keybindings* - C-c 1 z C-c f requires hand contortions and offers no mnemonic - *Syntax overhead* - Parentheses tracking steals time from real learning (logic bugs, architecture understanding) - *Poor architecture* - Common actions (like "save all attachments") shouldn't require architectural archaeology *** Code Reads "Like a Newspaper" - Each use-package declaration is a *story* (topic = package) - Configuration settings are *facts* (what it does, how it behaves) - Clear variable/method naming (yours + maintainers) makes code read like English - Accessible to intermediate elisp readers without deep archaeology *** Principle *Intuition is earned through repeated success, not instant magic.* The config should make success easy to achieve and memorable when it happens. ** Fast *Definition:* Fast means staying in flow. Startup and org-agenda must not make me wait. Everything else is already acceptable. *** Performance Targets *Startup Time:* - Current: ~3.8 seconds (real clock time, not Emacs-reported) - Target: ~1 second (aspirational, may not be realistic given package count) - Comfortable: ~2 seconds (±) *Measurement:* #+begin_src bash time emacs --eval '(save-buffers-kill-emacs)' # Real startup time #+end_src *Note:* Emacs-reported time is inaccurate. Messages buffer continues populating and Emacs remains unresponsive after "loaded" message appears. *** Critical Performance Issues (Must Fix) 1. *Emacs startup* - 3.8s is too slow - Network check adds 1+ seconds (DELETE THIS) - Eager loading vs lazy loading 2. *Opening org-agenda for first time* - **THE BOTTLENECK** - "Takes forever and a full work day" - Likely: recursive directory scan, no caching, too many files - Solution: Profile first (build debug-profiling.el), then optimize *** Must Be Instant (Flow-Critical) - Keybinding response - Changing projects in projectile (already good ✓) - Opening large org files (already good ✓, except malformed files with stray "*"s) - Buffer/window operations *** Can Take 1-2 Seconds (Acceptable) - *Mail sync* - Consider putting on timer instead of manual trigger - *Calibredb* (PDFs/Epubs) - Known solution: shrink inventory to <1k books or contribute optimizations - *Org-noter* opening PDFs/Epubs - Needs reliability + reasonable speed - *Looking up org-noter notes* - Should be easy to pull into other documents - *Initial file indexing* (projectile, etc.) *** Disabled Due to Performance (Need Solutions) - *Grammar checker* - Installed but turned off because it slows everything down - No task exists to fix this yet - Breaks concentration when writing - *Bibliography management* - Don't know how to do in Emacs - Worried about broken/slow tools breaking writing flow - Need solution that "just works" *** Principle *Speed is about flow, not milliseconds.* Startup and agenda are flow-breakers. Everything else is fine. Don't optimize what doesn't hurt. ** Simple *Definition:* Simple means clear, maintainable code following production software practices. Simplicity is a discipline that produces reliability. Config is production software - treat it as such. *** What Makes Code Simple 1. *Clear naming* - Variables and functions say what they do 2. *Small functions* - Easy to understand, test, and modify 3. *Good comments* - NOT obvious comments ("cat with post-it note saying 'cat'") *Good comments:* - Navigation markers for long files - Explain complex/non-obvious logic - Document unobvious impacts of settings - Answer "why" not "what" *Bad comments:* #+begin_src emacs-lisp ;; declare a variable (defvar variable 10) #+end_src *** Abstractions and Magic - *Abstractions are fine* if they serve a purpose - *Macros are irritating* when unnecessary, but acceptable when warranted - *Magic is acceptable* if it's reliable and you can build a mental model *Principle:* "I want to understand every line of what my config does, or at least have a decent mental model of how it probably works. Never use a tool you can't fully trust." *** Package Count Package count itself isn't a concern. Quality and maintainability matter. *Concerns:* - More packages = more potential breakage - Need ability to roll back when packages break (localrepo for package snapshots) - Maintenance burden is real, but manageable with good practices *Not concerned about:* - Absolute number of packages - Startup time impact (if lazy-loaded properly) - Cognitive load (if organized well) *** Config IS Production Software *Key insight:* "My Emacs config IS production software. I use it more than probably every other application combined. The impact when it's broken can crush my productivity." This means: - *Apply production practices:* Testing, modularity, documentation, version control - *Plan for failure:* Rollback capability (localrepo), error handling, graceful degradation - *Modular design:* Extract custom code into packages when it grows - *Long-term maintenance:* Architecture matters, technical debt has real cost *** Personal Software Platform "I see my config as a personal software project built on the software platform called Emacs. Emacs has taught me a great deal about how to build software platforms well." *Implications:* - Config follows software engineering principles - Custom functionality becomes packages (chime, org-msg, potentially jumper) - Good architecture enables evolution - Quality matters because uptime matters *** Why Simplicity Matters When config breaks, productivity is crushed. The discipline of simplicity produces reliability: - Simple code is easier to fix when it breaks - Simple architecture enables graceful degradation - Simple practices (testing, rollback) provide safety nets - Simple means never using tools you can't trust *** Principle *Simple means maintainable production software, not minimal or primitive.* Complexity is acceptable when it serves the vision and can be understood or trusted. **Simplicity is the practice that produces reliability as an outcome.** ** Summary: Three Core Values 1. *Intuitive* - Muscle memory, mnemonics, just-in-time discovery. Code reads like a newspaper. 2. *Fast* - Startup and org-agenda must not break flow. Everything else is acceptable. 3. *Simple* - Clear, maintainable, production-quality code. Simplicity produces reliability. * Methods ** Method 1: Make Using Emacs Frictionless Emacs should never make you wait or break your concentration. This method eliminates daily friction points that disrupt flow. Every item here either removes a bottleneck (startup delay, org-agenda slowness), fixes something broken (org-noter, recording, mail attachments), or adds missing functionality you reach for weekly (diff-buffer-with-file). When Method 1 is complete, Emacs starts fast, org-agenda opens instantly, all core workflows work reliably, and nothing makes you context-switch to debug config during work. *Concrete actions:* - Remove network check from startup (saves 1+ seconds every launch) - Optimize org-agenda performance using built-in profiler (eliminate "forever and a full work day" rebuild time) - Fix [[https://github.com/weirdNox/org-noter][org-noter]] (reading/annotation workflow currently "so painful") - Fix video/audio recording module (use it constantly, just broke) - Fix mail attachment workflow (currently awkward) - Implement cj/diff-buffer-with-file (compare buffer with saved version - weekly need) - Fix cj/goto-git-gutter-diff-hunks (missing function causing errors) - Fix grammar checker performance (currently disabled because it breaks flow) ** Method 2: Stop Problems Before They Appear A stable config comes from proactive maintenance, not reactive fixes. This method replaces aging packages with modern, actively-maintained alternatives before they break. It removes deprecated dependencies and adopts better-designed tools that align with Emacs' evolution. When Method 2 is complete, the config uses current best practices, has no deprecated packages lurking as time bombs, and benefits from simpler, more maintainable completion infrastructure. *Concrete actions:* - Migrate from Company to [[https://github.com/minad/corfu][Corfu]] (simpler, modern completion framework - complete config already in todo.org) - Switch to [[https://gitlab.com/jessieh/mood-line][mood-line]] (lighter modeline, already researched) - Remove deprecated tree-sitter package and rely on [[https://github.com/renzmann/treesit-auto][treesit-auto]] (already installed, leverages Emacs 29+ built-in treesit) - Add [[https://github.com/awth13/org-appear][org-appear]] (show emphasis markers only when point is on them - cleaner org files) - Integrate [[https://github.com/radian-software/prescient.el][prescient]] with Corfu (frequency/recency-based smart sorting - already using with vertico) ** Method 3: Make *Fixing* Emacs Frictionless You can't fix what you can't measure, and you can't trust what you can't test. This method builds observability and testing infrastructure that makes future maintenance systematic instead of guesswork. With proper profiling, testing, and diffing tools in place, debugging becomes fast and confident. When Method 3 is complete, you can profile any performance issue in seconds, write integration tests for complex workflows, roll back broken packages instantly, and review config changes with semantic understanding. *Concrete actions:* - Build debug-profiling.el module and develop skills using it (reusable profiling infrastructure for any future performance work) - Integrate [[https://github.com/jorgenschaefer/emacs-buttercup][Buttercup]] (behavior-driven integration tests for complex config workflows) - Build localrepo out (package snapshot system for repeatable installs and safe rollbacks) - Integrate [[https://github.com/Wilfred/difftastic][difftastic]] (structural diffs that show semantic changes, not just line changes) ** Method 4: Contribute to the Emacs Ecosystem Maintaining packages (chime, org-msg, wttrin) means being a good steward of code others depend on. This method establishes professional package development practices: automated linting, CI testing, and coverage reporting. These tools catch issues before users do and make MELPA submissions smooth. When Method 4 is complete, every package you maintain has automated quality checks, measurable test coverage, and CI that validates changes before they ship. You contribute back to the community with confidence. *Concrete actions:* - Set up [[https://github.com/purcell/package-lint][package-lint]] for elisp linting (catch packaging issues and style violations automatically) - Set up [[https://github.com/riscy/melpazoid][melpazoid]] CI (validates packages meet MELPA standards before submission) - Set up [[https://github.com/leotaku/elisp-check][elisp-check]] GitHub Action (zero-config CI for Emacs packages) - Integrate [[https://github.com/undercover-el/undercover.el][undercover.el]] (measure and track test coverage over time) ** Method 5: Be Kind To Your Future Self With Emacs stable and maintainable, it's time to add features that expand what's possible. This method builds workflows you'll use repeatedly: transcribing audio for notes and creating presentations directly from org-mode. These aren't fixes—they're investments in future capability. When Method 5 is complete, you can transcribe recordings without leaving Emacs and generate beautiful reveal.js presentations from org files. Future you will thank present you for shipping these. *Concrete actions:* - Add transcription workflow (complete code already in todo.org:2-99 - need today and recurring) - Implement [[https://github.com/yjwen/org-reveal][org-reveal]] presentation workflow (create reveal.js slides from org-mode) ** Method 6: Develop Disciplined Engineering Practices The best infrastructure won't help without disciplined habits. This method builds the practices that make all other methods sustainable: knowing what matters most, shipping over researching, measuring before optimizing. These are skills to develop, not tasks to complete—they evolve throughout the entire V2MOM, and I become a better engineer overall. *Concrete practices to develop:* - *Ruthless prioritization* - Always do the most important thing. Use V2MOM as filter. If it doesn't serve the vision, cancel it. - *Weekly triage* - Review todos every Sunday (30 min). Items sitting >1 week get shipped or killed. Prevents backlog rot. Keep <20 active items. - *Measure metrics* - Define success criteria before starting work. Quantify outcomes so you know when you're done (startup time, test coverage, todo count). - *Profile-before-optimize* - Never guess what's slow. Run profiler, identify hotspot, THEN fix. Avoids wasting time optimizing things that don't matter. - *Ship-over-research* - Execute existing specs before exploring new ones. Time-box research (30 min → decide: ship or kill). Monthly retrospective on research:shipped ratio. - *Incremental execution* - Ship small, test, iterate. Keep config working at every step. Avoid big-bang failures, integration hell, and sunk cost traps. *How to measure success:* - *Ruthless prioritization* → todo.org stays under 20 active items, cancelled:completed ratio shows I'm saying "no" - *Weekly triage* → At least once a week by Sunday, no longer than 7 days between triage (tracked in calendar) - *Measure metrics* → Every task has defined success criteria before starting, can show actual tracked metrics (startup logs, coverage reports) - *Profile-before-optimize* → Every performance fix has profiler output proving the bottleneck, zero "I think this is slow" guesses - *Ship-over-research* → Research:shipped ratio improves monthly (>1:1), complete code in todo.org ships within 1 week - *Incremental execution* → Config never broken for >2 days, git commits are small and frequent, can roll back any change cleanly * Obstacles 1. *Building and researching is more fun than fixing.* But if I don't change this, everything will be broken. 2. *I get irritated with myself when making mistakes.* But mistakes are how people learn. If I let irritation drive me to give up, I'll never develop the skills these methods require. 3. *It's hard for me to say "no".* But if I don't say "no" to something, I'll never achieve anything. The only way to make saying "no" easier is to do it repeatedly. 4. *I can be a perfectionist who wants something just right before I move on.* But perfect is the enemy of shipped. I need to learn that good enough is better than perfect, and iteration beats perfection. 5. *I don't always have the time for all day coding sessions.* Breaking the work into increments will help me deliver the long term value anyway. Be the tortoise, not the rabbit. 6. *New disciplines are hard to sustain.* Weekly triage, measuring metrics, and profiling-before-optimizing are new habits. The first few weeks I'll be tempted to skip them when busy. But if I don't practice them consistently, they'll never become automatic, and I'll fall back into old patterns. * Metrics You can't improve what you don't measure. These metrics provide objective evidence that the Methods are working and the Vision is becoming reality. Track them weekly during triage to catch regressions early and celebrate progress. ** Performance Metrics: - *Startup time: < 3 seconds* (currently ~6.2s) - Measured with =time emacs --eval '(save-buffers-kill-emacs)'= - *Org-agenda rebuild time: < 5 seconds* (currently 30+ seconds) - Measured with profiler during first daily open ** Maintenance Discipline Metrics: - *Active todo count: < 20 items* (currently ~50+) - Counted during weekly triage - *Weekly triage consistency: At least once a week by Sunday, no longer than 7 days between triage* - Tracked in calendar - *Research:shipped ratio: > 1:1* - Can't research next thing until current thing is implemented. Track monthly. - *Config uptime: Never broken > 2 days* - Allows breathing room for emergencies/travel ** Package Quality Metrics (chime, org-msg, wttrin): - *Test coverage: > 70% and all code not covered justifiable* - Uncovered code is 100% risk. Better not be the most-used parts! * How to Use This V2MOM ** For Decision Making When considering a new task, package, or feature: 1. Does it serve the *Vision*? 2. Does it align with the *Values*? 3. Is it addressed in the *Methods*? 4. Does it overcome an *Obstacle*? 5. Does it improve a *Metric*? If the answer is "no" to all five → CANCEL the task. ** For Triage When reviewing todo.org: - Tasks aligned with V2MOM → Keep and prioritize - Tasks not aligned with V2MOM → CANCEL - Tasks that are interesting but not important → CANCEL - Tasks with complete code already → Execute immediately ** For Weekly Review Every Sunday (30 minutes): 1. Review metrics - Are they improving? 2. Review obstacles - Any new ones? Any resolved? 3. Review active todos - Still aligned with V2MOM? 4. Cancel stale/misaligned tasks 5. Plan next week's focus * Completion Status - [X] Vision - Complete (kept from original todo.org) - [X] Values - Complete (Intuitive, Fast, Simple) - [X] Methods - Complete (6 methods with aspirational bodies and concrete actions) - [X] Obstacles - Complete (6 honest obstacles with real stakes) - [X] Metrics - Complete (Performance, Discipline, and Quality metrics defined) *Last Updated:* 2025-10-31 (Session 2) *Status:* ✅ V2MOM COMPLETE - Ready to use for decision making and weekly triage