/prowler-changelog

name: prowler-changelog
description: >
  Manages Prowler changelog entries as towncrier fragments (`<component>/changelog.d/<slug>.<type>.md`) compiled into keepachangelog-style CHANGELOG.md files at release time.
  Trigger: When creating PRs, adding changelog entries or fragments, fixing a failing changelog gate, or working with changelog.d/ or CHANGELOG.md in ui/, api/, mcp_server/, or prowler/.
license: Apache-2.0
metadata:
  author: prowler-cloud
  version: "2.1"
  scope: [root, ui, api, sdk, mcp_server]
  auto_invoke:
    - "Add changelog entry for a PR or feature"
    - "Add or edit changelog fragments in <component>/changelog.d/"
    - "Create PR that requires changelog entry"
    - "Review changelog format and conventions"
allowed-tools: Read, Edit, Write, Glob, Grep, Bash

How changelog entries work: fragments

A PR never edits `CHANGELOG.md` directly: the PR gate fails on any change to a component `CHANGELOG.md` (only exception: released-block corrections with the `no-changelog` label, see below). Instead, add one small **fragment file** per entry under the component's `changelog.d/`. At release time [towncrier](https://towncrier.readthedocs.io/) compiles the fragments into `CHANGELOG.md` and deletes them, so concurrent PRs never conflict.

| Component | Fragments directory | Compiled file | towncrier config | |-----------|---------------------|---------------|------------------| | SDK | `prowler/changelog.d/` | `prowler/CHANGELOG.md` | `prowler/towncrier.toml` | | API | `api/changelog.d/` | `api/CHANGELOG.md` | `api/towncrier.toml` | | UI | `ui/changelog.d/` | `ui/CHANGELOG.md` | `ui/towncrier.toml` | | MCP Server | `mcp_server/changelog.d/` | `mcp_server/CHANGELOG.md` | `mcp_server/towncrier.toml` |

All four configs share the template `.github/towncrier/template.md.jinja`. "What's unreleased" = "what's in `changelog.d/`". The compiled `CHANGELOG.md` files contain only released versions.

Fragment filename

<slug>.<type>.md

• `<slug>`: free-form, `[A-Za-z0-9][A-Za-z0-9._-]*`, descriptive of the change (e.g. `securityhub-delegated-admin`). Prefer a descriptive slug.
• An all-digit slug is taken literally as the PR number (`.github/scripts/changelog_attribution.py` skips PR lookup for it), so use `13245.fixed.md` only when you know the real PR number.
• `<type>` maps 1:1 to the sections (from `towncrier.toml`):

| `<type>` | Section | Usage | |----------|---------|-------| | `added` | `### 🚀 Added` | New features, checks, endpoints | | `changed` | `### 🔄 Changed` | Modifications to existing functionality | | `deprecated` | `### ⚠️ Deprecated` | Features marked for removal | | `removed` | `### ❌ Removed` | Deleted features (major releases only) | | `fixed` | `### 🐞 Fixed` | Bug fixes | | `security` | `### 🔐 Security` | Security patches, CVE fixes, vulnerable dependency bumps |

• The gate regex also accepts an optional numeric counter (`<slug>.<type>.<N>.md`); you never need it, the compile step adds it on collisions.
• One file per entry. A PR touching Added, Changed and Fixed ships `kms-rotation-check.added.md` + `kms-metadata-cache.changed.md` + `kms-disabled-keys.fixed.md`; all compile with the same PR link into their own sections.
• Several entries of the SAME type: a different slug per entry (`kms-rotation-check.added.md`, `kms-rotation-docs.added.md`).
• At least one fragment per touched component.

Fragment content

The file contains ONLY the entry text, exactly as it should appear in the changelog, on a single line ending with a newline:

echo '`securityhub_delegated_admin_enabled_all_regions` check for AWS provider, verifying that Security Hub has a delegated administrator, is active in all opted-in regions, and has organization auto-enable on' > prowler/changelog.d/securityhub-delegated-admin.added.md

**Rules:**

• **NEVER write a PR or issue link.** The compile workflow resolves the PR that added the fragment from git history and appends `[(#NNNN)](...)`. The gate fails on `[(#N)]`, `[#N](`, `(#N)` and any `github.com/<owner>/<repo>/pull|issues/N` URL.
• No period at the end
• Do NOT start with redundant verbs (the section header already provides the action)
• Be specific: what changed, not why (that's in the PR)
• Use spaces around inline code and product names; wrap check IDs, endpoints, commands, errors, task names and file paths in backticks
• Avoid run-on sentences: one concise result plus at most one context clause

Good fragments

# ui/changelog.d/provider-search-bar.added.md
Search bar when adding a provider

# api/changelog.d/scan-dispatch-race.fixed.md
`POST /api/v1/scans` no longer intermittently fails with `Scan matching query does not exist`; scan dispatch now publishes the `scan-perform` Celery task after the transaction commits

# prowler/changelog.d/pyasn1-joserfc-cves.security.md
pyasn1 to 0.6.5 and joserfc to 1.7.5 in the SDK, patching the ASN.1 decoding and JWE decryption denial of service advisories

Bad fragments

Fixed bug.                              # Too vague, has period, redundant verb
Add search bar                          # Redundant verb (the section already says "Added")
Search bar [(#9634)](https://github.com/prowler-cloud/prowler/pull/9634)   # NEVER include the PR link; the gate fails

Mandatory Human Confirmation Gate

Before creating or editing any changelog fragment or `CHANGELOG.md` file, the agent MUST stop and get explicit user confirmation. This applies even when the changelog gate is failing, the required file seems obvious, or the user asked to "fix the changelog".

Present the proposed action before writing:

1. Target fragment path (component, slug, type) or CHANGELOG.md edit. 2. Exact entry text. 3. Reason the changelog entry is needed.

Only proceed after an explicit approval such as "confirm", "approved", "sí", or equivalent. If the user rejects or does not answer, do not create or edit anything. Offer alternatives such as adding `no-cha