Smart Docs Updater

Smart Documentation Updater

File Locations

Documentation Index

Start here to understand the full documentation structure:

• docs/DOCUMENTATION.md — Master index of all documentation
• docs/DOCUMENTATION-MAP.md — How CLAUDE.md, docs/, and SOPs connect

Mandatory Updates (Always Check)

Conditional Updates (If Doc Exists for This Feature)

Rule: If a doc exists for the specific feature/bug/sprint being worked on → UPDATE IT.

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):

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

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

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

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"

Comprehensive Session-End Checklist

When user says "done", "ship it", or similar, run through this checklist.

Core Principle: Understand WHAT was built → Cross-reference ROADMAP → Find ALL related docs → Update them.

Step 1: Context Discovery (Understand the Work)

First, understand the scope of work completed:

# 1. Get recent commits to understand what was done
git log --oneline -10

# 2. Extract identifiers from commits (sprint IDs, feature names)
# Look for patterns like: M138, feature-name, bug-fix-name
git log --oneline -10 | grep -oE 'M[0-9]+|feat\([^)]+\)|fix\([^)]+\)'

# 3. Get all files changed to understand scope
git diff --name-only $(git log --oneline -10 | tail -1 | cut -d' ' -f1)..HEAD

Step 2: Cross-Reference ROADMAP

Read the ROADMAP to understand where this work fits:

# Read the roadmap to understand milestones and features
cat docs/product/ROADMAP.md

Questions to answer:

• Is this work part of a tracked milestone (e.g., "M138: Tool Feedback Loop")?
• Does this complete a feature listed in the roadmap?
• Is this a bug fix for a known issue?
• Is this part of an ongoing sprint?

Extract keywords from roadmap that match your work:

• Sprint/milestone IDs: M138, M137, etc.
• Feature names: "tool feedback loop", "knowledge review", etc.
• System areas: "company brain", "context intelligence", etc.

Step 3: Find ALL Related Docs

Using keywords from Steps 1-2, search across all doc types:

# Set your feature identifiers (from Steps 1-2)
FEATURE="m138"
KEYWORDS="tool feedback loop provenance"

# Search across all doc locations
echo "=== Sprint Docs ==="
ls docs/product/sprints/active/ 2>/dev/null | grep -iE "$FEATURE|feedback|provenance" || echo "None"
ls docs/product/sprints/completed/ 2>/dev/null | grep -iE "$FEATURE|feedback|provenance" || echo "None"

echo "=== Bug Reports ==="
ls docs/bugs/ 2>/dev/null | grep -iE "$FEATURE|feedback|provenance" || echo "None"

echo "=== Briefs ==="
ls docs/product/briefs/ 2>/dev/null | grep -iE "$FEATURE|feedback|provenance" || echo "None"

echo "=== PRDs ==="
ls docs/product/PRD/ 2>/dev/null | grep -iE "$FEATURE|feedback|provenance" || echo "None"

echo "=== Build Records ==="
ls docs/product/builds/ 2>/dev/null | grep -iE "$FEATURE|feedback|provenance" || echo "None"

echo "=== QA/Testing ==="
ls docs/product/sprints/qa/ 2>/dev/null | grep -iE "$FEATURE|feedback|provenance" || echo "None"

echo "=== Architecture Docs ==="
ls docs/architecture/ 2>/dev/null | grep -iE "$FEATURE|prompt|coaching|advisory" || echo "None"

echo "=== Design Docs ==="
ls docs/design/ 2>/dev/null | grep -iE "$FEATURE|design|crm|ui" || echo "None"

echo "=== SOPs ==="
ls advisory/clients/ 2>/dev/null | grep -iE "SOP|procedure" || echo "None"
ls .claude/skills/ 2>/dev/null | grep -iE "$FEATURE" || echo "None"

echo "=== ROADMAP References ==="
grep -in "$FEATURE" docs/product/ROADMAP.md || echo "Not in roadmap"

Step 4: Mandatory Updates (Always)

# 1. CHANGELOG.md - Always update
# Insert entry under ## [Unreleased]

# 2. Build Record - Create or update if significant work
ls docs/product/builds/*/BUILD_RECORD.md | grep -i "{feature-keyword}"
# If exists: Update Progress Log
# If not and significant: Create new

Step 5: Update ALL Found Docs

For each doc found in Step 3, apply the appropriate update:

Sprint Plans/Handovers (if found)

• Update "Daily Progress" section with accomplishments
• Mark completed tasks with [x] in "Backlog" section
• Add discovered gotchas to handover

Bug Reports (if found)

Add a "Resolution" section:

## Resolution (YYYY-MM-DD)

**Fixed in:** commit-hash or sprint-id
**Root cause:** Brief explanation
**Solution:** What was done
**Files changed:** List key files

Briefs (if found)

Add an "Outcome" section at the bottom:

## Outcome (YYYY-MM-DD)

**Implemented in:** M138 / commit-hash
**Final approach:** Brief description of what was built
**Deviations from brief:** Any scope changes or approach changes
**Build Record:** [Link to build record if exists]

PRDs (if found)

• Update status field if PRD has one
• Add implementation notes if requirements evolved
• Link to build record

ROADMAP.md (if milestone tracked OR scope changed OR learnings)

Update the roadmap when:

1. Milestone completed → Mark status as Complete, add date
2. Scope changed → Update milestone description, add/remove items
3. New learnings → Add notes about discovered complexity, dependencies, or blockers

## M138: Tool Feedback Loop
**Status:** ✅ Complete (Jan 24, 2026)
**Scope change:** Originally included UI integration; deferred to M140
**Learnings:** Feedback loop was implemented but never wired up - audit discovered disconnected code

QA/Testing Docs (if found)

• Document new test patterns
• Update coverage notes
• Add test utilities documentation

Architecture Docs (if prompt system changed)

When modifying files in lib/ai/prompts/, lib/ai/coaching/, lib/ai/advisory/, or lib/ai/chat/:

• Update relevant doc in docs/architecture/
• For module changes: Update 01-prompt-module-system.md
• For coaching/advisory: Update 05-coaching-advisory.md
• For context changes: Update 03-context-intelligence.md

Design Docs (if UI changed)

When modifying files in components/ui/, components/crm/, or app/ pages:

• Update docs/design/DESIGN-LANGUAGE.md for new patterns
• Update docs/design/CRM-SYSTEM.md for CRM-specific changes
• Add new CVA variants or component patterns discovered

SOPs (if workflow procedures changed)

When modifying operational workflows:

• Update advisory/clients/CLIENT_SOP.md for client procedures
• Update relevant .claude/skills/*/SKILL.md for agent procedures
• Update docs/modules/infrastructure/crm-system/migration-sop.md for data migrations

Quick Reference: Intelligent Doc Update Flow

Session End Triggered ("done", "ship it")
        │
        ▼
┌─────────────────────────────────────────────────────┐
│  STEP 1: CONTEXT DISCOVERY                          │
│  - Review recent commits                            │
│  - Extract sprint IDs (M138, M137...)               │
│  - Extract feature keywords                         │
└─────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────┐
│  STEP 2: CROSS-REFERENCE ROADMAP                    │
│  - Read docs/product/ROADMAP.md                     │
│  - Find matching milestones/features                │
│  - Understand where this work fits                  │
└─────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────┐
│  STEP 3: SEARCH ALL DOC LOCATIONS                   │
│  Using keywords from Steps 1-2, search:             │
│  - docs/product/sprints/active/                     │
│  - docs/product/sprints/completed/                  │
│  - docs/bugs/                                       │
│  - docs/product/briefs/                             │
│  - docs/product/PRD/                                │
│  - docs/product/builds/                             │
│  - docs/product/sprints/qa/                         │
│  - docs/architecture/                               │
│  - docs/design/                                     │
│  - advisory/clients/ (SOPs)                         │
│  - .claude/skills/ (Skill SOPs)                     │
└─────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────┐
│  STEP 4: MANDATORY UPDATES                          │
│  ✅ CHANGELOG.md → Always update                    │
│  ✅ Build Record → Create/update if significant     │
└─────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────┐
│  STEP 5: UPDATE ALL FOUND DOCS                      │
│                                                     │
│  For EACH doc found in Step 3:                      │
│  ┌─────────────────────────────────────────────┐    │
│  │ Sprint Plan exists?  → Update progress/tasks│    │
│  │ Sprint Handover?     → Add gotchas/patterns │    │
│  │ Bug Report exists?   → Add Resolution       │    │
│  │ Brief exists?        → Add Outcome section  │    │
│  │ PRD exists?          → Update status/notes  │    │
│  │ ROADMAP reference?   → Update status/scope  │    │
│  │ QA Doc exists?       → Document patterns    │    │
│  │ Architecture Doc?    → Update system design │    │
│  │ Design Doc exists?   → Update UI patterns   │    │
│  │ SOP exists?          → Update procedures    │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

Key Insight: Don't ask "should I update X?" — Instead, search for X and if it exists for this feature, update it.

Example Complete Session End

Example 1: Feature with Existing Docs

## Session End: M138 Tool Feedback Loop

### Step 1: Context Discovery
Commits: 9aa4c78, e0f1d4d
Keywords extracted: M138, tool feedback loop, provenance

### Step 2: Cross-Reference ROADMAP
Found in ROADMAP.md: "M138: Tool Feedback Loop - Provenance Tracking"
Status: In Progress → Should mark Complete

### Step 3: Found Related Docs
- Sprint: docs/product/sprints/active/M138-TOOL-FEEDBACK/ ✅ Found
- Brief: docs/product/briefs/CONTEXT-MEMORY-INTEGRATION-BRIEF.md ✅ Found (related)
- Bug Report: None
- Build Record: docs/product/builds/m138-tool-feedback-provenance/ ✅ Found

### Step 4: Mandatory Updates
- [x] CHANGELOG.md - Added M138 entry
- [x] Build Record - Updated progress log

### Step 5: Updated Found Docs
- [x] Sprint Plan - Marked tasks complete, updated daily progress
- [x] Brief - Added Outcome section linking to build record
- [x] ROADMAP.md - Marked M138 as Complete with date

### Commits
- 9aa4c78 feat(M138): Add provenance tracking to tool feedback loop
- e0f1d4d docs(M138): Add build record with audit findings
- abc1234 docs: Update sprint/brief/roadmap for M138 completion

Example 2: Bug Fix with Report

## Session End: Fix stuck chat context building

### Step 1: Context Discovery
Commits: b42adc7 fix(M135)
Keywords extracted: M135, stuck chat, context building, timeout

### Step 2: Cross-Reference ROADMAP
Found: M135 Chat Reliability sprint

### Step 3: Found Related Docs
- Bug Report: docs/bugs/CRITICAL-stuck-chat-context-building-failure.md ✅ Found
- Sprint: docs/product/sprints/active/M135-CHAT-RELIABILITY/ ✅ Found
- Build Record: None (should create)

### Step 4: Mandatory Updates
- [x] CHANGELOG.md - Added bug fix entry
- [x] Build Record - Created new for M135

### Step 5: Updated Found Docs
- [x] Bug Report - Added Resolution section with root cause and fix
- [x] Sprint Plan - Marked fix task complete

### Commits
- b42adc7 fix(M135): Prevent stuck chats with timeouts
- xyz9876 docs: Add resolution to bug report, update sprint