From cad18c785f2b303bce2ed6ae2ca2b0d69fe02237 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sat, 28 Mar 2026 23:52:10 -0700 Subject: [PATCH] feat: extract CHANGELOG_WORKFLOW resolver from /ship Move changelog generation logic into a reusable resolver. The resolver is changelog-only (no version bump per Codex review recommendation). Adds voice rules inline. /ship Step 5 now uses {{CHANGELOG_WORKFLOW}}. Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/resolvers/index.ts | 3 ++- scripts/resolvers/utility.ts | 44 ++++++++++++++++++++++++++++++++++++ ship/SKILL.md | 3 ++- ship/SKILL.md.tmpl | 41 +-------------------------------- 4 files changed, 49 insertions(+), 42 deletions(-) diff --git a/scripts/resolvers/index.ts b/scripts/resolvers/index.ts index c2f3157f..7ac7f1a2 100644 --- a/scripts/resolvers/index.ts +++ b/scripts/resolvers/index.ts @@ -12,7 +12,7 @@ import { generateCommandReference, generateSnapshotFlags, generateBrowseSetup } import { generateDesignMethodology, generateDesignHardRules, generateDesignOutsideVoices, generateDesignReviewLite, generateDesignSketch, generateDesignSetup, generateDesignMockup, generateDesignShotgunLoop } from './design'; import { generateTestBootstrap, generateTestCoverageAuditPlan, generateTestCoverageAuditShip, generateTestCoverageAuditReview } from './testing'; import { generateReviewDashboard, generatePlanFileReviewReport, generateSpecReviewLoop, generateBenefitsFrom, generateCodexSecondOpinion, generateAdversarialStep, generateCodexPlanReview, generatePlanCompletionAuditShip, generatePlanCompletionAuditReview, generatePlanVerificationExec } from './review'; -import { generateSlugEval, generateSlugSetup, generateBaseBranchDetect, generateDeployBootstrap, generateQAMethodology, generateCoAuthorTrailer } from './utility'; +import { generateSlugEval, generateSlugSetup, generateBaseBranchDetect, generateDeployBootstrap, generateQAMethodology, generateCoAuthorTrailer, generateChangelogWorkflow } from './utility'; import { generateLearningsSearch, generateLearningsLog } from './learnings'; import { generateConfidenceCalibration } from './confidence'; import { generateInvokeSkill } from './composition'; @@ -55,4 +55,5 @@ export const RESOLVERS: Record = { LEARNINGS_LOG: generateLearningsLog, CONFIDENCE_CALIBRATION: generateConfidenceCalibration, INVOKE_SKILL: generateInvokeSkill, + CHANGELOG_WORKFLOW: generateChangelogWorkflow, }; diff --git a/scripts/resolvers/utility.ts b/scripts/resolvers/utility.ts index 660e4ec5..e6167d02 100644 --- a/scripts/resolvers/utility.ts +++ b/scripts/resolvers/utility.ts @@ -375,3 +375,47 @@ export function generateCoAuthorTrailer(ctx: TemplateContext): string { } return 'Co-Authored-By: Claude Opus 4.6 '; } + +export function generateChangelogWorkflow(_ctx: TemplateContext): string { + return `## CHANGELOG (auto-generate) + +1. Read \`CHANGELOG.md\` header to know the format. + +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 + - \`### Changed\` — changes to existing functionality + - \`### Fixed\` — bug fixes + - \`### Removed\` — removed features + - Write concise, descriptive bullet points + - Insert after the file header (line 5), dated today + - Format: \`## [X.Y.Z.W] - YYYY-MM-DD\` + - **Voice:** Lead with what the user can now **do** that they couldn't before. Use plain language, not implementation details. Never mention TODOS.md, internal tracking, or contributor-facing details. + +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.`; +} diff --git a/ship/SKILL.md b/ship/SKILL.md index a4ff1bd2..f8781721 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -1714,7 +1714,7 @@ already knows. A good test: would this insight save time in a future session? If --- -## Step 5: CHANGELOG (auto-generate) +## CHANGELOG (auto-generate) 1. Read `CHANGELOG.md` header to know the format. @@ -1747,6 +1747,7 @@ already knows. A good test: would this insight save time in a future session? If - Write concise, descriptive bullet points - Insert after the file header (line 5), dated today - Format: `## [X.Y.Z.W] - YYYY-MM-DD` + - **Voice:** Lead with what the user can now **do** that they couldn't before. Use plain language, not implementation details. Never mention TODOS.md, internal tracking, or contributor-facing details. 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, diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl index 98e2d8ea..e8a17251 100644 --- a/ship/SKILL.md.tmpl +++ b/ship/SKILL.md.tmpl @@ -342,46 +342,7 @@ For each classified comment: --- -## Step 5: CHANGELOG (auto-generate) - -1. Read `CHANGELOG.md` header to know the format. - -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 - - `### Changed` — changes to existing functionality - - `### Fixed` — bug fixes - - `### Removed` — removed features - - Write concise, descriptive bullet points - - 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. +{{CHANGELOG_WORKFLOW}} ---