feat(release): enhance AI prompt for generating user-focused release notes

scripts/release/generate-notes

@@ -104,141 +104,155 @@ generate_with_copilot() {
     # This helps the AI understand which commits touched which files
     COMMITS=$(git log --pretty=format:"%h | %s%n%b%n" --stat --compact-summary "${FROM_TAG}..${TO_TAG}")
 
+    # Get code diff for user-facing files to give the AI real context about what changed.
+    # Limited to ~8KB to keep the prompt manageable.
+    DIFF_CONTEXT=$(git diff --unified=2 --diff-filter=AM \
+        -- "custom_components/tibber_prices/sensor/" \
+        -- "custom_components/tibber_prices/binary_sensor/" \
+        -- "custom_components/tibber_prices/config_flow_handlers/" \
+        -- "custom_components/tibber_prices/services/" \
+        -- "custom_components/tibber_prices/translations/" \
+        -- "custom_components/tibber_prices/number/" \
+        -- "custom_components/tibber_prices/switch/" \
+        "${FROM_TAG}..${TO_TAG}" 2>/dev/null | head -c 8000 || true)
+
     if [[ -z $COMMITS ]]; then
         log_info "${YELLOW}No commits found between ${FROM_TAG} and ${TO_TAG}${NC}"
         exit 0
     fi
 
     # Create prompt for Copilot
-    PROMPT="You are tasked with generating professional release notes in GitHub-flavored Markdown from conventional commits.
+    PROMPT="You are writing a GitHub release announcement for a Home Assistant integration called **Tibber Prices**.
 
-**CRITICAL Format Requirements:**
+## YOUR AUDIENCE
+Home Assistant users — people who automate their home and build dashboards. They are NOT developers.
+They do not understand technical terms like: coordinator, entity, async, refactor, TypedDict, module,
+class, iterator, cache, pool, BaseCalculator, interval_pool, or any Python/software engineering terminology.
 
-1. **START with a single-line title using '# ' (H1 heading):**
+## WHAT THIS INTEGRATION DOES
-   - Analyze ALL commits and create a SHORT, descriptive title (max 5-7 words)
+It fetches electricity prices from Tibber and provides sensors to Home Assistant, so users can:
+- See the current electricity price on their dashboard
+- Automate appliances to run during cheapest hours (dishwasher, washing machine, heat pump, EV charging)
+- Get alerts when prices are unusually high or low
+- Find the best time window in the day for flexible loads
 
-   **HOW TO CHOOSE THE TITLE:**
+## YOUR GOAL
-   Step 1: Scan commit scopes and identify USER-FACING changes:
+Translate technical changes into real user benefits. Write as a product manager telling
-     - feat(sensors): ✅ User feature (they see new sensors)
+users what they can now DO, what was BROKEN and is now FIXED, or why the integration
-     - feat(config_flow): ✅ User feature (they use config UI)
+is now more RELIABLE.
-     - feat(services): ✅ User feature (they call services)
-     - fix(translations): ✅ User fix (they see corrected text)
-     - feat(release): ❌ Developer tool (users don't see this)
-     - feat(ci): ❌ Infrastructure (users don't care)
-     - docs: ❌ Documentation (nice but not a feature)
 
-   Step 2: Among user-facing changes, prioritize by impact:
+## WRITING RULES — FOLLOW STRICTLY
-     - New sensor types > Config improvements > Bug fixes > Translations
-     - Multiple related sensors = name the feature domain (e.g., \"Price Volatility Analysis\")
-     - Major config flow changes = \"Enhanced Configuration Experience\"
 
-   Step 3: Ignore developer/internal changes for title selection:
+**Rule 1 — No jargon, ever.**
-     - Even if there are 10 release/ci/docs commits, they don't appear in title
+NEVER use: coordinator, entity, async, class, module, package, cache invalidation, refactor, pool,
-     - Title must reflect what USERS experience when they upgrade
+iterator, TypedDict, BaseCalculator, interval_pool, config entry, data class, state machine.
+Always rephrase as a user experience.
 
-   **EXAMPLE DECISION PROCESS:**
+**Rule 2 — Second person, present tense.**
-   Given these commits:
+Write: \"You can now see...\", \"Your automations will...\", \"The setup wizard now...\"
-     - feat(sensors): Add 4 volatility sensors with classification
-     - feat(release): Add automated release notes generation
-     - fix(translations): Fix hassfest validation errors
-     - docs: Restructure documentation
 
-   WRONG title: \"Release Automation & Documentation\" (developer-focused!)
+**Rule 3 — Bug fixes: describe the SYMPTOM, not the technical cause.**
-   RIGHT title: \"Price Volatility Analysis Features\" (user sees new sensors!)
+  ❌ \"Fix timezone-aware datetime comparison at resolution boundary\"
+  ✅ \"Fixed: Price data was missing or showed wrong values when switching to/from daylight saving time\"
+  ❌ \"Restore missing while-loop increment preventing indefinite hang during period calculation\"
+  ✅ \"Fixed: The integration could occasionally freeze when calculating the cheapest time windows\"
 
-   **GOOD TITLES (user-focused):**
+**Rule 4 — New features: lead with what the user can DO.**
-   - \"# Advanced Price Analysis Features\" (new sensors = user feature)
+  ❌ \"Add volatility calculator with BaseCalculator integration\"
-   - \"# Enhanced Configuration Experience\" (config flow = user-facing)
+  ✅ \"New sensors show how stable today's prices are — useful for deciding whether to run flexible appliances now or wait\"
-   - \"# Improved Reliability & Performance\" (stability = user benefit)
 
-   **BAD TITLES (avoid these):**
+**Rule 5 — Refactoring without user impact: omit completely.**
-   - \"# Release Automation\" (developers don't read release notes!)
+Only mention internal changes if they improve actual reliability or stability that users
-   - \"# Developer Experience\" (not user-facing!)
+would notice. If so, group them under \"⚡ More Reliable\" as a brief single line.
-   - \"# New Features & Bug Fixes\" (boring, says nothing)
+NEVER write a refactoring bullet per commit.
 
-   Keep it exciting but professional. Do NOT include version number.
+**Rule 6 — Combine related commits into one story.**
+Do NOT list every commit as a separate bullet. Group related commits into a single
+paragraph or bullet that tells the complete story. Use multiple commit links for the group.
 
-2. **After title, use '### ' (H3 headings) for sections:**
+**Rule 7 — Use Impact: sections.**
-   - ### 🎉 New Features (for feat commits)
+Commit bodies may contain an \"Impact:\" line — this is the user-facing description.
-   - ### 🐛 Bug Fixes (for fix commits)
+Prioritize it over the commit subject line.
-   - ### 📚 Documentation (for docs commits)
-   - ### 📦 Dependencies (for chore(deps) commits)
-   - ### 🔧 Maintenance & Refactoring (for refactor/chore commits)
-   - ### 🧪 Testing (for test commits)
 
-3. **Smart grouping**: If multiple commits address the same logical change:
+**Rule 8 — Imagine explaining to your neighbor.**
-   - Combine them into one release note entry
+Before writing each bullet, ask: \"Would my neighbor who uses Home Assistant to automate their
-   - Link all related commits: ([hash1](url1), [hash2](url2))
+home understand this?\" If not, rephrase.
-   - Use a descriptive summary that captures the overall change
 
-4. Extract 'Impact:' sections from commit bodies as user-friendly descriptions
+## OUTPUT FORMAT
 
-5. Format each item as: - **scope**: Description ([hash](https://github.com/${GITHUB_REPO}/commit/hash))
+Start with: # [Short, exciting title — max 6 words, NO version number]
 
-6. **Exclude from release notes (but still consider for context):**
+Then sections using ### (H3 headings):
-   - Manifest.json version bumps: chore(release): bump version
-   - Development environment: feat/fix/chore(devcontainer), feat/fix/chore(vscode), feat/fix/chore(scripts)
-   - CI/CD infrastructure: feat/fix/chore/ci(ci), feat/fix/chore(workflow), feat/fix/chore(actions)
-   - IMPORTANT: These should NEVER influence the title choice, even if they're the majority!
 
-7. **Include in release notes (these CAN influence title):**
+- ### 🎉 What's New
-   - Dependency updates: chore(deps) - these ARE relevant for users
+  (New sensors, new config options, new automations possible — use this for feat commits with real user benefit)
-   - Any user-facing changes regardless of scope (sensors, config, services, binary_sensor, etc.)
-   - Bug fixes that users experience (translations, api, coordinator, etc.)
 
-8. **Understanding the file paths (use this to assess importance):**
+- ### 🐛 Fixed
-   - custom_components/tibber_prices/sensor/ = User-facing sensors (HIGH priority for title)
+  (Bugs users experienced — describe what was wrong, what is better now)
-   - custom_components/tibber_prices/binary_sensor.py = User-facing binary sensors (HIGH priority)
-   - custom_components/tibber_prices/config_flow.py = User-facing configuration (HIGH priority)
-   - custom_components/tibber_prices/services.py = User-facing services (HIGH priority)
-   - custom_components/tibber_prices/translations/*.json = User-facing translations (MEDIUM priority)
-   - scripts/ = Developer tools (LOW priority, exclude from title)
-   - .github/workflows/ = CI/CD automation (LOW priority, exclude from title)
-   - docs/ = Documentation (LOW priority, exclude from title)
 
-   **Key insight:** Large changes (100+ lines) in custom_components/tibber_prices/ are usually important user features!
+- ### ⚡ More Reliable
+  (Performance improvements OR refactoring that improves stability — only when users would notice)
 
-9. **Output structure example:**
+- ### 📦 Updated Dependencies
-   # Title Here
+  (Dependency bumps — keep brief, one line per group)
 
-   ### 🎉 New Features
+Skip any section that has no content.
 
-   - **scope**: description ([abc123](url))
+After the last section, ALWAYS end with this exact footer, no modifications:
-
-   ### 🐛 Bug Fixes
-   ...
-
----
-
-**Now, here are the commits to analyze (between ${FROM_TAG} and ${TO_TAG}):**
-
-${COMMITS}
-
----
-
-**Generate the release notes now. Start with '# ' title, then use '### ' for sections.**
-
-**IMPORTANT: Output ONLY the release notes in Markdown format. Do NOT include:**
-- Explanations or rationale for your choices
-- Meta-commentary about the process
-- Analysis of why you chose the title
-- Any text after the footer
-
-**Always end the output with this exact footer (after the last release note section):**
 
 ---
 
 If this release saved you some money on your electricity bill, a coffee would be much appreciated! ☕
 
-[![Buy Me A Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=jpawlowski&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/jpawlowski)"
+[![Buy Me A Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=jpawlowski&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/jpawlowski)
+
+## TITLE SELECTION
+- Find the most user-impactful change: new sensors > bug fixes affecting data quality > reliability improvements > UI improvements > translations
+- Ignore dev/CI/docs commits for the title
+- Make it sound exciting: \"Smarter Cheap-Period Detection\", \"Reliable DST Price Data\", \"New Price Stability Sensors\"
+- Example: if DST price data was wrong and now fixed → title = \"Reliable Prices Around Clock Changes\"
+
+## WHAT TO INCLUDE vs SKIP
+✅ Include: Changes to what sensors show, bugs fixing wrong data, config UI improvements,
+   automation reliability, dependency updates
+❌ Skip: Script/CI/workflow changes, version bumps, pure code reorganization,
+   documentation commits, test changes
+
+## FILE PATH GUIDE (for assessing importance)
+- sensor/ = Price sensors users see → HIGH
+- binary_sensor/ = On/off sensors for automations → HIGH
+- config_flow_handlers/ or config_flow/ = Setup wizard users interact with → HIGH
+- services/ = Actions users trigger → HIGH
+- translations/ = Labels users see in the UI → MEDIUM
+- number/ or switch/ = Controls users interact with → HIGH
+- coordinator/ = Data fetching/processing (rarely user-visible unless fixing data bugs) → LOW-MEDIUM
+- scripts/, .github/, docs/ = Developer-only → SKIP
+
+---
+
+**Commits to analyze (${FROM_TAG} → ${TO_TAG}):**
+
+${COMMITS}
+
+---
+
+**Code diff for user-facing files (use this to understand WHAT actually changed — but always translate to user language):**
+
+${DIFF_CONTEXT}
+
+---
+
+Output ONLY the release notes. Start directly with the # title.
+End after the Buy Me A Coffee button. No meta-commentary, no explanations."
 
     # Save prompt to temp file for copilot
     TEMP_PROMPT=$(mktemp)
     echo "$PROMPT" > "$TEMP_PROMPT"
 
-    # Use Claude Haiku 4.5 for faster, cheaper generation (same quality for structured tasks)
+    # Use Claude Sonnet for better user-focused, plain-language release notes.
-    # Can override with: COPILOT_MODEL=claude-sonnet-4.5 ./scripts/release/generate-notes
+    # Haiku tends to echo technical commit language; Sonnet better translates to user benefits.
-    COPILOT_MODEL="${COPILOT_MODEL:-claude-haiku-4.5}"
+    # Can override with: COPILOT_MODEL=claude-haiku-4.5 ./scripts/release/generate-notes
+    COPILOT_MODEL="${COPILOT_MODEL:-claude-sonnet-4-6}"
 
     # Call copilot CLI (it will handle authentication interactively)
     copilot --model "$COPILOT_MODEL" < "$TEMP_PROMPT" || {