Debug OAS

Overview

Use node ./scripts/validate_oas_docs.js to validate Kibana OAS, but always scope output with --path so developers can focus on the API area they are actively changing.

Use this skill when the developer needs issue breakdown, categorization, or representative examples. For quick pass/fail only, use validate-oas first.

If results look stale or surprising, refresh generated OAS first using the environment setup flow in validate-oas. Treat stale oas_docs as a setup problem, not a debugging conclusion.

The validator can surface two broad categories of issues:

• structural: invalid OAS problems that usually block correctness, such as schema violations, invalid shapes, unresolved references, or mismatches between path definitions and the spec structure.
• quality: documentation completeness problems such as missing description, summary, example, or examples.

When reporting results, always separate these categories. Lead with structural issues first.

Required interaction flow

1. Ask what APIs the developer is working on.
2. Ask for one or more HTTP API paths (for example /api/fleet/agent_policies).
3. Refresh generated OAS first when needed by following the environment setup flow in validate-oas.
4. Run validation with those route-style --path filters.
5. Classify the resulting issues into structural vs quality.
6. Display the command output directly so the developer can see current issues.

Do not skip questions (1) and (2) unless the developer already provided the API paths.

Path format guidance

Use normal route-style API paths for --path (human-readable):

• /api/fleet/agent_policies
• /internal/fleet/outputs

Do not manually convert to JSON pointers. The CLI handles conversion for error filtering internally.

Multiple path filters are supported:

node ./scripts/validate_oas_docs.js \
  --path /api/fleet/agent_policies \
  --path /internal/fleet/outputs

Commands

Default scoped validation:

node ./scripts/validate_oas_docs.js --only traditional --path <api_route_prefix>

Scope to one offering when requested:

node ./scripts/validate_oas_docs.js --only traditional --path <api_route_prefix>
node ./scripts/validate_oas_docs.js --only serverless --path <api_route_prefix>

Default behavior:

• Unless the developer asks otherwise, always include --only traditional so validation runs against a single OAS output file.
• Prefer --only traditional by default because it matches the common local debugging path and keeps output narrower.
• Use --only serverless only when the developer explicitly asks for it.

Optional structural-only summary when the raw output is noisy:

node ./scripts/validate_oas_docs.js --only traditional --path <api_route_prefix> 2>&1 \
  | node .agents/skills/debug-oas/scripts/extract_structural_oas_issues.js

If the developer wants to keep documentation issues in that helper output:

node ./scripts/validate_oas_docs.js --only traditional --path <api_route_prefix> 2>&1 \
  | node .agents/skills/debug-oas/scripts/extract_structural_oas_issues.js --include-docs

Only use the helper summary as a supplement. Keep the raw validator output available for exact debugging.

Issue categorization

Classify issues using these defaults:

• quality:
  • missing description
  • missing summary
  • missing example
  • missing examples
• structural:
  • everything else by default
  • examples include invalid schemas, type mismatches, missing required non-doc fields, invalid parameter definitions, unresolved refs, or malformed response/request structures

Heuristic:

• If the message is a docs-completeness complaint about description, summary, example, or examples, treat it as quality.
• Otherwise treat it as structural unless the developer explicitly asks for a finer split.

Severity guidance:

• structural = blocking invalid OAS
• quality = docs completeness or polish problems

If a run mixes both categories, report structural counts first, then quality counts.

Scope narrowing

If the initial scope is noisy, narrow in this order:

• start with a broad product area such as /api/fleet
• narrow to a feature area such as /api/fleet/epm
• narrow again to a route family such as /api/fleet/epm/packages

Suggest narrower scopes when one area dominates the structural issues.

Output behavior

• Use the CLI line Found N errors in ... as the source of truth for issue count.
• If the run has 25 or fewer issues, show the exact CLI output with no summarization.
• If the run has more than 25 issues, summarize key patterns and suggest a narrower --path scope.
• When summarizing, include:
  • structural issue count
  • quality issue count
  • a few issues copied verbatim from CLI output, ideally one sample per dominant category
• When summarizing, use language like:
  • Structural issues (invalid OAS): ...
  • Quality issues (docs gaps): ...
• Prefer full issue output (do not use --skip-printing-issues) when debugging.
• If no issues are shown for the selected path, suggest widening or adjusting the --path prefix.
• If only quality issues remain, say that explicitly so the developer knows the remaining work is documentation-oriented rather than structural.

Output template

When summarizing, use this shape:

Total issues: N
Structural issues: X
Quality issues: Y