Triager

Agentic PR-to-suite matcher. Given a pull request diff and a catalog of test suites, it picks the suites that are worth running — and optionally labels the PR on GitHub.

Pipeline

Path coverage runs first: any diff file matching a suite's covers globs flags that suite as a candidate at HIGH confidence. If at least one suite matches, the decision is deterministic and the AI phase is skipped. If nothing matches (docs-only, infra-only, or otherwise uncovered PRs), the AI phase reads the diff through a small set of tool handlers and picks contextually.

1
PR Diff
Files, hunks, title/body fetched from GitHub.
2
Suite Catalog
Groups from .xqa/suites/.
3
Match Covers
Any diff path matching a suite's covers globs flags that suite as a HIGH candidate.
4
AI Fallback
Only when zero suites match via path. Claude reads the diff and picks contextually.
5
Decision
Picks, skipped, confidence, meta-PR flag.
6
Apply Labels
Optional — adds xqa:<suite> labels to the PR.

Inputs

Everything the triager runs against.

Diff

A canonical Diff shape derived from the GitHub PR:

  • files[] — path, status (added / modified / deleted / renamed), optional hunks with line ranges
  • title, body — PR metadata used as prompt context

Test Groups

Each entry in .xqa/suites/<name> becomes a TestGroup:

  • id — stable identifier (becomes the xqa:<id> label)
  • description — human summary shown to the AI
  • covers[] — glob patterns used for scoring
  • metadata — free-form bag surfaced to the AI prompt

Decision

What the triager emits.

Field Type Meaning
picks Pick[] Suites the triager recommends running. Each pick carries groupId, confidence (HIGH / MEDIUM / LOW), reason, and evidence[].
skipped Pick[] Suites considered and rejected, with the same shape as picks. Useful for audit trails.
confidence 'high' | 'medium' | 'low' Overall confidence in the decision.
metaPr boolean Indicates the PR is not product code (docs, infra, tooling) — downstream tooling can choose to skip labeling entirely.

What triage can read

When path coverage finds no match, the AI phase uses a small set of read-only helpers.

file

Read file

Reads a path from the repository working tree (path traversal denied).

search

Search codebase

Search over the repo to understand what the diff touches.

app

App context

Loads .xqa/app.md screen sections to reason about UI surfaces touched by the diff.

catalog

Suite index

Sees which suite specs reference which screens or modules.

CLI

The triager ships behind a single user-facing command.

xqa triage --pr 123 --repo your-org/your-app
xqa triage --pr 123 --repo your-org/your-app --apply-labels
xqa triage --pr 123 --repo your-org/your-app --threshold 0.7
Flag Required Effect
--pr <number> Yes Pull request number to triage.
--repo <owner/name> Yes Repository hosting the PR.
--suites-dir No Override the default suites directory (.xqa/suites/).
--apply-labels No When set, writes resolved xqa:<suite> labels back to the PR.
--model No Override the triager model (default: claude-sonnet-4-6).
--threshold No Confidence threshold in [0, 1]; suites below this score are filtered out.

Requires ANTHROPIC_API_KEY and GITHUB_TOKEN in .env.local.