path: root/NOTES.org

#+TITLE: Project Notes for Future Sessions
#+AUTHOR: Claude (AI Assistant)
#+DATE: 2025-11-01

* Session Startup Protocol

When starting a new session with Craig:
1. Craig will point me to this NOTES.org file
2. Read this file completely to understand project context
3. **Scan =docs/sessions/= directory** for available session type filenames
   - Do NOT read full contents (they're long)
   - Just note the filenames to understand vocabulary
   - Example: =refactor.org= means "refactor session workflow"
4. When Craig says "let's do a [session-type] session":
   - **Check for exact match** in scanned filenames
   - **If exact match found:** Read =docs/sessions/[session-type].org= and guide Craig through that workflow
   - **If no exact match but similar word exists:** Ask for clarification
     - Example: User says "refactoring" but we have "refactor.org"
     - Ask: "Did you mean the 'refactor' session, or would you like to create a new 'refactoring' session?"
   - **If no match at all:** Offer to create it
     - Say: "I don't see a session type called '[session-type]' yet. Would you like to create it together using the create-session workflow?"
   - **If yes to create:** Do a create-session session to define the new type, then use it immediately (validation)

* Available Session Types

** refactor
File: =docs/sessions/refactor.org=

Workflow for comprehensive test-driven quality engineering:
1. Analyze test coverage for target file
2. Categorize functions by testability (easy/medium/hard)
3. Refactor for testability if needed (pure helpers + interactive wrappers)
4. Write ERT tests systematically (Normal/Boundary/Error categories)
5. Run tests and analyze failures
6. Decide: test bug or production bug?
7. Fix and verify
8. Repeat for all testable functions

Recent completion: =modules/music-config.el= - 103 tests, 3 bugs fixed

** create-session
File: =docs/sessions/create-session.org=

Meta-workflow for creating new session types:
1. Q&A discovery (Problem, Exit criteria, Approach, Principles)
2. Assess completeness and agreement
3. Name the session
4. Document using standard structure
5. Update NOTES.org
6. Validate by immediate execution

Defines how we formalize repetitive workflows into reusable, documented sessions.

Created: 2025-11-01

* Current Project State

** Completed Work

*** music-config.el Testing Session (2025-11-01)
- **Module:** =modules/music-config.el= (EMMS music player configuration)
- **Test Coverage:** 9 functions, 103 tests total
- **Bugs Fixed:** 3 (nil handling x2, URL regex escaping bug)
- **Session Document:** =docs/sessions/refactor.org=

Functions tested:
1. =cj/music--append-track-to-m3u-file= - 11 tests
2. =cj/music--valid-file-p= - 15 tests
3. =cj/music--valid-directory-p= - 13 tests
4. =cj/music--safe-filename= - 13 tests
5. =cj/music--m3u-file-tracks= - 15 tests (caught URL regex bug!)
6. =cj/music--get-m3u-files= - 7 tests
7. =cj/music--get-m3u-basenames= - 6 tests
8. =cj/music--collect-entries-recursive= - 12 tests
9. =cj/music--completion-table= - 12 tests

Functions skipped (EMMS buffer-dependent, hard to test):
- =cj/music--ensure-playlist-buffer=
- =cj/music--playlist-tracks=
- =cj/music--playlist-modified-p=
- =cj/music--assert-valid-playlist-file=

Test files location: =tests/test-music-config--*.el=

Key bug found: URL regex escaping in =cj/music--m3u-file-tracks= caused HTTP/HTTPS/MMS URLs to be treated as relative paths, corrupting playlist data.

** Work In Progress

(None currently - ready for next task)

** Backlog / Future Work

(To be added as Craig identifies next priorities)

* Project Structure Notes

** Test Organization
- One test file per function: =test-<module>-<function>.el=
- Rationale: Fast discovery when tests fail
- Test utilities: =tests/testutil-general.el=

** Test Categories
Every test file follows this structure:
- Normal Cases: Expected behavior under typical conditions
- Boundary Cases: Edge conditions, limits, unusual inputs
- Error Cases: Failure scenarios, invalid inputs

** Quality Engineering Reference
See =ai-prompts/quality-engineer.org= for comprehensive guidelines.
Note: This file evolves as we learn best practices.

* Session History

** 2025-11-01: music-config.el Refactor Session
- Added comprehensive test coverage to music configuration
- Found and fixed 3 bugs
- Created refactor session workflow document
- Established session type pattern for future work

** 2025-11-01: Create-Session Meta-Workflow
- Designed the process for creating new session types
- Used recursive application: created create-session using itself
- Defined four-question Q&A framework
- Established seven core principles for session creation
- Documented in =docs/sessions/create-session.org=

** 2025-11-03: Method 2 Quick Wins Session
- Completed 6 tasks across Methods 1, 2, and 3
- Focus: Low-risk improvements aligned with V2MOM Methods

*** Key Technical Learnings

**** Difftastic vs Ediff - Complementary Tools
- **Difftastic**: Read-only structural diffs for git (language-aware)
- **Ediff**: Interactive side-by-side editing for buffer comparison
- **Discovery**: User had ediff at C-c D but C-; b D used basic diff
- **Solution**: Hybrid approach - ediff for buffers, difftastic for git
- **Lesson**: Don't assume one replaces the other; they serve different purposes

**** Org-mode Visual Emphasis
- =org-fontify-emphasized-text= controls bold/italic rendering
- =org-hide-emphasis-markers= hides markup characters (* / _)
- =org-appear= shows markers only when cursor is on emphasized text
- **Pattern**: Hide markers globally, reveal contextually with org-appear

*** User Workflow Preferences

**** Task Selection Strategy
- User prefers quick wins when energy is lower
- Appreciates effort estimates BEFORE committing to work
- Will defer mission-critical changes (e.g., Company → Corfu)
- Quote: "now I'm hungry for more" after successful quick wins

**** Communication Patterns
- User sometimes needs clarification iterations ("whoops. I wasn't clear again")
- Always confirm understanding before major changes
- User values knowing keybindings for new features
- Appreciates when tasks are already complete (just need verification)

**** V2MOM Task Management
- Tasks organized by 6 Methods with progress tracking (e.g., 7/13, 3/5)
- User maintains detailed completion notes in todo.org
- Each task includes context, rationale, and completion details
- Weekly triage scheduled to keep active todos < 20

*** Development Patterns

**** Git Workflow
- Always push to BOTH remotes: origin (cjennings.net) AND github
- Commit messages include Claude Code attribution
- User reviews git status and diffs before committing

**** Configuration Management
- User runs Emacs 30.2 with use-package
- Prefers editing existing files over creating new ones
- Values code reduction (mood-line: -40 lines, ediff upgrade: -12 lines)

*** Tasks Completed
1. Switched doom-modeline → mood-line (Method 2)
2. Removed deprecated tree-sitter package (Method 2)
3. Fixed cj/goto-git-gutter-diff-hunks void-function (Method 1)
4. Cleaned up go-ts-mode-map declarations (Method 1)
5. Upgraded buffer diff to ediff + added difftastic for git (Method 3)
6. Added org-appear and enabled emphasis rendering (Method 2)