create-changelog

Create a changelog entry for the work on the current Git branch. The entry is registered by running:

just changelog add --domain {domain} --type {type} --message '{message}'

Workflow

Follow these steps in order. Do not skip ahead — the user confirms before anything is committed.

1. Gather the diff

Run these commands from the repository root to understand what has changed on this branch relative to develop:

git rev-parse --abbrev-ref HEAD
git diff --name-status develop...HEAD
git diff --stat develop...HEAD
git log develop..HEAD --oneline

develop...HEAD (three dots) gives the changes introduced on this branch since it diverged from develop, which is what a changelog entry should describe.

If any of the following is true, stop and tell the user there's nothing to changelog:

• git diff --name-status develop...HEAD is empty.
• The current branch is develop itself, or is main/master.
• develop does not exist as a ref (in which case mention it and ask how they'd like to proceed).

If the diff is large enough that the file list alone isn't informative, also peek at git diff develop...HEAD -- <path> for a few of the most-changed files to get a sense of the substance of the change. Prefer looking at a handful of representative files over dumping the entire diff.

2. Pick the domain

The domain must be exactly one of: core, database, dashboard, builder, automation, integration. These correspond to modules in the codebase.

Choose the domain with the most changed files. Use directory names and file paths as the primary signal — e.g. files under a dashboard/ directory belong to dashboard. If paths are ambiguous, fall back to the substance of the changes (e.g. migration files → database, webhook/third-party API code → integration).

If there's a close tie, prefer the domain that contains the change with the most lines modified, or the one the branch name and commit messages most clearly point at. Don't overthink it — pick the single best match.

3. Pick the type

The type must be exactly one of: bug, feature, refactor, breaking_change.

Rough guide:

• bug — fixes incorrect behavior. Signals: commit messages with "fix", "bug", "regression"; small targeted changes; tests added alongside a fix.
• feature — adds capability that wasn't there before. Signals: new files, new endpoints, new UI, new configuration options.
• refactor — reshapes existing code without changing behavior. Signals: moves/renames, no new functionality, no bug being fixed, tests largely unchanged.
• breaking_change — changes that require consumers to update. Signals: removed/renamed public APIs, changed function signatures, database migrations that drop columns, config format changes.

A breaking change beats the other labels when it applies — if a refactor removes a public function, it's a breaking_change. Otherwise, pick the single best fit and move on.

4. Write the message

The message describes what changed, in plain English, for a mixed audience of developers and non-technical users reading a public changelog.

Rules:

• Max 100 characters, including spaces. Count them.
• Plain English, no jargon, no internal code names, no file paths, no class names.
• Present tense, sentence case, no trailing period. Start with a verb when natural.
• Describe the user-visible effect, not the implementation. "Speeds up dashboard loading" beats "Adds index to dashboard_widgets.user_id".
• Don't start with the type or domain (e.g. don't write "Fix: ..." — the type and domain are separate fields).
• Single line, no newlines.

Examples:

Good:

• Dashboards now load faster when you have many widgets
• Fixes an error that could lose changes when saving automations
• Adds a bulk import option for contacts

Too technical:

• Refactor DashboardWidget.render() to use memoization
• Patch NPE in AutomationSaver.persist()

Too vague:

• Various improvements
• Bug fixes

5. Show the proposal and get confirmation

Present the chosen values to the user in this exact shape so they're easy to scan:

Domain:  <domain>
Type:    <type>
Message: <message>

Follow with a one- or two-sentence rationale explaining why you picked that domain and type (e.g. "7 of 9 changed files are under builder/, and the branch adds a new step type, so I called it a new feature.") and then the full command that will be run:

just changelog add --domain <domain> --type <type> --message '<message>'

Ask the user to confirm, or to tell you what to change. If they ask for changes, redo whichever steps are affected and present an updated proposal — don't run the command until the user explicitly confirms.

6. Execute

Once the user confirms, run the command:

just changelog add --domain <domain> --type <type> --message '<message>'

Wrap the message in single quotes so apostrophes, spaces, and punctuation pass through correctly. If the message itself contains a single quote, close-escape-open it ('\'') or rewrite the message to avoid it — preferably the latter, since changelog messages rarely need apostrophes.

The issue number is automatically extracted from the branch name (e.g. a branch named 1234-fix-something yields issue 1234). If no issue number is found in the branch name, the entry is created without one.

Show the command's output to the user and confirm it succeeded. If just errors (for example, the arguments aren't accepted), surface the error and offer to adjust and retry.

Notes

• If the user runs this skill multiple times in one session with different intents, re-run the diff — don't reuse cached results, because the branch state may have changed.