diff options
| -rw-r--r-- | NOTES.org | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/NOTES.org b/NOTES.org new file mode 100644 index 00000000..d048710f --- /dev/null +++ b/NOTES.org @@ -0,0 +1,125 @@ +#+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= |