validate-integration-docs

name	validate-integration-docs
description	Lint an Elastic integration package's markdown with vale and propose fixes. Use when the user says "vale check," "lint docs," "validate the README," "check integration markdown," or wants to polish an integration's docs before opening a PR. Filters out false positives inside Go-template comment blocks in _dev/build/docs/, then re-runs vale against the rendered docs/ output after `elastic-package build` as a final pass.
compatibility	Requires `elastic-package` CLI and `vale` on PATH. Designed for packages in elastic/integrations (or any repo using the _dev/build/docs/README.md → docs/README.md layout produced by elastic-package build).
license	Apache-2.0
metadata	{"origin":"elastic/elastic-package"}

validate-integration-docs

Lint an integration package's docs source, filter template noise, propose fixes, then verify the rendered output.

Phase 1 — Lint the source

1. Check prerequisites: run both checks before continuing:

   • vale --version — if not found, tell the user to install it by following the Elastic vale linter guide.
   • elastic-package version — if not found, tell the user to install it by following the elastic-package install guide.

   Stop and report any missing tools before proceeding.

2. Locate the package root: find the nearest ancestor directory (including cwd) that contains both manifest.yml and _dev/build/docs/README.md. If not found, ask the user for the path before continuing.

3. Run vale on the source:

   vale _dev/build/docs/README.md --output JSON
   

   If additional *.md files exist under _dev/build/docs/, include them too.

4. Detect template-comment ranges: pre-scan the source file with a non-greedy DOTALL match for \{\{\s*/\*.*?\*/\s*\}\}. For each match, record (start_line, end_line) by counting newlines before the match start and end.

5. Filter findings: suppress any vale finding whose Line falls within any (start_line, end_line) range. Those lines are stripped by elastic-package build and their findings are false positives. Report only findings outside those ranges, grouped by file, with: Line, Match, Severity, Check, and Message.

6. Draft proposals for each reported finding:

   • Action.Name == "replace" → mechanical substitution using Action.Params[0].
   • Action.Name == "remove" → delete the Match span.
   • No action params (for example Elastic.Semicolons, Elastic.DontUse, Elastic.Ellipses) → draft a prose rewrite of the sentence using context.

7. Confirm before editing: present all proposals together and ask the user which to apply (all / subset / none). Apply only confirmed edits via the Edit tool. Never edit files under packages/*/docs/ — only _dev/build/docs/ sources.

If Phase 1 finds no actionable issues, skip the confirmation step and proceed to Phase 2.

Phase 2 — Build and re-lint the rendered output

1. Build the package from the package root:

   elastic-package build
   

2. Run vale on the rendered README:

   vale packages/<pkg>/docs/README.md --output JSON
   

   Extend to other docs/**/*.md if present. No template-comment filtering is needed — comments are stripped by the build.

3. Report and propose fixes exactly as in Phase 1 steps 6–7. If a Phase 2 finding maps to a source line, edit _dev/build/docs/ only.

4. Re-run elastic-package build after any source edits so the user can confirm the rendered output is clean.

Review checklist

Before reporting the task complete, verify:

• vale and elastic-package were both confirmed available (or the user was sent to the relevant install guide).
• Every finding inside a {{/* */}} block was suppressed in Phase 1.
• No edits were written to any path under packages/*/docs/.
• Every edit was confirmed by the user — nothing was silently auto-applied.
• elastic-package build completed without error.
• vale packages/<pkg>/docs/README.md (Phase 2) reported no findings.