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, missing product/surface context in titles, description verb-tense issues, 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 changelog files before merging — pairs with docs-fix-changelog to get suggested fixes.
Instrucciones de origen · Vista previa de solo lectura
name
docs-review-changelog
version
1.6.0
description
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, missing product/surface context in titles, description verb-tense issues, 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 changelog files before merging — pairs with docs-fix-changelog to get suggested fixes.
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-changelogsuggests 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
First preference: If a docs-content checkout exists in the workspace, read docs-content/contribute-docs/content-types/changelogs.md
Fallback: Use the embedded patterns in this skill if the above sources are unavailable
Repository Configuration Loading
Area validation: Look for docs/changelog.yml in the workspace to extract valid area values from the pivot.areas section
Repository context: If found, use this as the authoritative source for area validation instead of generic rules
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
No buried lede: If title is vague, fold in concrete detail from description so release notes stand alone
Product/surface context: Titles scoped to a UI element or workflow must locate the change: [Verb] [change] [in/on/for] [feature, app, page, tab, flyout, or integration]. Flag generic nouns (button, metrics, monitors) with no context. Use PR paths/labels, areas, and issue titles as context sources
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
Verb-form split: Titles use base-form imperative (Fix, Add). Descriptions, impact, and action use third-person present (Fixes, Adds). Flag past tense (Fixed, Added) and base-form openings in descriptions
Directory mode: Flag mixed past/present description tense across files in the same run
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
6. 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
7. 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:
## Changelog review: <filename>### Summary- N schema errors, M quality warnings, P formatting warnings
### Schema errors-`field`: description of the problem
### Quality warnings-`field`: description of the problem
### Formatting warnings-`field`: description of the problem
### Recommend removal- Optional; include only when eligibility checks fire — reason and PR/issue reference if available
If a file has no issues, say so explicitly.
Confidence Assessment
Include this section when resource loading or validation has limitations:
End with a one-line overall summary across all files reviewed. If any files have quality warnings (including systematic pattern issues, type-title alignment mismatches, and technical content issues) or formatting warnings, suggest running docs-fix-changelog to get specific improvement suggestions that address the same patterns this review identified.
Sync awareness: If Step 1 successfully loaded canonical guidance and you detected significant discrepancies between the live documentation and this skill's embedded patterns, flag this in your summary. Note which patterns may need updating and suggest checking the canonical source directly at https://www.elastic.co/docs/contribute-docs/content-types/changelogs.
