From f4ce6953d15246a0e9b56b4ed7cb88aad220efa6 Mon Sep 17 00:00:00 2001 From: Dimitris Marlagkoutsos Date: Tue, 14 Apr 2026 18:28:08 +0200 Subject: [PATCH 1/3] fix(pr-skill): move changelog phase after PR creation Changelog entries need the PR number for links (e.g. `[#123]`), so they must be written after the PR is created, not before. Also adds stronger emphasis on consumer-perspective thinking and combining like changes, per the updating-changelogs.md instructions. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/pr/SKILL.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md index 74f54ba301..d62093d29d 100644 --- a/.claude/skills/pr/SKILL.md +++ b/.claude/skills/pr/SKILL.md @@ -107,13 +107,7 @@ Otherwise, after all launched subagents complete: - Abort 4. If there are no blockers, briefly summarize the findings and proceed. -## Phase 4: Update changelogs - -**MANDATORY — DO NOT SKIP.** Each PR must update changelogs for all packages with consumer-facing changes. -Read the instructions in [`docs/contributing/updating-changelogs.md`](../../../docs/contributing/updating-changelogs.md) and follow them to the letter. -Commit the changes to the current branch with the commit message "docs: Update changelogs" before creating the PR. - -## Phase 5: Create the PR +## Phase 4: Create the PR 1. Run `gh pr create` to create a pull request. The PR body should include: @@ -123,4 +117,19 @@ Commit the changes to the current branch with the commit message "docs: Update c **If this is a stacked PR**, add `--draft` to create it as a draft PR. -2. Return the PR URL and any relevant information. If a review was performed, include the review summary. +2. Note the PR number from the created PR URL — it is needed for changelog entries. + +3. Return the PR URL and any relevant information. If a review was performed, include the review summary. + +## Phase 5: Update changelogs + +**MANDATORY — DO NOT SKIP.** Each PR must update changelogs for all packages with consumer-facing changes. + +Read the instructions in [`docs/contributing/updating-changelogs.md`](../../../docs/contributing/updating-changelogs.md) and follow them **to the letter**. In particular: + +- **Think from the consumer's perspective.** A changelog is not a git history. For each affected package, ask: "What changed for someone who depends on this package?" Describe changes in natural language; do not simply reuse commit messages. +- **Combine like changes.** If multiple commits contribute to a single logical change within one package, write one changelog entry — not one per commit. +- **Split disparate changes.** If one commit touches unrelated concerns in a single package, write separate entries. +- **Link the PR.** Use the PR number from Phase 4 in each entry (e.g. `([#123](https://github.com/.../pull/123))`). + +Commit the changelog updates to the current branch with the message "docs: Update changelogs" and push. From f4f372f2a458d5ca14689273259baef18211d5e0 Mon Sep 17 00:00:00 2001 From: Dimitris Marlagkoutsos Date: Tue, 14 Apr 2026 18:30:55 +0200 Subject: [PATCH 2/3] fix(pr-skill): add no-changelog label step for non-consumer changes When a PR has no consumer-facing changes, the skill now adds the `no-changelog` label instead of silently skipping. This prevents CI changelog validation failures. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/pr/SKILL.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md index d62093d29d..1cd531e6df 100644 --- a/.claude/skills/pr/SKILL.md +++ b/.claude/skills/pr/SKILL.md @@ -123,7 +123,10 @@ Otherwise, after all launched subagents complete: ## Phase 5: Update changelogs -**MANDATORY — DO NOT SKIP.** Each PR must update changelogs for all packages with consumer-facing changes. +**MANDATORY — DO NOT SKIP.** Analyze the diff and determine whether any changes are consumer-facing (i.e., affect the behavior or API of a published or private package). + +- **If there are NO consumer-facing changes** (e.g., docs-only, CI, tooling, skill definitions, dev scripts): add the `no-changelog` label to the PR via `gh pr edit --add-label no-changelog` and skip the rest of this phase. +- **If there ARE consumer-facing changes**: update changelogs as described below. Read the instructions in [`docs/contributing/updating-changelogs.md`](../../../docs/contributing/updating-changelogs.md) and follow them **to the letter**. In particular: From fc7e5ff6ad420518e85f21ebe74d6ecdf079dc1d Mon Sep 17 00:00:00 2001 From: Dimitris Marlagkoutsos Date: Tue, 14 Apr 2026 18:35:50 +0200 Subject: [PATCH 3/3] fix(pr-skill): defer presenting results until after changelog phase Move the "return PR URL" instruction out of Phase 4 and into a final "Done" section after Phase 5, so an agent following the instructions sequentially won't interpret "Return" as a signal to end the workflow before updating changelogs. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/pr/SKILL.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md index 1cd531e6df..2f532a296f 100644 --- a/.claude/skills/pr/SKILL.md +++ b/.claude/skills/pr/SKILL.md @@ -117,9 +117,7 @@ Otherwise, after all launched subagents complete: **If this is a stacked PR**, add `--draft` to create it as a draft PR. -2. Note the PR number from the created PR URL — it is needed for changelog entries. - -3. Return the PR URL and any relevant information. If a review was performed, include the review summary. +2. Note the PR number from the created PR URL — it is needed for changelog entries. Proceed to Phase 5 before presenting results to the user. ## Phase 5: Update changelogs @@ -136,3 +134,7 @@ Read the instructions in [`docs/contributing/updating-changelogs.md`](../../../d - **Link the PR.** Use the PR number from Phase 4 in each entry (e.g. `([#123](https://github.com/.../pull/123))`). Commit the changelog updates to the current branch with the message "docs: Update changelogs" and push. + +## Done + +Present the PR URL and any relevant information to the user. If a review was performed, include the review summary.