brk/docs/claude/changelog.md

# Changelog Generation for Claude Code

**TASK**: Update docs/CHANGELOG.md for ALL latest releases missing from the file.

## ⚠️ CRITICAL FAILURE MODE TO AVOID ⚠️
**THE #1 FAILURE**: Ignoring most changes and only documenting a few
**ABSOLUTELY FORBIDDEN**: Skipping changes, summarizing with "and other updates", or being incomplete
**YOU MUST DOCUMENT EVERY SINGLE MEANINGFUL CHANGE - NO EXCEPTIONS**

## CORE WORKFLOW - EXECUTE EXACTLY:

### Step 1: Get Release Information
```bash
git tag --list --sort=version:refname
```

### Step 2: Process ONE Release at a Time
For each missing release, execute these commands to get complete information:

**First, get the file list:**
```bash
git diff --name-only [previous-tag]..[current-tag]
```

**Then, get changes excluding Cargo.lock:**
```bash
git diff [previous-tag]..[current-tag] -- . ':(exclude)Cargo.lock'
```

**If output is too large, examine files individually:**
```bash
git diff [previous-tag]..[current-tag] -- path/to/specific/file.rs
```

**For summary of changes per file (if needed):**
```bash
git diff --stat [previous-tag]..[current-tag]
```

### Step 3: Analyze Before Writing
**MANDATORY**: Before writing ANY changelog entry, analyze the diff output and explain:
- **Use `git diff --name-only` to see ALL changed files** - this prevents truncation issues
- **Use `git diff -- . ':(exclude)Cargo.lock'` to see actual changes** without Cargo.lock noise
- **If output is large, examine key files individually** with `git diff [tags] -- path/to/file`
- **Identify every functional change** - what new capabilities, fixes, or modifications were made
- What each code change accomplishes functionally
- The user-facing or system impact of modifications
- **Which crate each change belongs to** (based on file paths)
- How changes group together logically within and across crates
- What functionality is added/removed/modified per crate

**COMPLETENESS CHECK**: State "I have analyzed X files and identified Y distinct functional changes to document"

### Step 4: Write Changelog Entry
Only after analysis, update CHANGELOG.md with ONE release entry.

**REQUIRED**: End each release entry with a comparison link:
```markdown
[View changes](https://github.com/bitcoinresearchkit/brk/compare/vPREVIOUS...vCURRENT)
```
Where PREVIOUS is the previous release tag and CURRENT is the current release tag.

### Step 5: Stop and Confirm
**CRITICAL**: Process only ONE release, then ask for confirmation to continue.

---

## STRICT RULES

### FORBIDDEN - NEVER MENTION:
- **Cargo.lock** (ignore completely)
- **Line counts** ("added 50 lines", "removed 200 lines")
- **Dependency version bumps** (unless enabling major new features)
- **Local crate version changes** (0.0.61 → 0.0.62)
- **Vague words**: "Enhanced", "Improved", "Updated", "Refactored"

### FORBIDDEN PHRASES:
- "and other changes"
- "various updates"
- "along with minor improvements"
- "among other enhancements"
- **"along with other modifications"**
- **"plus additional changes"**
- **"including other updates"**
- **"and more"**
- **ANY phrase that suggests you're skipping changes**

### REQUIRED - MUST INCLUDE:
- **Every meaningful change** in the diff (no shortcuts)
- **Specific functionality** descriptions
- **Business impact** of each change
- **Complete coverage** - if 20 changes exist, document all 20
- **Source links** for significant changes (new features, breaking changes, major bug fixes)

## WORKSPACE-SPECIFIC RULES

### Crate Identification:
- **Determine crate from file paths** in the diff (e.g., `crates/brk-core/src/lib.rs` → `brk-core`)
- **Group all changes by their crate** before writing changelog entries
- **Use crate name as subheading** under each change type section
- **For root-level files**: Use `workspace` as the crate name

### Cross-Crate Changes:
- **When changes span multiple crates** for one feature, mention the relationship
- **Example**: "Added new transaction API in `brk-core` with corresponding HTTP endpoints in `brk-api`"

### Crate Naming:
- **Use backticks** around crate names: `brk-core`, `brk-api`
- **Use workspace structure** as shown in file paths, not display names

### File Header (if missing):
```markdown
<!-- This changelog was generated by Claude Code -->
```

### Release Entry Format:
```markdown
## [vX.Y.Z](https://github.com/bitcoinresearchkit/brk/releases/tag/vX.Y.Z) - YYYY-MM-DD

### Breaking Changes
#### `crate-name`
- Specific change with functional impact explanation ([source](https://github.com/bitcoinresearchkit/brk/blob/vX.Y.Z/path/to/file.rs))

### New Features
#### `crate-name`
- Feature description with user benefit ([source](https://github.com/bitcoinresearchkit/brk/blob/vX.Y.Z/path/to/main/file.rs))
- Another feature with implementation details

#### `another-crate`
- Feature specific to this crate

### Bug Fixes
#### `crate-name`
- Specific problem that was resolved ([source](https://github.com/bitcoinresearchkit/brk/blob/vX.Y.Z/path/to/file.rs))
- Another bug fix with impact description

### Internal Changes
#### `crate-name`
- Architectural improvement with purpose
- Code organization change with benefit

[View changes](https://github.com/bitcoinresearchkit/brk/compare/vPREVIOUS...vCURRENT)
```

---

## ANALYSIS REQUIREMENTS

**Before writing changelog text, you MUST state:**

1. **File discovery**: "Using git diff --name-only, I see X files were modified"
2. **Cargo.lock check**: "After excluding Cargo.lock, Y files contain actual changes"
3. **Functional changes identified**: "I identified these distinct changes: A, B, C, D..."
4. **What each change does**: "Change A: adds new API endpoints, Change B: fixes memory leak, etc."
5. **Which crates are affected**: "Changes span crates: A, B, C"
6. **What this means for users**: "Users can now do X, bug Y is fixed, etc."
7. **How changes group together**: "Changes A and B work together to implement feature W"
8. **Cross-crate dependencies**: "Crate A's new feature requires the new API in crate B"
9. **Any unclear changes**: "I cannot determine the purpose of change X from the diff"
10. **FINAL CHECK**: "I will now document all X functional changes without listing files"

**MANDATORY**: The changelog should describe FUNCTIONALITY, not files. But you must capture ALL functionality changes.

**Only after this analysis, write the changelog entry.**

---

## EXAMPLES

### ❌ BAD (Vague, incomplete):
```markdown
### New Features
- Enhanced blockchain processing capabilities
- Improved error handling and various other updates
```

### ✅ GOOD (Specific, complete, grouped by crate, with source links):
```markdown
### New Features
#### `brk-core`
- Added `TransactionAnalyzer` struct with fee calculation and coinbase detection methods ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.0.108/crates/brk-core/src/analyzer.rs))
- Implemented in-memory caching layer for blockchain queries using HashMap storage

#### `brk-api`
- Added three new API endpoints: `/api/blocks/{hash}`, `/api/transactions/search`, and `/api/stats/network` ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.0.108/crates/brk-api/src/routes.rs))
- Implemented standardized error responses with error codes and descriptions

### Bug Fixes
#### `brk-core`
- Fixed panic when processing blocks with zero transactions by adding explicit empty block validation ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.0.108/crates/brk-core/src/block.rs))

#### `brk-api`
- Resolved memory leak in connection pool by implementing proper cleanup in Drop trait

[View changes](https://github.com/bitcoinresearchkit/brk/compare/v0.0.107...v0.0.108)
```

---

## SUCCESS CRITERIA

✅ **COUNT files modified for internal verification only**
✅ **Identify EVERY distinct functional change**
✅ **Document ALL functionality changes (no "other changes")**
✅ **Changelog describes WHAT users can do, not which files changed**
✅ **Never mention Cargo.lock or line counts**
✅ **Use specific, functional descriptions**
✅ **Complete analysis before writing**
✅ **Stop and ask for confirmation after each release**

**FAILURE INDICATORS - If you do any of these, you FAILED:**
❌ "and other changes"
❌ "various updates"
❌ "among other improvements"
❌ **Diff shows new API endpoints but changelog doesn't mention them**
❌ **Diff shows bug fixes but changelog misses some**
❌ **Diff shows new structs/functions but changelog ignores them**
❌ Missing obvious functional changes from the diff
❌ Summarizing instead of listing each distinct functionality change

**KEY PRINCIPLE**: Count files internally to ensure you don't miss changes, but write about FUNCTIONALITY for users.