diff --git a/ship/SKILL.md b/ship/SKILL.md
index a3e0b325..13a313cf 100644
--- a/ship/SKILL.md
+++ b/ship/SKILL.md
@@ -1546,10 +1546,26 @@ High-confidence findings (agreed on by multiple sources) should be prioritized f
1. Read `CHANGELOG.md` header to know the format.
-2. Auto-generate the entry from **ALL commits on the branch** (not just recent ones):
- - Use `git log ..HEAD --oneline` to see every commit being shipped
- - Use `git diff ...HEAD` to see the full diff against the base branch
- - The CHANGELOG entry must be comprehensive of ALL changes going into the PR
+2. **First, enumerate every commit on the branch:**
+ ```bash
+ git log ..HEAD --oneline
+ ```
+ Copy the full list. Count the commits. You will use this as a checklist.
+
+3. **Read the full diff** to understand what each commit actually changed:
+ ```bash
+ git diff ...HEAD
+ ```
+
+4. **Group commits by theme** before writing anything. Common themes:
+ - New features / capabilities
+ - Performance improvements
+ - Bug fixes
+ - Dead code removal / cleanup
+ - Infrastructure / tooling / tests
+ - Refactoring
+
+5. **Write the CHANGELOG entry** covering ALL groups:
- If existing CHANGELOG entries on the branch already cover some commits, replace them with one unified entry for the new version
- Categorize changes into applicable sections:
- `### Added` — new features
@@ -1560,6 +1576,11 @@ High-confidence findings (agreed on by multiple sources) should be prioritized f
- Insert after the file header (line 5), dated today
- Format: `## [X.Y.Z.W] - YYYY-MM-DD`
+6. **Cross-check:** Compare your CHANGELOG entry against the commit list from step 2.
+ Every commit must map to at least one bullet point. If any commit is unrepresented,
+ add it now. If the branch has N commits spanning K themes, the CHANGELOG must
+ reflect all K themes.
+
**Do NOT ask the user to describe changes.** Infer from the diff and commit history.
---
@@ -1697,7 +1718,12 @@ The PR/MR body should contain these sections:
```
## Summary
-
+..HEAD --oneline` to enumerate
+every commit. Exclude the VERSION/CHANGELOG metadata commit (that's this PR's bookkeeping,
+not a substantive change). Group the remaining commits into logical sections (e.g.,
+"**Performance**", "**Dead Code Removal**", "**Infrastructure**"). Every substantive commit
+must appear in at least one section. If a commit's work isn't reflected in the summary,
+you missed it.>
## Test Coverage
diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl
index 7f545cd9..6cbe66bd 100644
--- a/ship/SKILL.md.tmpl
+++ b/ship/SKILL.md.tmpl
@@ -339,10 +339,26 @@ For each classified comment:
1. Read `CHANGELOG.md` header to know the format.
-2. Auto-generate the entry from **ALL commits on the branch** (not just recent ones):
- - Use `git log ..HEAD --oneline` to see every commit being shipped
- - Use `git diff ...HEAD` to see the full diff against the base branch
- - The CHANGELOG entry must be comprehensive of ALL changes going into the PR
+2. **First, enumerate every commit on the branch:**
+ ```bash
+ git log ..HEAD --oneline
+ ```
+ Copy the full list. Count the commits. You will use this as a checklist.
+
+3. **Read the full diff** to understand what each commit actually changed:
+ ```bash
+ git diff ...HEAD
+ ```
+
+4. **Group commits by theme** before writing anything. Common themes:
+ - New features / capabilities
+ - Performance improvements
+ - Bug fixes
+ - Dead code removal / cleanup
+ - Infrastructure / tooling / tests
+ - Refactoring
+
+5. **Write the CHANGELOG entry** covering ALL groups:
- If existing CHANGELOG entries on the branch already cover some commits, replace them with one unified entry for the new version
- Categorize changes into applicable sections:
- `### Added` — new features
@@ -353,6 +369,11 @@ For each classified comment:
- Insert after the file header (line 5), dated today
- Format: `## [X.Y.Z.W] - YYYY-MM-DD`
+6. **Cross-check:** Compare your CHANGELOG entry against the commit list from step 2.
+ Every commit must map to at least one bullet point. If any commit is unrepresented,
+ add it now. If the branch has N commits spanning K themes, the CHANGELOG must
+ reflect all K themes.
+
**Do NOT ask the user to describe changes.** Infer from the diff and commit history.
---
@@ -490,7 +511,12 @@ The PR/MR body should contain these sections:
```
## Summary
-
+..HEAD --oneline` to enumerate
+every commit. Exclude the VERSION/CHANGELOG metadata commit (that's this PR's bookkeeping,
+not a substantive change). Group the remaining commits into logical sections (e.g.,
+"**Performance**", "**Dead Code Removal**", "**Infrastructure**"). Every substantive commit
+must appear in at least one section. If a commit's work isn't reflected in the summary,
+you missed it.>
## Test Coverage