docs: clarify when to create the stack changeset, and when growing it is required

[thecodedrift]

Summary

Two refinements to the One changeset, at the bottom of the stack, grown as the stack grows section of CLAUDE.md. Both were found by walking into them on the real 4-PR merging-down stack (#71/#93/#94/#95).

Gap 1 — the section said where the changeset lives, never when to create it. "At the bottom, grown as the stack grows" describes the steady state, not the trigger. Inheritance only runs forward in time, so a child branched before the file existed has nothing to grow — and the natural moment to write a release note (finishing a unit) is exactly when you are standing on the wrong branch. Now documented: write it on the base branch before cutting the children. On that stack it was written on the tip, and removing skip-changeset from the bottom PR turned Require a changeset red immediately.

Gap 2 — "grow it incrementally" is merge-forward reasoning stated as a universal rule. Its justification is that a reviewer shouldn't approve a release note promising more than the diff in front of them, which only holds when each unit reaches main separately. Under merging down, one protected merge carries the whole stack, so a whole-change note is accurate at the only moment it is read. The rule is now scoped to forward, with the constraint that holds in both shapes stated plainly: the file must be in the bottom PR's own diff, since that is the only diff require-changeset evaluates.

Notes

• Documentation only; no code, no openspec/ files, no behavior change.
• Labeled skip-changeset — a CLAUDE.md edit ships no release content.
• The rest of the "Stacked PRs" section is untouched and un-reordered.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jwc9FFroR3mTZ4hLiSkkX3

[Copilot]

Pull request overview

Refines the stacked-PR documentation in CLAUDE.md to clarify (1) when to create the stack’s single changeset file and (2) when “grow it incrementally” is a requirement vs. an optional review-friendly practice, depending on whether the stack merges forward or down.

Changes:

• Document that the changeset must be created on the base branch before cutting child branches (inheritance only runs forward in time).
• Scope “grow it incrementally” to merge-forward stacks, and explicitly explain why that reasoning doesn’t apply to merge-down stacks.
• Restate the invariant that always matters: the changeset must live on the bottom branch and be present in the bottom PR’s own diff (the only diff the workflow evaluates).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.