smart-docs-updater
智能更新CHANGELOG.md和文档,通过跟踪工作会话。将多个相关变更累积为一条连贯的条目,而不是零散的更新。在用户表示“开始工作于X”或“修复Y”(会话开始)时使用;用户表示“完成”、“发货”、“完成X”(会话结束 - 触发文档更新);用户请求在多次提交后更新变更日志。不要在每次小更改后更新文档。等待会话完成
name: smart-docs-updater description: | Intelligently updates CHANGELOG.md and documentation by tracking work sessions. Accumulates multiple related changes into ONE coherent entry instead of fragmented updates.
Use this when:
- User says "start working on X" or "fixing Y" (session start)
- User says "done", "ship it", "finished with X" (session end - trigger docs update)
- User asks to update changelog after multiple commits
DO NOT update docs after every small change. Wait for session completion. aliases: - changelog-readme-updater
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:
- User-focused: What impact does this have?
- Concise: One line summary, details optional
- Grouped: Related changes = one entry
- Traceable: Include file paths or issue numbers
- 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:
- Create directory:
docs/product/builds/{feature-name}/ - Copy template:
cp docs/product/builds/BUILD_RECORD_TEMPLATE.md docs/product/builds/{feature-name}/BUILD_RECORD.md - 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
- Update CHANGELOG.md with user-facing changes
- Check for build record at
docs/product/builds/{feature}/BUILD_RECORD.md - If exists: Append to Progress Log, update Key Files
- If doesn't exist and significant work: Create one
- 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"