1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
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=
|
