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.

1. 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.

1. Run vale on the source:

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

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

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

1. Filter findings: suppress any vale finding whose Line falls within any (startline, endline) 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.

1. 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.

1. 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:

``bash elastic-package build ``

1. Run vale on the rendered README:

``bash 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.

1. 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.

1. 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.