docs(skills): document mergify stack note in mergify-stack skill (#1310)

The `mergify stack note` command exists but the mergify-stack skill
didn't mention it, so Claude never used it when amending pushed
commits. Add it to the conventions, commands reference, and common
mistakes table, plus a dedicated "Amend Notes" section explaining
how notes propagate to the PR's Revision history comment (markdown
table + JSON marker) via `mergify stack push`.

Also extend the description trigger list with "note" and
"revision history" so the skill activates on those keywords.

Author: jd

skills/mergify-stack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mergify-stack
-description: Use Mergify stacks for git push, commit, branch, and PR creation. ALWAYS use this skill when pushing code, creating commits, creating branches, or creating PRs. Triggers on push, commit, branch, PR, pull request, stack, stacked, git, rebase, checkout, reorder, move, sync, amend.
+description: Use Mergify stacks for git push, commit, branch, and PR creation. ALWAYS use this skill when pushing code, creating commits, creating branches, or creating PRs. Triggers on push, commit, branch, PR, pull request, stack, stacked, git, rebase, checkout, reorder, move, sync, amend, note, revision history.
 ---
 
 # Mergify Stack Workflow
@@ -20,6 +20,7 @@ A branch is a stack. Keep stacks short and focused:
 
 - **Push**: Use `mergify stack push` (never `git push`)
 - **Fixes**: Use `git commit --amend` (never create new commits to fix issues)
+- **Amend notes**: When amending a commit that already has a PR (i.e. has been pushed), attach a `mergify stack note` BEFORE `mergify stack push` to record *why* the commit was amended. The note appears in the PR's "Revision history" comment and JSON marker, so reviewers can see the reason without diffing.
 - **Mid-stack fixes**: Stash any local changes first (`git stash -u`), then use `git rebase -i` to edit the specific commit, amend it, continue rebase, then `mergify stack push`, then `git stash pop`
 - **Reordering**: Stash any local changes first (`git stash -u`), then use `mergify stack reorder` (list all commits in desired order) or `mergify stack move` (move a single commit) instead of manual `git rebase -i` — non-interactive and avoids `GIT_SEQUENCE_EDITOR` quoting issues
 - **Fixup**: Stash any local changes first (`git stash -u`), then use `mergify stack fixup <SHA>...` to fold a commit into its parent (drops the listed commit's message). Non-interactive — never use `git rebase -i` for this.
@@ -44,6 +45,7 @@ A branch is a stack. Keep stacks short and focused:
 | `git rebase -i` to squash commits | `mergify stack squash A B into X [-m "..."]` | Non-interactive — works inside LLM/agent sessions; no editor spawned |
 | Deferring lint fixes to a later commit | Include the fix in the commit that caused it | Each commit runs CI independently; later commits won't save earlier ones |
 | Rebase/reorder/checkout/sync with dirty worktree | `git stash -u` first, then `git stash pop` after | Uncommitted changes are lost or cause conflicts during these operations |
+| Amending a pushed commit with no explanation | `mergify stack note -m "why"` before `mergify stack push` | The reason is recorded in the PR's Revision history table and JSON marker, so reviewers don't need to diff to understand the change |
 
 ## Commands
 
@@ -63,6 +65,10 @@ mergify stack fixup X              # Fold commit X into its parent (drops X's me
 mergify stack fixup X Y Z          # Fold each into its parent (multi-fixup)
 mergify stack squash X into Y      # Reorder X adjacent to Y, fold X into Y (keeps Y's message)
 mergify stack squash X Y into Z -m "msg"  # Fold X Y into Z with a custom message
+mergify stack note -m "why"        # Attach an amend reason to HEAD (shown in PR revision history)
+mergify stack note <SHA-or-Change-Id-prefix> -m "why"  # Attach to a specific commit in the stack
+mergify stack note --append -m "more"                  # Append to an existing note
+mergify stack note --remove                            # Remove the note from a commit
 ```
 
 Use `mergify stack checkout NAME` to check out a stack that exists on GitHub (e.g. a colleague's stack). NAME is the remote branch name of the stack. It fetches all stacked PRs, creates a local branch, and sets up tracking. Use `--branch` to override the local branch name.
@@ -71,6 +77,31 @@ Use `mergify stack sync` to bring your stack up to date. It fetches the latest t
 
 Use `mergify stack list` to see which commits have been pushed, which PRs they map to, and whether the stack is up to date with the remote. It also shows CI status, review status, and merge conflicts for each PR. Use `--verbose` for detailed check names and reviewer names. Use `--json` when you need to parse the output programmatically — it includes full CI check details and review data.
 
+## Amend Notes
+
+`mergify stack note` records *why* a commit was amended. The note travels with the stack:
+
+- Stored locally under `refs/notes/mergify/stack` against the commit SHA.
+- Pushed automatically by `mergify stack push` (alongside the commit refspecs, with `--force-with-lease`).
+- Surfaced in the PR's **Revision history** comment as the `Reason` column of the markdown table, and embedded in the `<!-- mergify-revision-data: {...} -->` JSON marker (key `reason`) so it can be parsed programmatically.
+
+**When to attach a note** — any time you amend or rewrite a commit that already has a PR open (i.e. it has been pushed at least once). The note answers "why is this revision different?" so the reviewer doesn't have to diff old vs new SHAs to find out.
+
+**Workflow** — attach the note BEFORE `mergify stack push`:
+
+```bash
+# Edit HEAD, then:
+git commit --amend
+mergify stack note -m "address review: rename foo() to bar()"
+mergify stack push
+
+# Or for a mid-stack commit (after the rebase that amended it):
+mergify stack note <SHA-or-Change-Id-prefix> -m "fix lint reported in CI"
+mergify stack push
+```
+
+A note is per-commit, not per-revision. Each amend (or other history rewrite) creates a new commit SHA, so you must run `mergify stack note` again for the new SHA — the previous note stays attached to the old SHA and won't carry over. Use `--append` only when the current target commit already has a note and you want to add another reason; use `--remove` to clear it. Notes on commits that haven't changed since the last push are preserved but won't add a new revision row.
+
 ## CRITICAL: Check Branch Before ANY Commit
 
 **BEFORE staging or committing anything**, always check the current branch and assess stack state: