dd-unblock-pr

A red build, gone through check by check — each failure labelled with what caused it and the single next step, so you can see which ones are actually yours to fix.

WHEN TO USE

SCOPE

USE FOR

Find out whether a failing check was already failing before your change touched it.
Tell an unreliable test apart from a genuine bug you just introduced.
Retry a failure that is just a blip, instead of guessing whether a retry will help.
Check a branch's code coverage alongside its CI health in one report.

NOT FOR

Fix a regression it identifies — it only classifies and points you at the code change.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (3)

Unblock PR

One-line summary: Investigate a failing PR CI pipeline — attribute each failure as flaky, infra, or regression and propose a targeted action.

Requires: dd-pup skill (pup CLI installed and authenticated), dd-triage-flaky-test skill (for flaky failure deep investigation).

Input

Parameter	Description
PR branch	The branch under investigation (e.g. `my-feature-branch`)
Repository	Lowercase, no-schema URL (e.g. `github.com/org/repo`). Derive from `git remote get-url origin` if not provided.

Workflow

STEP 0 — Parse Input

Derive repository ID and default branch from git if not provided:

# Repository ID: fully lowercase, no-schema URL (the API rejects mixed-case)
git remote get-url origin
# Strip protocol and trailing .git, then lowercase the result
# e.g. https://github.com/DataDog/my-repo.git → github.com/datadog/my-repo

# Default branch
git symbolic-ref refs/remotes/origin/HEAD
# Strip refs/remotes/origin/ prefix — fall back to main if unset

STEP 1 — Get PR CI Summary (run both in parallel)

Pipeline failures (job level):

pup cicd events search \
  --query "@ci.status:error @git.branch:<branch> @git.repository.id_v2:\"<repo>\"" \
  --level job \
  --from 24h \
  --limit 50

Test failures:

pup cicd tests search \
  --query "@test.status:fail @git.branch:<branch> @git.repository.id_v2:\"<repo>\"" \
  --from 24h \
  --limit 50

Run both queries in parallel. Collect all distinct @test.service values from test event results. If more than one distinct service is found, note each separately in the triage brief — do not collapse them into a single service filter. If pipeline results contain only infrastructure job types (build, lint, deploy) with no test-runner output, discard test search results and skip to STEP 3.

STEP 1.5 — Fetch Code Coverage (run in parallel with STEP 1)

This step runs unconditionally — coverage context is valuable whether CI is red or green.

The --repo value must be fully lowercase (the API rejects mixed-case). Normalize before calling:

repo_lower=$(echo "<repo>" | tr '[:upper:]' '[:lower:]')
pup code-coverage branch-summary \
  --repo "$repo_lower" \
  --branch "<branch>"

If the command returns no data or exits with an error, report "No data available" for Coverage in the PR Health section.

Note: Code quality and security violation counts are not available in pup — those lines always show "No data available".

STEP 2 — Blame Guard per Failing Job

First check whether @error_classification.domain / @error_classification.type are present on job events from STEP 1 — if populated, use them as primary classification signals.

For each failing job where classification is still needed, run both checks in parallel:

Default branch check — was this job already failing before this PR?

pup cicd events aggregate \
  --query "@ci.status:error @ci.job.name:\"<job>\" @git.branch:<default-branch> @git.repository.id_v2:\"<repo>\"" \
  --compute count \
  --from 24h

Blast radius check — is this job failing on other branches too?

pup cicd events aggregate \
  --query "@ci.status:error @ci.job.name:\"<job>\" @git.repository.id_v2:\"<repo>\"" \
  --compute count \
  --group-by "@git.branch" \
  --from 24h

Performance fallback: if the blast radius query is slow or times out, skip it and rely on the default branch check alone.

STEP 3 — Classify Each Failure

Priority order:

If @error_classification.domain / @error_classification.type present → use as primary signal

If test failure AND test appears in flaky tests with flaky_test_state:active:

pup cicd flaky-tests search \
  --query "flaky_test_state:active @test.name:\"<test-name>\" @git.repository.id_v2:\"<repo>\""

→ flaky

Use blame guard results:

Failing on default branch?	Failing on ≥3 other branches?	Classification
Yes	Yes	infra (pre-existing, widespread)
Yes	No	infra (pre-existing on default branch)
No	No	regression (introduced by this PR)
No	Yes	flaky (intermittent, cross-branch)
Insufficient data	—	unknown

STEP 4 — Produce Triage Brief

One entry per failing job:

PR CI Triage Brief
==================
Branch:   <branch>
Repo:     <repo>

Job: <job-name>
  Classification:  <flaky | infra | regression | unknown>
  Evidence:        <1 key data point — error message, pipeline count, or test result>
  Confidence:      <high | medium | low>
  Recommended:     <action>

[repeat for each failing job]

Overall: <N> failures — <e.g. "1 regression, 1 flaky, 1 infra">

PR Health
=========
Coverage:   <X>% on <branch> | No data available
Quality:    No data available
Security:   No data available

All three lines always appear.

STEP 5 — Propose Actions

regression → Prompt user to investigate their code changes. No write action available.

flaky → Load dd-triage-flaky-test skill for deep investigation. That skill will:

Attempt an agent-native fix using flaky_category + stack trace
Propose quarantine via pup test-optimization flaky-tests update if a quick fix isn't possible

infra → Before proposing a retry, assess whether the failure is transient:

Check @error_classification.type and error message for signals like timeout, runner unavailable, network error, quota exceeded — these indicate transient failures where a retry is likely to help
If the error is deterministic (build misconfiguration, missing secret, explicit test assertion failure), a retry is unlikely to help — note this and suggest investigating the root cause
If the failure is pre-existing on the default branch, inform the user — a retry will likely fail again; await the upstream fix instead

If transient and GitHub Actions: extract the run ID from @ci.pipeline.url (e.g. https://github.com/org/repo/actions/runs/<run_id>):

gh run rerun <run_id> --failed

For other providers, share @ci.pipeline.url and direct to the provider UI for retry.

unknown → Suggest checking raw job logs via the CI provider UI or @ci.pipeline.url from the pipeline event.

Account or credentials required

1 FOR YOU

01
Install and authenticate the pup CLI
This skill assumes the dd-pup skill's prerequisite is already met: pup installed and signed in via pup auth login.

Not standalone. This skill ships with DataDog/pup and only works together with that tool — install the tool first, then add this skill.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add DataDog/pup --skill "dd-unblock-pr" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

View on GitHub