ecs-pr-triage

name	ecs-pr-triage
description	>- Use when this capability is needed.

ECS PR triage

This skill triages an ECS pull request. The agent needs access to the PR diff, changed file list, PR description, and metadata — either already present in context or fetched via tools (e.g. gh). It analyzes that context, makes a routing decision, and delivers a triage report.

Execution steps

1. Inventory the PR context

From the PR context available to you (or fetched via gh pr view, gh pr diff, etc.), extract:

• PR number, title, author.
• Changed file paths — bucket every path into one of these categories:
  • schemas/ — source schema YAML (the key signal for routing)
  • generated/ — build outputs (should only change as a side effect of schema + make)
  • scripts/ — generator tooling, tests, templates
  • docs/ — hand-authored docs vs generated reference (docs/reference/ecs-*.md)
  • rfcs/ — RFC markdown and supporting YAML
  • .github/ — CI workflows, templates, issue config
  • release/ — release-process artifacts: version file, CHANGELOG.md rotation, release-note shuffling in docs/
  • Root config — Makefile, version, CHANGELOG.next.md, etc.
• PR description body — check which of the 7 template sections from .github/PULL_REQUEST_TEMPLATE.md are filled vs empty/placeholder.
• Diff content — scan for signals: new field set files, field removals, type: changes, new reusable entries, allowed_values additions, alpha/beta changes, etc.

2. Classify the change

Walk the decision tree in classification-rules.md in priority order:

0. Check for release process PR first — if the PR exclusively touches release mechanics (version bumps, changelog rotation, moving/updating release notes in docs/, CHANGELOG.md consolidation) it is always Direct PR. Release PRs never require an RFC or discussion regardless of how many files change.
1. Check §1 (RFC triggers) — any match means classification is Needs RFC. Triggers: new schemas/*.yml file, breaking changes (field removal, type change, semantic redefinition), new reuse topology, novel use case, ECS-wide scope, >10 new leaf fields.
2. Check §3 (ambiguous) — any match (without §1) means classification is Needs Discussion. Includes: 3–10 new fields in one field set, new allowed_values on categorization fields (event.category, event.type, event.kind), maturity promotions, unjustified object/flattened.
3. Otherwise §2 — all remaining low-risk patterns → classification is Direct PR.

Assign labels:

• Change type: Schema Change | Tooling | Documentation | Mixed
• Scope: Minor | Moderate | Substantial

3. Check completeness

Evaluate against the checklist in ecs-pr-completeness rule:

• PR description: all 7 template sections answered (not empty/placeholder).
• CHANGELOG.next.md entry: only expected when schemas/ or scripts/ files change (i.e. schema changes or tooling changes). RFC-only PRs (rfcs/ only), pure documentation PRs, CI-only PRs, and release process PRs do not require a changelog entry. When required, verify it is in the correct section (Schema Changes vs Tooling and Artifact Changes) and includes #NNNN.
• If schema change: generated/ and docs/reference/ artifacts present in the diff (evidence that make was run and outputs committed).
• If new/changed fields relate to OTel semconv: otel: metadata is encouraged but not required.
• No hand-edits to files that should only be generator output (docs/reference/ecs-*.md, generated/).

Mark each item as met or missing.

4. Produce the triage report

Fill report-template.md completely. Rules:

• Cite specific triggers. E.g. "New file schemas/foo.yml detected → RFC required per classification-rules §1."
• List every missing checklist item with clear remediation (e.g. "Add a CHANGELOG.next.md entry under Schema Changes > Added with #NNNN").
• If Needs RFC: point the contributor to rfcs/PROCESS.md and the RFC template at rfcs/0000-rfc-template.md. Reference the ecs-rfc-guide skill for a detailed walkthrough.
• If Needs Discussion: state exactly what is ambiguous and what a maintainer should weigh in on.

Decision defaults

• Conservative: when borderline, prefer Needs Discussion or Needs RFC over Direct PR. Under-triaging is worse than over-triaging.
• No approval authority: the agent triages and reports. It does not approve, request changes, or merge.

Important repo facts

• Source of truth for fields: schemas/*.yml. Hand-edits to generated/ or docs/reference/ecs-*.md without a corresponding schema change are errors — flag them.
• Build pipeline: make regenerates all artifacts; make test runs unit tests; make check runs generate + test + diff (CI parity).
• RFC process: single Proposal stage per rfcs/PROCESS.md; template at rfcs/0000-rfc-template.md.
• OTel mapping: otel: metadata on fields is optional; encouraged when a clear semconv counterpart exists but not a merge gate.

Related assets

• classification-rules.md — full decision tree with thresholds and examples.
• report-template.md — output format to fill.
• ecs-rfc-guide skill — reference for contributors when RFC is needed.
• Rules: ecs-contribution-routing, ecs-schema-standards, ecs-pr-completeness.

---

Source: elastic/ecs — distributed by TomeVault.