add create-release-note slash command and documentation

2025-12-17 15:36:53 +00:00 · 2025-10-17 00:38:04 +10:00 · 2025-10-17 00:38:04 +10:00 · 94724c9c51
commit 94724c9c51
parent c90188251f
2 changed files with 541 additions and 0 deletions
--- a/.claude/commands/documentation/create-release-note.md
+++ b/.claude/commands/documentation/create-release-note.md
@ -0,0 +1,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
--- a/README.md
+++ b/README.md
@ -130,6 +130,13 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st
  - Matches existing README style and tone
  - Usage: `/create-readme-section "Create an installation section for my Python project"`

+- **`/create-release-note`** - Generate comprehensive release documentation from recent commits with dual output formats
+  - Interactive workflow with two modes: by commit count or by commit hash range (last 24/48/72 hours)
+  - Produces customer-facing release note (value-focused, no technical jargon) and technical engineering note (SHA references, file paths)
+  - Comprehensive commit analysis with grouping by subsystem and traceability to specific SHAs
+  - Supports direct arguments for quick generation or interactive selection for precise control
+  - Usage: `/create-release-note` (interactive), `/create-release-note 20` (last 20 commits), or select commit hash after viewing recent commits
+
 ### `/security` Commands

 - **`/security-audit`** - Perform comprehensive security audit of the codebase