brk/.claude/prompts/changelog.md

# Changelog Generation Prompt

Update docs/CHANGELOG.md for ALL releases starting from v0.0.107 onwards. Use ONLY git commands - no other sources.

## MANDATORY PROCESS - FOLLOW EXACTLY - NO EXCEPTIONS:
1. Run `git tag --list --sort=version:refname` to get releases in order
2. Process EXACTLY ONE release at a time
3. For EACH SINGLE release: run `git diff [previous-tag]..[current-tag]`
4. **MANDATORY ANALYSIS STEP**: Before writing ANY changelog entry, you MUST:
   - Analyze each file change and explain what the code is doing
   - Identify the purpose and impact of each modification
   - Group related changes together logically
   - State clearly what functionality is being added, removed, or modified
   - If you cannot understand what a change does from the diff, explicitly say so
5. Only AFTER completing the analysis, write the detailed changelog entry
6. Update the CHANGELOG.md file with that ONE entry
7. STOP. Ask me if you should continue to the next release.

## CRITICAL CONSTRAINTS:
- **NEVER EVER** process multiple releases in one go, even if there are many
- **NEVER** say "let me continue more efficiently by processing multiple releases"
- **NEVER** batch releases together for any reason
- If you feel tempted to process multiple releases, **STOP** and process only one
- Context window concerns do **NOT** justify batching - process one release only

## ABSOLUTE REQUIREMENTS:
- **NEVER** read commit messages, PR descriptions, existing changelog, or any text documentation
- Use **ONLY** the actual code changes shown in git diff output
- Process releases **ONE BY ONE** - I don't care if there are 100 releases
- **MANDATORY**: Before writing changelog entries, demonstrate understanding by analyzing what each code change accomplishes
- Be **HIGHLY DESCRIPTIVE** about what each code change does and why it matters
- Don't be conservative - write detailed explanations of the impact and purpose of changes
- **If you don't understand a change from the code diff alone, DO NOT GUESS - say so explicitly**

## SOURCE OF TRUTH:
- `git diff` output is the **ONLY** source of truth
- If you can't determine what a change does from the code diff alone, say so explicitly
- Ignore **ALL** text/documentation - focus purely on code additions, deletions, and modifications

## CHANGELOG FILE REQUIREMENTS:
- Add a header at the top of the CHANGELOG.md file: `<!-- This changelog was generated by Claude Code -->`
- Ensure this header appears before any changelog entries

## CHANGELOG WRITING RULES:

### RELEASE TITLE FORMAT:
**MUST** use this exact format: `## [vX.Y.Z](https://github.com/bitcoinresearchkit/brk/releases/tag/vX.Y.Z) - YYYY-MM-DD`
Use the actual release date from git tag information

### ABSOLUTELY FORBIDDEN PATTERNS:
- **NEVER** mention line counts (e.g., "with 138 lines", "1,290 lines removed")
- **NEVER** use vague action words: "Enhanced", "Improved", "Updated", "Expanded", "Restructured", "Refactored", "Modified", "Adjusted"
- **NEVER** write sections about Cargo.lock or dependency updates unless they represent major functional changes
- **NEVER** use the format "Action: File with vague description"
- **NEVER** mention version bumps of local crates (e.g., "Updated all crate versions from 0.0.61 to 0.0.62") - this is implied by the release version
- **NEVER** mention dependency version changes in external crates unless they enable new functionality visible in the code
- **NEVER** write entries like "Updated dependencies" or "Cargo.lock maintenance"

### REQUIRED WRITING STYLE:
- Write what the code **actually DOES**, not that it was "enhanced" or "improved"
- Be **specific about functionality**: "Added transaction validation logic", "Implemented caching for API responses"
- Focus on **business/functional impact**: "Enables users to...", "Fixes issue where...", "Adds support for..."
- **Mandatory structure**: Group by: Breaking Changes, New Features, Bug Fixes, Internal Changes
- Include GitHub file links for major changes (max 5 per entry)
- **Skip entirely**: minor dependency bumps, Cargo.lock changes, and local crate version bumps

### MANDATORY ANALYSIS WORKFLOW:
**BEFORE writing any changelog entry, you MUST:**

1. **Code Comprehension Check**: Go through each modified file and explain:
   - What specific functionality is being added/removed/changed
   - What the new/modified functions/structs/methods do
   - How the changes affect the overall system behavior

2. **Impact Assessment**: For each change, determine:
   - Is this a new feature, bug fix, breaking change, or internal improvement?
   - What user-facing or system behavior changes result from this code?
   - What problem does this change solve?

3. **Logical Grouping**: Organize related changes together:
   - Group files that work together to implement a single feature
   - Separate breaking changes from additions
   - Distinguish user-facing changes from internal refactoring

4. **Understanding Verification**: Before writing changelog text, state:
   - "I understand this change does X because the code shows Y"
   - If unclear: "I cannot determine the purpose of this change from the diff alone"

**ONLY AFTER completing this analysis should you write the changelog entry.**

### WHAT TO FOCUS ON (IN ORDER OF PRIORITY):
1. **New functionality** - What can users now do that they couldn't before?
2. **Breaking changes** - What existing functionality changed or was removed?
3. **Bug fixes** - What specific problems were resolved?
4. **Internal changes** - New modules, significant refactoring, architecture changes
5. **Skip completely** - Dependency updates, version bumps, Cargo.lock changes

### VERBOSITY REQUIREMENTS:
- **Minimum 3-4 bullet points per section** when changes exist
- **Each bullet point should be 1-2 sentences** explaining both what changed and why it matters
- **For new features**: Explain what the feature does and what problem it solves
- **For bug fixes**: Describe the problem that was fixed (inferred from the code changes)
- **For internal changes**: Explain the architectural or structural improvement

### EXAMPLES OF GOOD vs BAD:

#### ❌ BAD EXAMPLES:
- "Enhanced: Chain analysis with sophisticated blockchain processing capabilities"
- "Updated: brk_rolldown from 0.0.1 to 0.1.0 with comprehensive bundling improvements"
- "Version Bump: Updated all crate versions from 0.0.61 to 0.0.62"
- "Improved error handling"
- "Refactored codebase"
- "Updated dependencies"

#### ✅ GOOD EXAMPLES WITH ANALYSIS:

**Analysis**: "Looking at the diff, I see a new `TransactionAnalyzer` struct was added with methods `calculate_fee()` and `is_coinbase()`. The struct takes transaction data and provides analysis methods. This enables users to programmatically analyze transaction properties."

**Changelog**: "Added new `TransactionAnalyzer` struct that provides methods for computing transaction fees and detecting coinbase transactions"

**Analysis**: "The diff shows error handling was added around block parsing where previously there was an unwrap(). Now it returns a Result and handles the empty block case explicitly. This prevents panics when processing malformed blocks."

**Changelog**: "Fixed panic when processing blocks with zero transactions by adding explicit empty block handling and proper error propagation"

**Analysis**: "I see a new caching layer was implemented with a HashMap storing block hashes as keys and block data as values. The API endpoints now check this cache before making network requests. This should improve performance for repeated queries."

**Changelog**: "Implemented new caching layer for blockchain queries, reducing API response time by storing frequently accessed block data in memory"

#### ❌ BAD EXAMPLES (NO UNDERSTANDING):
- "Enhanced error handling" (What specific errors? How were they enhanced?)
- "Improved performance" (What was improved? How?)
- "Updated transaction logic" (What specific logic? What changed?)

## FINAL REMINDER:
**PROCESS ONLY ONE RELEASE. THEN STOP AND WAIT FOR MY CONFIRMATION.**

You must be thorough and verbose - if there are code changes, there should be substantial changelog content explaining what those changes accomplish.