refactor(ci): Clarify version bump decision prompt for LLM

Author: underthestars-zhy

.github/blocks/determine-publish-version/action.yaml

@@ -117,42 +117,58 @@ runs:
           echo
           cat <<'PROMPT'
         Base your decision on the ACTUAL CODE CHANGES below — the commit
-        messages, the list of changed files, and the diff are all provided.
-        Commit messages are a hint, not the source of truth: most authors do
-        not annotate breaking changes, so the diff is authoritative. If the diff
-        was truncated you may run `git diff` yourself (read-only) for any file.
-
-        How to choose the bump (apply in order):
-        1. MAJOR — a breaking or broadly-disruptive change. Bump major if ANY
-           of these hold:
-           - a commit message carries an explicit `BREAKING CHANGE:` footer or
-             a `type!:` marker (authoritative); OR
-           - the DIFF is backward-incompatible even when no commit said so —
-             e.g. a public endpoint/route/exported symbol is removed or
-             renamed, a request/response schema or required field changes
-             shape, default behavior changes in a way that breaks existing
-             callers, or a config/runtime contract changes; OR
-           - the change lands on the common path for the vast majority of
-             users (roughly 90%+ of them) — e.g. it changes a default everyone
-             relies on, forces a migration / re-config / re-auth, or alters
-             output or UX that nearly all users will hit. A high blast radius
-             is breaking even if old code technically still compiles.
-           You are explicitly allowed to bump the major from the diff alone.
-        2. MINOR — backward-COMPATIBLE new functionality that users opt into: a
-           new endpoint, flag, exported symbol, or capability is ADDED without
-           breaking existing ones and without changing what current users
-           already experience (corresponds to `feat:`).
-        3. PATCH — bug fixes, performance, internal refactors, docs, chores, or
-           anything else that neither adds public surface nor breaks it, and
-           that most users won't actively notice.
-
-        Be conservative about MAJOR to avoid false positives. "Could affect 90%
-        of users" means the change alters something on the common path that
-        nearly all users already depend on — NOT merely that a new, opt-in
-        feature is available to them. A purely additive feature is MINOR even
-        if every user could eventually adopt it, because it doesn't disrupt
-        what they already do. When genuinely unclear between two levels, pick
-        the lower one (default to patch).
+        messages, changed files, and diff are all provided. Commit types such
+        as `feat:` and `fix:` are hints, not commands. The public compatibility
+        impact shown by the diff is the source of truth. If the diff was
+        truncated you may run `git diff` yourself (read-only) for any file.
+
+        Choose the highest bump that is concretely justified:
+        1. MAJOR — backward-INCOMPATIBLE. Use this only when an existing,
+           supported consumer must change code, configuration, stored data, or
+           usage to keep working. Concrete evidence includes:
+           - an explicit `BREAKING CHANGE:` footer or `type!:` marker; OR
+           - a public endpoint, route, export, option, or accepted input is
+             removed or renamed; OR
+           - a documented public schema/type changes incompatibly (a required
+             field is added, a field is removed, or its meaning/type changes);
+             OR
+           - an existing default or runtime/config contract changes such that a
+             previously valid, supported use case now fails or needs migration.
+           You may infer a major from the diff without a marker, but identify
+           the concrete public contract that existing consumers can no longer
+           use. Blast radius, visibility, changed-line count, or the fact that
+           behavior is automatic are NOT by themselves evidence of breakage.
+        2. MINOR — backward-compatible, user-visible functionality is ADDED.
+           This includes a new endpoint, flag, export, option, capability, or a
+           newly supported case in an existing operation. A feature does not
+           have to be opt-in. Returning richer information through an already
+           supported public type/variant can be minor when it handles data that
+           was previously ignored or lost and does not remove a supported use
+           case. A commit labeled `fix:` can therefore still be minor if it
+           gives users a meaningful new capability.
+        3. PATCH — a backward-compatible correction or maintenance change that
+           adds no new user capability: bug fixes that restore already-promised
+           behavior, performance work, refactors, tests, docs, and chores.
+
+        Use these tie-breakers:
+        - Do not treat observed buggy or incomplete behavior as a compatibility
+          guarantee unless it was a documented, supported contract.
+        - A behavior change can be PATCH or MINOR; it is MAJOR only when it
+          invalidates a supported contract and requires existing users to
+          migrate.
+        - To distinguish MINOR from PATCH, ask whether users can now do or
+          receive something meaningful they could not before. If yes, MINOR;
+          if the same promised capability merely works correctly, PATCH.
+        - Documentation for functionality that already existed is PATCH.
+        - When genuinely unclear between two levels, choose the lower one.
+
+        Examples:
+        - Optional media captions were previously discarded; they are now
+          exposed as attachment + text using an already-public group variant,
+          while media without captions is unchanged: MINOR, not MAJOR.
+        - A new optional API method or config flag: MINOR.
+        - A public field is renamed and callers must update: MAJOR.
+        - A crash is fixed without adding a capability: PATCH.
         PROMPT
           echo
           echo "A major bump of ${STABLE_VERSION} increments the first number and"