---
name: "dev-changelog-gen"
description: "Genera o aggiorna CHANGELOG.md leggendo git log e raggruppando commit per tipo Conventional Commits. Usa quando l'utente dice 'aggiorna changelog', 'genera changelog', 'update changelog', 'popola unreleased', 'crea release nel changelog', oppure prima di un tag/release per consolidare le entry. Skill generica: funziona su qualsiasi repo git con Conventional Commits, senza hardcoding specifico al progetto."
---

# /dev-changelog-gen — Generazione CHANGELOG da git log (v0.18.0)

Wrapper conversazionale su `changelog-gen.ts`. Legge `git log` dal repo corrente, classifica i commit secondo [Conventional Commits](https://www.conventionalcommits.org/), e aggiorna `CHANGELOG.md` nel formato [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

**Script sottostante**: `dev-methodology/scripts/changelog-gen.ts`

---

## Modalità

| Flag | Comportamento |
|------|---------------|
| `--unreleased` _(default)_ | Legge i commit dopo l'ultimo tag e aggiorna/crea la sezione `[Unreleased]` |
| `--release X.Y.Z` | Rinomina `[Unreleased]` → `[X.Y.Z] - YYYY-MM-DD` + inserisce nuova `[Unreleased]` vuota sopra |
| `--dry-run` | Mostra su stdout l'entry che verrebbe scritta, senza modificare nessun file |
| `--changelog PATH` | Specifica il path al CHANGELOG.md target (default: `./CHANGELOG.md`) |
| `--repo-dir PATH` | Root del repo git (default: directory corrente) |

---

## Classificazione commit

| Tipo Conventional | Sezione CHANGELOG |
|-------------------|-------------------|
| `feat:` | **Added** |
| `fix:` | **Fixed** |
| `refactor:`, `perf:` | **Changed** |
| `docs:` | **Docs** |
| `chore:`, `ci:`, `test:` | _esclusi dalla sezione principale_ (inclusi in `other`, non mostrati) |

Commit non-Conventional vengono ignorati silenziosamente. Se tutti i commit dopo l'ultimo tag sono non-Conventional, la skill avvisa e non modifica il file.

---

## Workflow

### Step 1 — Verifica esistenza dello script

```bash
SCRIPT="dev-methodology/scripts/changelog-gen.ts"
```

Se il file non esiste:

```
changelog-gen.ts non trovato. Esegui bash install.sh --update per aggiornare il plugin.
```

Termina qui.

### Step 2 — Determina modalità e parametri

Identifica la modalità dall'input dell'utente:

- Contiene `--unreleased` o nessuna modalità esplicita → `--unreleased`
- Contiene `--release X.Y.Z` → `--release X.Y.Z`
- Contiene `--dry-run` → aggiungi al comando
- Contiene `--changelog PATH` → aggiungi al comando
- Contiene `--repo-dir PATH` → aggiungi al comando

### Step 3 — Esegui lo script

```bash
npx tsx dev-methodology/scripts/changelog-gen.ts \
  [--unreleased | --release X.Y.Z] \
  [--changelog PATH] \
  [--dry-run] \
  [--repo-dir PATH]
```

Cattura stdout, stderr e exit code.

**Exit codes attesi**:
- `0` — OK (anche con 0 commit Conventional — in quel caso warning su stderr)
- `1` — errore utente (git non disponibile, directory non è un repo)
- `2` — errore interno

### Step 4 — Presenta output conversazionale

#### Se exit code 0 — modalità `--unreleased` (file scritto)

```
CHANGELOG.md aggiornato.

Sezione [Unreleased] popolata con N commit dopo {ultimo-tag}:
  Added: M entry (feat:)
  Fixed: K entry (fix:)
  Changed: J entry (refactor:/perf:)
  Docs: L entry (docs:)

File: ./CHANGELOG.md
```

#### Se exit code 0 — modalità `--release X.Y.Z` (file scritto)

```
CHANGELOG.md aggiornato.

[Unreleased] → [X.Y.Z] - YYYY-MM-DD
Nuova sezione [Unreleased] vuota inserita.

File: ./CHANGELOG.md
```

#### Se exit code 0 — `--dry-run`

Mostra direttamente lo stdout dello script (il markdown della sezione) senza ulteriori elaborazioni.

```
Dry-run — nessun file modificato. Entry che verrebbe scritta:

{output stdout}
```

#### Se exit code 0 con warning su stderr (0 commit Conventional)

```
Nessun commit Conventional trovato dopo {tag}.

Il CHANGELOG non è stato modificato.
Per abilitare la generazione automatica, usa il formato:
  feat: descrizione
  fix: descrizione
  docs: descrizione
```

#### Se exit code 1 (git non disponibile)

```
Errore: {messaggio da stderr}

Verifica:
  1. git è nel PATH: which git
  2. Sei nella root di un repo git: git status
```

#### Se exit code 0 — prima esecuzione (CHANGELOG.md creato)

Se stdout contiene `creato (prima esecuzione)`:

```
CHANGELOG.md non esisteva — creato con header Keep a Changelog standard.
Sezione [Unreleased] popolata con i commit trovati.
```

---

## Esempi

### Esempio 1 — Aggiorna [Unreleased]

```
User: /dev-changelog-gen --unreleased

Skill:
  → Trova changelog-gen.ts
  → Esegue: npx tsx ... --unreleased --changelog ./CHANGELOG.md
  → Exit code: 0

Output:
  CHANGELOG.md aggiornato.

  Sezione [Unreleased] popolata con 8 commit dopo v0.17.0:
    Added: 3 entry (feat:)
    Fixed: 2 entry (fix:)
    Changed: 1 entry (refactor:)
    Docs: 2 entry (docs:)
```

### Esempio 2 — Crea release

```
User: /dev-changelog-gen --release 0.18.0

Skill:
  → Esegue: npx tsx ... --release 0.18.0 --changelog ./CHANGELOG.md
  → Exit code: 0

Output:
  CHANGELOG.md aggiornato.

  [Unreleased] → [0.18.0] - 2026-05-15
  Nuova sezione [Unreleased] vuota inserita.
```

### Esempio 3 — Dry-run

```
User: /dev-changelog-gen --unreleased --dry-run

Skill:
  → Esegue: npx tsx ... --unreleased --dry-run
  → Nessun file modificato

Output:
  Dry-run — nessun file modificato. Entry che verrebbe scritta:

  ## [Unreleased]

  ### Added
  - aggiunta skill dev-changelog-gen

  ### Fixed
  - corretto bug nel parser YAML
```

### Esempio 4 — CHANGELOG brainstorming

```
User: /dev-changelog-gen --unreleased --changelog brainstorming/CHANGELOG.md

Skill:
  → Esegue: npx tsx ... --unreleased --changelog brainstorming/CHANGELOG.md
  → Exit code: 0

Output:
  CHANGELOG.md aggiornato.
  File: brainstorming/CHANGELOG.md
```

### Esempio 5 — 0 commit Conventional

```
User: /dev-changelog-gen --unreleased

Skill:
  → Exit code: 0 (con warning su stderr)

Output:
  Nessun commit Conventional trovato dopo v0.17.0.

  Il CHANGELOG non è stato modificato.
  Per abilitare la generazione automatica, usa il formato:
    feat: descrizione
    fix: descrizione
    docs: descrizione
```

---

## Note tecniche

- **Atomic write**: il file viene scritto su un `.tmp` e poi rinominato — nessuna corruzione in caso di crash
- **Preservazione**: il contenuto storico (versioni passate) non viene mai sovrascritto
- **Prima esecuzione**: se `CHANGELOG.md` non esiste, viene creato con header Keep a Changelog standard
- **Zero dipendenze**: lo script usa solo Node.js builtins e `git` (già nel PATH su qualsiasi macchina di sviluppo)
- **Generica**: nessun hardcoding al progetto MUCC — riusabile su qualsiasi repo git

---

## Riferimenti

- Script: `dev-methodology/scripts/changelog-gen.ts`
- Spec: Keep a Changelog 1.1.0 — https://keepachangelog.com/en/1.1.0/
- Conventional Commits 1.0.0 — https://www.conventionalcommits.org/
- Story: US-AC04 (v0.18.0 Sprint 2, cluster CHANGELOG)