ecs-pr-triage

name: ecs-pr-triage description: >- Triages an ECS pull request. Analyzes the PR diff and metadata, classifies the change (schema / tooling / docs / mixed), routes it to the correct contribution path (direct PR vs RFC Proposal vs needs-discussion), checks PR completeness, and produces a structured Triage Report.

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.