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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
|
# Release Note Generator
Generate comprehensive release documentation from recent commits, producing two distinct outputs: a customer-facing release note and a technical engineering note.
## Interactive Workflow
When this command is triggered, **DO NOT** immediately generate release notes. Instead, present the user with two options:
### Mode Selection Prompt
Present this to the user:
```text
I can generate release notes in two ways:
**Mode 1: By Commit Count**
Generate notes for the last N commits (specify number or use default 10)
→ Quick generation when you know the commit count
**Mode 2: By Commit Hash Range (i.e. Last 24/48/72 Hours)**
Show all commits from the last 24/48/72 hours, then you select a starting commit
→ Precise control when you want to review recent commits first
Which mode would you like?
1. Commit count (provide number or use default)
2. Commit hash selection (show last 24/48/72 hours)
You can also provide an argument directly: /create-release-note 20
```
---
## Mode 1: By Commit Count
### Usage
```bash
/create-release-note # Triggers mode selection
/create-release-note 20 # Directly uses Mode 1 with 20 commits
/create-release-note 50 # Directly uses Mode 1 with 50 commits
```
### Process
1. If `$ARGUMENTS` is provided, use it as commit count
2. If no `$ARGUMENTS`, ask user for commit count or default to 10
3. Set: `COMMIT_COUNT="${ARGUMENTS:-10}"`
4. Generate release notes immediately
---
## Mode 2: By Commit Hash Range
### Workflow
When user selects Mode 2, follow this process:
### Step 1: Retrieve Last 24 Hours of Commits
```bash
git log --since="24 hours ago" --pretty=format:"%h|%ai|%an|%s" --reverse
```
### Step 2: Present Commits to User
Format the output as a numbered list for easy selection:
```text
Commits from the last 24 hours (oldest to newest):
1. a3f7e821 | 2025-10-15 09:23:45 | Alice Smith | Add OAuth provider configuration
2. b4c8f932 | 2025-10-15 10:15:22 | Bob Jones | Implement token refresh flow
3. c5d9e043 | 2025-10-15 11:42:18 | Alice Smith | Add provider UI components
4. d6e1f154 | 2025-10-15 13:08:33 | Carol White | Database connection pooling
5. e7f2g265 | 2025-10-15 14:55:47 | Alice Smith | Query optimization middleware
6. f8g3h376 | 2025-10-15 16:20:12 | Bob Jones | Dark mode CSS variables
7. g9h4i487 | 2025-10-15 17:10:55 | Carol White | Theme switching logic
8. h0i5j598 | 2025-10-16 08:45:29 | Alice Smith | Error boundary implementation
Please provide the starting commit hash (8 characters) or number.
Release notes will be generated from your selection to HEAD (most recent).
Example: "a3f7e821" or "1" will generate notes for commits 1-8
Example: "d6e1f154" or "4" will generate notes for commits 4-8
```
### Step 3: Generate Notes from Selected Commit
Once user provides a commit hash or number:
```bash
# If user provided a number, extract the corresponding hash
SELECTED_HASH="<hash from user input>"
# Generate notes from selected commit to HEAD
git log ${SELECTED_HASH}..HEAD --stat --oneline
git log ${SELECTED_HASH}..HEAD --pretty=format:"%H|%s|%an|%ad" --date=short
```
**Important:** The range `${SELECTED_HASH}..HEAD` means "from the commit AFTER the selected hash to HEAD". If you want to include the selected commit itself, use `${SELECTED_HASH}^..HEAD` or count commits with `--ancestry-path`.
### Step 4: Confirm Range
Before generating, confirm with user:
```text
Generating release notes for N commits:
From: <hash> - <commit message>
To: <HEAD hash> - <commit message>
Proceeding with generation...
```
---
## Core Requirements
### 1. Commit Analysis
**Determine commit source:**
- **Mode 1**: `COMMIT_COUNT="${ARGUMENTS:-10}"` → Use `git log -${COMMIT_COUNT}`
- **Mode 2**: User-selected hash → Use `git log ${SELECTED_HASH}..HEAD`
**Retrieve commits:**
- Use `git log <range> --stat --oneline`
- Use `git log <range> --pretty=format:"%H|%s|%an|%ad" --date=short`
- Analyze file changes to understand scope and impact
- Group related commits by feature/subsystem
- Identify major themes and primary focus areas
### 2. Traceability
- Every claim MUST be traceable to specific commit SHAs
- Reference actual files changed (e.g., src/config.ts, lib/utils.py)
- Use 8-character SHA prefixes for engineering notes (e.g., 0ca46028)
- Verify all technical details against actual commit content
### 3. Length Constraints
- Each section: ≤500 words (strict maximum)
- Aim for 150-180 words for optimal readability
- Prioritize most impactful changes if space constrained
---
## Section 1: Release Note (Customer-Facing)
### Purpose
Communicate value to end users without requiring deep technical knowledge. Audience varies by project type (system administrators, developers, product users, etc.).
### Tone and Style
- **Friendly & Clear**: Write as if explaining to a competent user of the software
- **Value-Focused**: Emphasize benefits and capabilities, not implementation details
- **Confident**: Use active voice and definitive statements
- **Professional**: Avoid jargon, explain acronyms on first use
- **Contextual**: Adapt language to the project type (infrastructure, web app, library, tool, etc.)
### Content Guidelines
**Include:**
- Major new features or functionality
- User-visible improvements
- Performance enhancements
- Security updates
- Dependency/component version upgrades
- Compatibility improvements
- Bug fixes affecting user experience
**Exclude:**
- Internal refactoring (unless it improves performance)
- Code organization changes
- Developer-only tooling
- Commit SHAs or file paths
- Implementation details
- Internal API changes (unless user-facing library)
### Structure Template
```markdown
## Release Note (Customer-Facing)
**[Project Name] [Version] - [Descriptive Title]**
[Opening paragraph: 1-2 sentences describing the primary focus/theme]
**Key improvements:**
- [Feature/improvement 1: benefit-focused description]
- [Feature/improvement 2: benefit-focused description]
- [Feature/improvement 3: benefit-focused description]
- [Feature/improvement 4: benefit-focused description]
- [etc.]
[Closing paragraph: 1-2 sentences about overall impact and use cases]
```
### Style Examples
✅ **Good (Customer-Facing):**
> "Enhanced authentication system with support for OAuth 2.0 and SAML providers"
❌ **Bad (Too Technical):**
> "Refactored src/auth/oauth.ts to implement RFC 6749 token refresh flow"
✅ **Good (Value-Focused):**
> "Improved database query performance, reducing page load times by 40%"
❌ **Bad (Implementation Details):**
> "Added connection pooling in db/connection.ts with configurable pool size"
✅ **Good (User Benefit):**
> "Added dark mode support with automatic system theme detection"
❌ **Bad (Technical Detail):**
> "Implemented CSS variables in styles/theme.css for runtime theme switching"
---
## Section 2: Engineering Note (Technical)
### Purpose
Provide developers/maintainers with precise technical details for code review, debugging, and future reference.
### Tone and Style
- **Precise & Technical**: Use exact terminology and technical language
- **Reference-Heavy**: Include SHAs, file paths, function names
- **Concise**: Information density over narrative
- **Structured**: Group by subsystem or feature area
### Content Guidelines
**Include:**
- 8-character SHA prefixes for every commit or commit group
- Exact file paths (src/components/App.tsx, lib/db/connection.py)
- Specific technical changes (version numbers, configuration changes)
- Module/function names when relevant
- Code organization changes
- All commits (even minor refactoring)
- Breaking changes or API modifications
**Structure:**
- Group related commits by subsystem
- List most significant changes first
- Use single-sentence summaries per commit/group
- Format: `SHA: description (file references)`
### Structure Template
```markdown
## Engineering Note (Technical)
**[Primary Focus/Theme]**
[Opening sentence: describe the main technical objective]
**[Subsystem/Feature Area 1]:**
- SHA1: brief technical description (file1, file2)
- SHA2: brief technical description (file3)
- SHA3, SHA4: grouped description (file4, file5, file6)
**[Subsystem/Feature Area 2]:**
- SHA5: brief technical description (file7, file8)
- SHA6: brief technical description (file9)
**[Subsystem/Feature Area 3]:**
- SHA7, SHA8, SHA9: grouped description (files10-15)
- SHA10: brief technical description (file16)
[Optional: List number of files affected if significant]
```
### Style Examples
✅ **Good (Technical):**
> "a3f7e821: OAuth 2.0 token refresh implementation in src/auth/oauth.ts, src/auth/tokens.ts"
❌ **Bad (Too Vague):**
> "Updated authentication system for better token handling"
✅ **Good (Grouped):**
> "c4d8a123, e5f9b234, a1c2d345: Database connection pooling (src/db/pool.ts, src/db/config.ts)"
❌ **Bad (No References):**
> "Fixed database connection issues"
✅ **Good (Precise):**
> "7b8c9d01: Upgrade react from 18.2.0 to 18.3.1 (package.json)"
❌ **Bad (Missing Context):**
> "Updated React dependency"
---
## Formatting Standards
### Markdown Requirements
- Use `##` for main section headers
- Use `**bold**` for subsection headers and project titles
- Use `-` for bullet lists
- Use `` `backticks` `` for file paths, commands, version numbers
- Use 8-character SHA prefixes: `0ca46028` not `0ca46028b9fa62bb995e41133036c9f0d6ac9fef`
### Horizontal Separator
Use `---` (three hyphens) to separate the two sections for visual clarity.
### Version Numbers
Format as: `version X.Y` or `version X.Y.Z` (e.g., "React 18.3", "Python 3.12.1")
### File Paths
- Use actual paths from repository: `src/components/App.tsx` not "main component"
- Multiple files: `(file1, file2, file3)` or `(files1-10)` for ranges
- Use project-appropriate path conventions (src/, lib/, app/, pkg/, etc.)
---
## Commit Grouping Strategy
### Group When
- Multiple commits modify the same file/subsystem
- Commits represent incremental work on same feature
- Space constraints require consolidation
- Related bug fixes or improvements
### Example Grouping
```text
Individual:
- c4d8a123: Add connection pool configuration
- e5f9b234: Implement pool lifecycle management
- a1c2d345: Add connection pool metrics
Grouped:
- c4d8a123, e5f9b234, a1c2d345: Database connection pooling (src/db/pool.ts, src/db/config.ts, src/db/metrics.ts)
```
### Don't Group
- Unrelated commits (different subsystems)
- Major features (deserve individual mention)
- Commits with significantly different file scopes
- Breaking changes (always call out separately)
---
## Quality Checklist
Before finalizing, verify:
- [ ] Mode selection presented (unless $ARGUMENTS provided)
- [ ] Commit range correctly determined (Mode 1: count, Mode 2: hash range)
- [ ] User confirmed commit range before generation
- [ ] Both sections ≤500 words
- [ ] Every claim traceable to specific commit(s)
- [ ] Customer note has no SHAs or file paths
- [ ] Engineering note has SHAs for all commits/groups
- [ ] File paths are accurate and complete
- [ ] Tone appropriate for each audience
- [ ] Markdown formatting consistent
- [ ] Version numbers accurate
- [ ] No typos or grammatical errors
- [ ] Primary focus clearly communicated in both sections
- [ ] Most significant changes prioritized first
- [ ] Language adapted to project type (not overly specific to one domain)
---
## Edge Cases
### If Fewer Commits Than Requested
- Generate notes for all available commits
- Note this at the beginning: "Release covering [N] commits"
- Example: "Release covering 7 commits (requested 10)"
### If No Commits in Last 24 Hours (Mode 2)
- Inform user: "No commits found in the last 24 hours"
- Offer alternatives:
- Extend time range (48 hours, 7 days)
- Switch to Mode 1 (commit count)
- Manual hash range specification
### If Mostly Minor Changes
- Group aggressively by subsystem
- Lead with most significant changes
- Note: "Maintenance release with incremental improvements"
### If Single Major Feature Dominates
- Lead with that feature in both sections
- Group supporting commits under that theme
- Structure engineering note by feature components
### If Merge Commits Present
- Skip merge commits themselves
- Include the actual changes from merged branches
- Focus on functional changes, not merge mechanics
### If No Version Tag Available
- Use branch name or generic title: "Development Updates" or "Recent Improvements"
- Focus on change summary rather than version-specific language
### If User Provides Invalid Commit Hash
- Validate hash exists: `git cat-file -t ${HASH} 2>/dev/null`
- If invalid, show error and re-present commit list
- Suggest checking the hash or selecting by number instead
---
## Adapting to Project Types
### Infrastructure/DevOps Projects
- Focus on: deployment improvements, configuration management, monitoring, reliability
- Audience: sysadmins, DevOps engineers, SREs
### Web Applications
- Focus on: features, UX improvements, performance, security
- Audience: product users, stakeholders, QA teams
### Libraries/Frameworks
- Focus on: API changes, new capabilities, breaking changes, migration guides
- Audience: developers using the library
### CLI Tools
- Focus on: command changes, new options, output improvements, bug fixes
- Audience: command-line users, automation engineers
### Internal Tools
- Focus on: workflow improvements, bug fixes, integration updates
- Audience: team members, internal stakeholders
---
## Example Output Structure
```markdown
## Release Note (Customer-Facing)
**MyProject v2.4.0 - Authentication & Performance Update**
This release introduces comprehensive OAuth 2.0 support and significant performance improvements across the application.
**Key improvements:**
- OAuth 2.0 authentication with support for Google, GitHub, and Microsoft providers
- Improved database query performance with connection pooling, reducing response times by 40%
- Added dark mode support with automatic system theme detection
- Enhanced error handling and user feedback throughout the interface
- Security updates for dependency vulnerabilities
These enhancements provide a more secure, performant, and user-friendly experience across all application features.
---
## Engineering Note (Technical)
**OAuth 2.0 Integration and Performance Optimization**
Primary focus: authentication modernization and database performance improvements.
**Authentication System:**
- a3f7e821: OAuth 2.0 provider implementation (src/auth/oauth.ts, src/auth/providers/)
- b4c8f932: Token refresh flow and session management (src/auth/tokens.ts)
- c5d9e043: Provider registration UI components (src/components/auth/OAuthProviders.tsx)
**Performance Optimization:**
- d6e1f154: Database connection pooling (src/db/pool.ts, src/db/config.ts)
- e7f2g265: Query optimization middleware (src/db/middleware.ts)
**UI/UX Improvements:**
- f8g3h376, g9h4i487: Dark mode CSS variables and theme switching (src/styles/theme.css, src/components/ThemeProvider.tsx)
- h0i5j598: Error boundary implementation (src/components/ErrorBoundary.tsx)
**Security:**
- i1j6k609: Dependency updates for security patches (package.json, yarn.lock)
```
---
## Implementation Workflow
When executing this command, Claude should:
### If $ARGUMENTS Provided
1. Use `COMMIT_COUNT="${ARGUMENTS}"`
2. Run git commands with the determined count
3. Generate both sections immediately
### If No $ARGUMENTS
1. Present mode selection prompt to user
2. Wait for user response
**If user selects Mode 1:**
3. Ask for commit count or use default 10
4. Generate notes immediately
**If user selects Mode 2:**
3. Retrieve commits from last 24 hours
4. Present formatted list with numbers and hashes
5. Wait for user to provide hash or number
6. Validate selection
7. Confirm commit range
8. Generate notes from selected commit to HEAD
### Final Steps (Both Modes)
1. Analyze commits thoroughly
2. Generate both sections following all guidelines
3. Verify against quality checklist
4. Present both notes in the specified format
|
