---
name: code-changelog
description: >
  Add a changelog entry in the changelogs/ directory. Use when the user says
  /code-changelog, /changelog, 'add changelog', 'changelog entry', or needs to document
  a change for the next release.
argument-hint: "[optional: description override]"
allowed-tools:
  - Bash
---

Create a changelog entry file in the `changelogs/` directory.

**CRITICAL — read carefully:**

- **Always use the script below.** It is the *only* sanctioned way to create or modify a file under `changelogs/`. The script resolves the correct filename from `mr_source_branch` via `detect_context` and emits the strict format `* <type>: <description> (#<iid>)`.
- **Never use `Write`, `Edit`, `cat >`, `echo >`, or any other tool to create, overwrite, or amend a file under `changelogs/`.** Even if the script's output looks too short, truncated, or imperfect — do not "fix it up" manually. If the result is wrong, re-run the script with a better `--type` or description argument, or report the issue to the user. Hand-written entries silently break the format (`* #IID Description...` instead of `* type: description (#IID)`) and the release pipeline.
- **Never include `(#IID)` in the description argument** — the script appends it.
- **`description` is a positional argument, not a flag.** There is no `--description` option — pass the text directly after the options, quoted.

```bash
pysae-ai-tools code changelog generate --write --json "description from $ARGUMENTS"
```

To validate all entries in `changelogs/` against strict conventional commits format
(optionally auto-fixing non-conforming entries):

```bash
pysae-ai-tools code changelog validate           # lint only
pysae-ai-tools code changelog validate --fix     # lint + auto-fix
```

The script handles everything automatically:
- Filename: `changelogs/<mr_source_branch>.md` (with `/` replaced by `-`), fallback to `git_branch`
- Type: issue `type::*` label > branch prefix > commit prefix > `tech`
- Description: issue title > MR title > commit message > branch slug
- Issue ref `(#IID)`: added automatically — **never include `(#IID)` in the description**

**Length budget.** Total entry length (prefix `* ` included) must be ≤ 122 chars.
If the resolved description blows the budget, the script exits 1 and emits an
error JSON of the form:

```json
{
  "error": "description_too_long",
  "current_length": 145,
  "max_total_length": 122,
  "max_description_length": 109,
  "type": "feat",
  "issue_iid": "123",
  "description": "<original description that was too long>",
  "content": "<the full over-budget entry>"
}
```

When you get this error, **rewrite the description yourself** so it fits within
`max_description_length` characters (keep meaning, drop filler words), then
re-run the same command with the shorter text as `$ARGUMENTS`. Do *not* simply
chop the original — produce a clean, idiomatic shorter description. Repeat
until the script succeeds.

Display the JSON output to the user. Do not commit.

$ARGUMENTS
