Hk Changelog

Changelog Creator

Generate a changelog entry from git changes, prepend it to CHANGELOG.md, and optionally commit + raise a PR.

Usage

/hk-changelog              → full flow: write + commit + PR
/hk-changelog --dry-run    → print the entry only (no file changes)
/hk-changelog --commit     → write + commit (no PR)

Arguments are passed via $ARGUMENTS.

Instructions

Step 1: Parse arguments

Check $ARGUMENTS for --dry-run or --commit. Default behavior (no args) is the full flow: write, commit, and open a PR.

Step 2: Gather raw git data

Run these commands to collect the raw material. This is mechanical — just capture the output:

# What branch are we on?
git rev-parse --abbrev-ref HEAD

# Commits on this branch that aren't on main
git log main..HEAD --oneline --no-merges 2>/dev/null

# File-level summary
git diff --stat main...HEAD 2>/dev/null
git diff main...HEAD --name-status 2>/dev/null

# Unstaged/untracked
git diff --stat HEAD
git diff --name-status HEAD
git status --short | grep "^??"

If there are no commits diverging from main AND no staged/unstaged changes, tell the user there's nothing to changelog and stop.

If on main with no diverging commits, fall back to diffing against the previous commit:

git log -1 --oneline
git diff HEAD~1 --stat
git diff HEAD~1 --name-status

Also read the existing CHANGELOG.md so the subagent can match the format.

Step 3: Delegate to haiku subagent

Use the Task tool with subagent_type: "general-purpose" and model: "haiku" to do the heavy lifting. The subagent reads diffs, understands the changes, and generates the changelog entry.

Pass the subagent a prompt containing:

1. All the git output from Step 2
2. The existing CHANGELOG.md content (for format reference)
3. The full generation rules below
4. A clear instruction: "Read the actual diffs by subsystem, then generate a changelog entry. Return ONLY the markdown entry, nothing else."

The subagent prompt must include these instructions:

Read actual diffs by subsystem. File names alone are not enough — read the actual diffs to understand what changed. Group by subsystem:

# Backend / orchestrator / CLI
git diff HEAD -- odin/src/ taskit/taskit-backend/

# Frontend — read separately, easy to miss
git diff HEAD -- taskit/taskit-frontend/src/

# Types, models, migrations
git diff HEAD -- taskit/taskit-frontend/src/types/ taskit/taskit-backend/tasks/models.py taskit/taskit-backend/tasks/migrations/

# Docs and config
git diff HEAD -- odin/docs/ odin/AGENTS.md odin/claude.md odin/README.md docs/

# Tests
git diff HEAD -- odin/tests/ taskit/taskit-backend/tests/

For new untracked files, read them to understand what they add. If a diff group is very large (>500 lines), skim the first 300 lines and the --stat for that group.

Generate a changelog entry in this format:

## YYYY-MM-DD — [Short Human-Friendly Title]
**`<short-hash>`** — [plain-English summary of the theme]

### Added
- [what's new, described in terms of capability]

### Changed
- [what works differently now — user/developer impact]

### Deleted
- [what's gone]

---

Rules:

• Completeness over brevity. Every meaningful change should appear. Someone reading the changelog should understand everything that shipped without looking at the diff.
• Use today's date and the latest commit's short hash (or "unstaged" for uncommitted work)
• Only include sections (Added/Changed/Deleted) that have entries — omit empty ones
• Write for humans, not machines. Say "Added executing time tracking to task cards" not "Added executingTimeMs field to Task type in types/index.ts"
• Describe what changed and why it matters, not which files were touched
• Scale detail to changeset size:
  • Small changeset (1-5 files): 2-4 bullets
  • Medium changeset (5-20 files): 5-10 bullets
  • Large changeset (20+ files): 10-20 bullets, organized by area if helpful
• Don't collapse distinct changes into one bullet. If the frontend got a new component AND the backend got a new comment type AND the CLI got restructured, those are three bullets.
• Frontend changes deserve their own bullets. New components, UX changes (e.g. multi-select → single-select), new fields on forms, visual changes (badges, icons, colors) — each gets called out.
• Backend and API changes deserve their own bullets. New fields on models/types, new API parameters, changed parsing logic, new migrations.
• Include file paths only when the file IS the feature (e.g. a new config module, a new migration)
• Match the tone and format of the existing CHANGELOG.md entries provided