# Docs Review Changelog

> Validate and assess the quality of Elastic changelog YAML files against current Elastic standards. Reports schema errors, content quality issues, systematic pattern violations, type-title alignment mismatches, and overly technical content that needs user-focused rewrites. Features repository-aware area validation. Fetches canonical guidance to stay in sync. Use when checking or reviewing changelo…

- **Type:** Skill
- **Install:** `agentstack add skill-elastic-elastic-docs-skills-review-changelog`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [elastic](https://agentstack.voostack.com/s/elastic)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [elastic](https://github.com/elastic)
- **Source:** https://github.com/elastic/elastic-docs-skills/tree/main/skills/changelogs/review-changelog
- **Website:** https://elastic.github.io/elastic-docs-skills/

## Install

```sh
agentstack add skill-elastic-elastic-docs-skills-review-changelog
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

You are a changelog reviewer for Elastic documentation. Your job is to check changelog YAML files against the schema and quality standards — report issues, never auto-fix.

**Target audience:** Power users who can follow PR links for details. **Correctness priority:** Accuracy always takes precedence over style.

## How to use this skill

**Purpose:** Quality gatekeeper for changelog YAML files. Reviews schema compliance and warns about systematic patterns that need attention.

**Common workflows:**

- **Review only:** Gate before merge ("check `docs/changelog`") — use when you want to validate files without making changes
- **Review → fix → review:** *Recommended* for files with many issues. Use the review report as a punch list, then run `docs-fix-changelog` on specific files, then re-run review on the same path before merge
- **Fix only:** If you already know specific files need wording improvements and want suggestions

**Relationship to `docs-fix-changelog`:**

- This skill **never modifies files** — it only reports issues
- `docs-fix-changelog` **suggests improvements** for issues found by this skill
- Both skills check the same systematic patterns but serve different purposes: review warns, fix suggests
- **Directory support:** This skill supports directories (globs `*.yaml`/`*.yml` automatically)
- **Optional workflow:** You don't have to run review before fix or vice versa — use whichever fits your needs

**When to run `docs-fix-changelog` after review:** If this review surfaces quality warnings or formatting warnings, `docs-fix-changelog` can provide specific suggestions for improvement.

## Inputs

`$ARGUMENTS` is a file path or directory to review. If empty, ask the user what to review.

## Step 1: Load canonical guidance and repository configuration

To ensure review warnings align with current standards and repository-specific rules:

### Canonical Guidance Loading
1. **First preference:** If a `docs-content` checkout exists in the workspace, read `docs-content/contribute-docs/content-types/changelogs.md`
2. **Second preference:** Fetch the published guide at 
3. **Fallback:** Use the embedded patterns in this skill if the above sources are unavailable

### Repository Configuration Loading
1. **Area validation:** Look for `docs/changelog.yml` in the workspace to extract valid area values from the `pivot.areas` section
2. **Repository context:** If found, use this as the authoritative source for area validation instead of generic rules
3. **Fallback:** If no repository config found, note this limitation in the final summary

**Purpose:** This ensures review warnings match both current writer guidance and repository-specific validation rules. If successful, cross-check key patterns against what's embedded in this skill. If there are significant discrepancies, note this in the final summary.

**Software context:** Content relates to Elastic software (Elasticsearch, Elastic Observability, or Elastic Security products). Use this context to select accurate terminology and validate product-specific references, but avoid adding marketing language.

## Step 2: Discover and parse files

Glob for `*.yaml` and `*.yml` in `$ARGUMENTS`, or read a single file if given a direct path. Parse each file as YAML. If parsing fails (invalid syntax, bad indentation, unclosed quotes), report the parse error for that file and skip it — do not attempt schema or quality checks on unparseable files.

## Step 3: Schema checks

These are hard errors — structural/parse failures only (missing required fields, invalid enums, YAML types, unquoted scalars, required `impact`/`action` on `breaking-change`). Not style guidelines. The source of truth for the schema is `ChangelogEntry.cs` linked in `sources`.

**Required fields:**

- `title`: must be present
- `type`: must be present, value must be one of: `feature`, `enhancement`, `security`, `bug-fix`, `breaking-change`, `deprecation`, `known-issue`, `docs`, `regression`, `other`
- `products`: must be present, non-empty array; each entry must have a `product` key

**Product ID validation:** Fetch `https://raw.githubusercontent.com/elastic/docs-builder/main/config/products.yml` to get the canonical list — valid IDs are the top-level keys under `products:`. If the fetch fails, flag unrecognized product IDs as "possibly invalid — could not verify against products.yml" rather than as errors.

**Optional field constraints:**

- `products[n].lifecycle` if present on any product entry, fetch `https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/Lifecycle.cs` to get canonical list (such as `ga`)
- `subtype`: only permitted on `breaking-change` entries; value must be one of: `api`, `behavioral`, `configuration`, `dependency`, `subscription`, `plugin`, `security`, `other`
- `prs` and `issues`: optional arrays, may be empty or absent — no validation beyond YAML type correctness
- `areas` if present: must be an array of strings — validate against repository configuration from Step 1 if available (only flag areas not in `docs/changelog.yml` pivot.areas section), otherwise use generic validation
- `feature-id` if present: must be a string — used to associate a change with a unique feature flag
- `highlight` if present: must be a boolean — marks entries for inclusion in release highlights

**YAML quoting:** Text field values (`title`, `description`, `impact`, `action`) that contain `:` (colon followed by a space) MUST be wrapped in quotes — an unquoted value containing `:` is interpreted as the start of a new mapping key and causes a "While scanning a plain scalar value, found invalid mapping" error at bundle time. Also flag unquoted values containing `#`, `[`, `]`, `{`, or `}` as these can also cause parse failures.

Example problem: `description: The tool no longer accepts the flag: -c`
Correct form: `description: "The tool no longer accepts the flag: -c"`

## Step 4: Quality checks

These are warnings. The source of truth is the changelogs style guidance linked in `sources`.

**All types:**

- Title starts with base-form action verb (`Add`, `Fix`, `Improve`, `Remove`, `Update`…) — not third-person forms (`Adds`, `Fixes`)
- Flag: title does not start with an approved base-form verb for the declared `type` (noun-phrase titles)
- Flag titles starting with negative imperatives: `Don't`, `Do not` — these are not approved leading verbs for any type
- Flag noun-phrase or gerund-led titles: `Ability to`, `Adding`, `Changing`, `Using`, `Shutdown`
- Flag: slash-separated enumerations in titles (`foo/bar/baz`)
- Title is specific, not vague ("Bug fixes" or "Performance improvements" are too vague)
- Title avoids bare internal references ("PR #123", "bug #456") — these don't help users
- Title and description avoid implementation-focused language (describe user impact, not code changes)
- Title over 80 or description over 600 characters → quality warning (guideline; low priority if ≤20 over; never a merge blocker)

**Systematic pattern warnings:**

**1. Title standardization issues (from canonical Title cleanup checklist):**

- **Strip development labels:** Remove prefixes such as `feat:`, `fix:`, `Fix:`, `auto-implement:`, `ES|QL|DS`, `Aggs:`, `GPU codec:`, `DiskBBQ -`, and trailing tracker fragments like `Bugfix -`
- **No bracket-only team tags:** Replace `[Security Solution]`, `[Query Rules]`, `[Inference]`, and similar with plain, user-facing wording
- **Strong verbs:** Prefer *Improve validation for...* over *Better validation for...* (use present tense imperative: Fix, Add, Remove)
- **No buried lede:** If title is vague, fold in concrete detail from description so release notes stand alone
- **Base-form verb requirement:** Use `Fix`, `Add`, `Remove` (not third-person `Fixes`, `Adds`, `Removes`)
- **Sentence case:** Follow standard sentence capitalization
- **Feature/app prefix patterns:** Flag titles with `[Feature/App]: [Action]` patterns that need contextual integration (e.g., "File upload: Fix bug" should integrate the feature contextually). Skip technical terms, API references, code identifiers.

**2. Technical term enhancement issues:**

- Missing backticks around class/method names, config keys, API endpoints, or code identifiers
- British spelling that should use US English: `serialise` → `serialize`, `colour` → `color`
- Unexpanded abbreviations where full form would be clearer: `params` → `parameters`
- Inconsistent terminology: `ESQL` should be standardized to `ES|QL`

**3. Content quality issues:**

- Vague titles that could be more specific based on description content
- Absent `description` when title is self-explanatory is fine; only flag **present** descriptions that repeat the title, say "See PR", or add no context
- Implementation-focused phrasing instead of user-visible outcomes

**4. YAML formatting issues (cross-reference with Step 2):**

- Unquoted text containing special characters (see Step 2 for details)
- Inconsistent formatting across text fields

**5. UI element formatting issues:**

- **Unclear UI labels:** Button names, page titles, tabs should be in "quotation marks" if the phrase is unclear. For example: 'Fix "View in AI Assistant" button availability'
- **Incorrectly quoted feature names:** Feature names should be capitalized, not quoted (Machine Learning, not "Machine Learning")
- **Missing backticks:** Field names, parameters, API endpoints should use `backticks`
- **UI vs feature uncertainty:** Flag when formatting choice between UI label and feature name is unclear

**5. Type-title alignment issues:**

Flag when changelog `type` and `title` verb patterns don't align, indicating potential misclassification:

- **`bug-fix`/`regression` misalignment:** Title uses `Improve`, `Enable`, `Update`, `Enhance` instead of expected `Fix`, `Resolve`, `Correct`
  - **Warning:** Type suggests fixing broken behavior, but title implies improvement/addition
  - **Suggest:** Review whether behavior was actually broken or if this should be `enhancement`
- **`bug-fix`/`regression` enhancement verbs:** On `bug-fix`, flag titles starting with `Default`, `Reserve`, `Ensure`, or `Close` without `Fix`
- **`bug-fix`/`regression` preventive/restrictive framing:** Flag titles that describe a new restriction or validation rather than the user-visible failure, especially when the title does NOT start with `Fix`, `Resolve`, or `Correct`
  - **Leading patterns to flag:** `Don't`, `Do not`, `Disallow`, `Prevent`, `Reject`, `Block`, `Forbid`, `Prohibit`, `Restrict`, `No longer allow`
  - **Warning:** Title explains what is now blocked, not what was broken (recovery failure, query error, cluster red, etc.)
  - **Suggest:** Rewrite as `Fix [symptom] when [condition]` — e.g. "Don't allow runtime fields to shadow index sort fields" → "Fix shard recovery failures when runtime fields shadow index sort fields"
  - **Type note:** If the change only adds validation with no prior user-visible failure, consider `enhancement` instead of `bug-fix`

- **`enhancement` misalignment:** Title uses `Fix`, `Resolve`, `Correct` instead of expected `Improve`, `Update`, `Optimize`, `Enable`, `Expand`, `Enhance`
  - **Warning:** Type suggests improving working functionality, but title implies fixing broken behavior
  - **Suggest:** Review whether behavior was broken (→ `bug-fix`) or truly an optimization (keep `enhancement`)

- **`feature` misalignment:** Title uses `Fix`, `Improve` for substantial new capabilities
  - **Warning:** Major new functionality should use `Add`, `Introduce`, `Enable`, `Support`
  - **Suggest:** Review scope - substantial new capability (→ `feature`) vs minor addition (→ `enhancement`)

- **`docs` misalignment:** Title doesn't focus on documentation clarity/accuracy
  - **Warning:** Documentation changes should use `Update`, `Add`, `Clarify`, `Document`

**Example patterns to flag:**

- Type `bug-fix` + "Improve query approximation accuracy..." → **Flag alignment mismatch**
- Type `bug-fix` + "Don't allow runtime fields to shadow fields used in index sort" → **Flag preventive framing + verb mismatch**
- Type `enhancement` + "Fix Painless score scripts..." → **Flag alignment mismatch**  
- Type `enhancement` + "Fix ES|QL performance issues..." → **Flag alignment mismatch**

**6. Technical content issues:**

Flag overly technical titles that focus on implementation details rather than user impact:

- **Implementation-focused titles:** Class names, method names, or internal processes without user context
  - **Warning:** Title focuses on code changes rather than user-visible symptoms
  - **Example:** "Fix splitValue nullability coercion when constructing ColorSeries" → Flag as too technical
  - **Suggest:** Rewrite to describe user-visible impact like "Fix inline charts with grey time series for ES|QL queries"

- **Technical jargon without context:** Multiple technical terms that don't explain user experience
  - **Warning:** Title requires deep technical knowledge to understand user impact
  - **Suggest:** Focus on what users see, not how code works

- **Missing user symptoms:** Describes internal fixes without explaining external effects
  - **Warning:** Users can't determine if this change affects them
  - **Suggest:** Include user-facing symptoms or feature areas affected
- **Preventive vs corrective:** On `bug-fix`/`regression`, if the title lacks symptom words (fail, error, crash, leak, hang, timeout, incorrect, missing, red, unallocated) and instead uses restriction words (allow, disallow, prevent, reject, validate, block), flag as likely preventive framing — soft heuristic for human review, not auto-fail
- **Dev/test language:** Flag `Repro and fix` phrasing and PR-title passthrough with class/method names
- **Unexpanded dev acronyms:** Flag `NPE`, `UOE` — expand per `docs-fix-changelog` acronym table
- **ES|QL function tokens:** When `areas` includes `ES|QL`, flag unbackticked function names (`UNION_BY_NAME`, `JSON_EXTRACT`, etc.)

**Eligibility (report only — never delete files):**

- Recommend removal when linked PR/issue is test-only, refactor-only, or internal plumbing with no user-visible change
- Without PR context: flag title/description mentioning test-only work or internal refactor
- Report under `### Recommend removal`; do not modify or delete files

**Type-specific:**

- `breaking-change`: `impact` and `action` are REQUIRED — flag as errors if absent; `subtype` is strongly recommended
- `deprecation` and `known-issue`: `impact` and/or `action` are recommended — flag as warnings if absent
- `feature` / `enhancement`: title/description should explain what users can now do, not how it was built
- `bug-fix` / `regression`: title/description should explain what was wrong and what is now correct
- When present, `description` must add context beyond repeating the title; flagging "See PR" or "Internal refactoring" as low-value
- `impact` if present: should explain scope and who is affected
- `action` if present: should provide clear, prescriptive steps

## Step 5: Formatting checks

These are warnings. Check `description`, `impact`, and `action` field values for formatting consistency.

**Link formatting:**

- Bare URLs used as link text — should use `[descriptive text](url)` instead
- Generic link text like "click here" or "read more" — should be descriptive of the destination

**Code formatting:**

- Code fences without a language identifier — e.g. ` ``` ` with no language tag (use `yaml`, `json`, `bash`, `console`, etc.)
- Field names, config keys, commands, class names, or API endpoints written as plain text — should use inline backticks
- Missing backticks around obvious code identifiers like method names, parameter names, or specific values

**Text formatting:**

- Inconsistent spelling (should follow US English conventions)
- Inconsistent terminology

## Step 6: Report

Produce one section per file reviewed. Omit empty sections. Use this format:

```markdown
## Changelog review: 

### Summary
- N schema errors, M quality warnings, P formatt

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [elastic](https://github.com/elastic)
- **Source:** [elastic/elastic-docs-skills](https://github.com/elastic/elastic-docs-skills)
- **License:** Apache-2.0
- **Homepage:** https://elastic.github.io/elastic-docs-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-elastic-elastic-docs-skills-review-changelog
- Seller: https://agentstack.voostack.com/s/elastic
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.