Smart Documentation Updater

File Locations

File	Path	Purpose
CHANGELOG.md	./CHANGELOG.md (project root)	All notable changes
Build Records	./docs/product/builds/{feature-name}/BUILD_RECORD.md	Per-feature architecture docs
Build Template	./docs/product/builds/BUILD_RECORD_TEMPLATE.md	Template for new records

IMPORTANT: Always use the project root CHANGELOG.md, not any other location.

Philosophy

Problem: Multiple commits for one fix = fragmented changelog entries Solution: Session-based tracking + intelligent summarization

Session Lifecycle

1. Session Start (Implicit or Explicit)

Explicit start:

• User says: "I'm going to fix the login bug" or "Starting work on feature X"
• Record the current git HEAD as session baseline

Implicit start:

• First code change in a conversation = session start
• Track from that point

State tracking (in memory or .claude/session-state.json):

{
  "session_id": "2025-12-25-login-fix",
  "started_at": "2025-12-25T12:00:00Z",
  "baseline_commit": "abc1234",
  "work_description": "Fixing login authentication flow",
  "changes_made": []
}

2. During Session (Accumulate, Don't Update)

As user works:

• Track files modified (from Edit/Write tool calls)
• Track commits made
• Note the problem being solved
• DO NOT update CHANGELOG.md yet

If user asks "update the changelog" mid-session:

• Ask: "Are you done with this work session, or still making changes?"
• If still working: "I'll wait until you're done to create one coherent entry"
• If done: Proceed to session end

3. Session End (Trigger Documentation Update)

Trigger phrases:

• "done", "finished", "ship it", "that's it", "complete"
• "update the docs now", "wrap this up"
• "commit and document this"

Process:

Step 1: Analyze All Changes Since Baseline

# Get all commits since session start
git log --oneline ${baseline_commit}..HEAD

# Get consolidated diff
git diff ${baseline_commit}..HEAD --stat

# Get detailed changes
git diff ${baseline_commit}..HEAD --name-status

Step 2: Intelligently Categorize

Group changes by TYPE (not by commit):

Category	When to Use
Added	New features, new files, new capabilities
Fixed	Bug fixes, error corrections
Changed	Refactors, behavior changes, updates
Removed	Deprecated features, deleted code
Security	Security-related fixes
Performance	Optimization changes

Step 3: Create ONE Coherent Entry

Bad (fragmented):

### Fixed
- Fix login button click handler
- Add null check to auth function
- Update error message for login
- Fix edge case in token validation

Good (intelligent summary):

### Fixed
- **Authentication flow**: Resolved login failures caused by null token handling and edge cases in validation. Improved error messaging for failed attempts. (lib/auth/, components/login/)

Step 4: Update CHANGELOG.md

Insert under ## [Unreleased] section:

## [Unreleased]

### Fixed
- **Authentication flow**: Resolved login failures caused by null token handling
  and edge cases in validation. Improved error messaging.
  ([#issue] if applicable)

Step 5: Update README.md (If Applicable)

Only update if:

• New user-facing features added
• API changes that affect usage
• New dependencies or requirements
• Installation steps changed

Skip if:

• Internal refactors
• Bug fixes with no API changes
• Performance improvements

4. Multi-Problem Sessions

If user works on MULTIPLE unrelated issues in one session:

Detection:

• Commits touch completely different areas
• User explicitly mentions multiple issues
• Long time gaps between commit clusters

Handling:

• Create SEPARATE changelog entries for each logical unit
• Group by feature/area, not by time

Example output:

## [Unreleased]

### Fixed
- **Authentication**: Resolved token validation edge cases (lib/auth/)
- **CRM Display**: Fixed company name truncation in sidebar (components/crm/)

### Changed
- **Memory System**: Optimized compression for large conversations (lib/memory/)

Commands Reference

User Says	Action
"I'm fixing X"	Start session, record baseline
"Working on feature Y"	Start session, record baseline
"Done" / "Ship it"	End session, update docs
"Update changelog"	Ask if done, then update
"What have I changed?"	Summarize changes since baseline
"Nevermind, discard"	Clear session, no docs update

Quality Guidelines

Changelog Entries Should Be:

1. User-focused: What impact does this have?
2. Concise: One line summary, details optional
3. Grouped: Related changes = one entry
4. Traceable: Include file paths or issue numbers
5. Present tense: "Fix X" not "Fixed X"

Avoid:

• Entry per commit
• Implementation details users don't care about
• Duplicate entries for the same fix
• Updating docs before work is complete

Edge Cases

User Forgets to "End" Session

• If new unrelated work starts, auto-close previous session
• Or ask: "Should I document the previous work before we start this?"

Work Spans Multiple Days

• Session state persists across conversations
• Use git history as source of truth
• Baseline commit is the key reference point

Merge Conflicts in CHANGELOG

• Always read current CHANGELOG.md before updating
• Insert new entries at the TOP of [Unreleased]
• Preserve existing entries

Integration with Sprint System

If project uses sprint tracking (like this one):

• Cross-reference sprint IDs in changelog entries
• Link to sprint docs where applicable

### Added
- **Company Brain context optimization** (M50): Token-efficient company
  chats with searchable files. See [sprint docs](docs/product/sprints/completed/M50/)

Build Record Integration

Build Records capture per-feature architecture, decisions, and progress. They complement the CHANGELOG by providing deep context.

When to Create/Update Build Records

Scenario	Action
New feature implementation	Create new build record in docs/product/builds/{feature-name}/
Bug fix sprint	Create build record documenting what was fixed and why
Significant refactor	Create build record with design decisions
Session completion	Check if relevant build record needs progress update

Build Record Workflow

Step 1: Check for Existing Build Record

# Check if build record exists for current work
ls docs/product/builds/*/BUILD_RECORD.md

Step 2: Create if Needed

If working on a feature without a build record:

1. Create directory: docs/product/builds/{feature-name}/
2. Copy template: cp docs/product/builds/BUILD_RECORD_TEMPLATE.md docs/product/builds/{feature-name}/BUILD_RECORD.md
3. Fill in sections as you work

Step 3: Update on Session End

When session ends, update the build record with:

• Progress Log: What was accomplished this session
• Design Decisions: Any trade-offs or choices made
• Key Files: New files added or modified
• Retrospective: (if marking complete) Lessons learned

Build Record vs CHANGELOG

CHANGELOG	Build Record
What changed (user-facing)	Why it was built this way
Brief, one-line entries	Detailed architecture
Chronological	Per-feature
For users/reviewers	For future developers

Example Session End Workflow

1. Update CHANGELOG.md with user-facing changes
2. Check for build record at docs/product/builds/{feature}/BUILD_RECORD.md
3. If exists: Append to Progress Log, update Key Files
4. If doesn't exist and significant work: Create one
5. Commit both together

Commit Tracking Hook

A PostToolUse hook logs commits to .context/state/commits-pending-build-record.json. Check this file when user says "done" to see if build records need updating.

# Check pending commits
cat .context/state/commits-pending-build-record.json 2>/dev/null || echo "No pending commits"