Using the Diff Stage agent skill

Your coding agent opens the PR and names the Pest browser tests that show its changes. CI records those tests and posts a Diff Stage player link. You watch the video next to main before merging.

Complete the recorder setup and GitHub Actions workflow first. The skill helps the agent prepare evidence inside that environment.

What the skill does#

The diff-stage-evidence skill reads the diff and your existing browser tests. It picks the smallest journeys that demonstrate the change, and adds or adjusts tests when the task calls for it. It records the current commit, checks the footage and writes Browser videos: selections and Browser review: notes in the PR description.

The agent also lists omitted journeys and the checks that cover them. If no browser journey demonstrates the change, it leaves the selection empty. Before handoff, it checks that CI evidence matches the PR commit and that the hosted videos play. Missing uploads, sign-in requirements and unreviewed footage remain explicit blockers.

You still review the evidence and decide whether to merge.

Install for your agent#

The recorder includes the skill as one SKILL.md file. Install the package, then read vendor/diff-stage/recorder/skills/diff-stage-evidence/SKILL.md before copying it.

composer require --dev diff-stage/recorder:^0.2 -W

For Codex, copy it into your project's .agents/skills directory:

mkdir -p .agents/skills
cp -r vendor/diff-stage/recorder/skills/diff-stage-evidence .agents/skills/

For Claude Code, use .claude/skills:

mkdir -p .claude/skills
cp -r vendor/diff-stage/recorder/skills/diff-stage-evidence .claude/skills/

Commit the copied skill to share it with your team. Copy it again after upgrading the recorder. For a personal installation across projects, use ~/.agents/skills for Codex or ~/.claude/skills for Claude Code instead.

For another agent that reads SKILL.md, copy the same directory into its documented skills location. If your tool doesn't discover skills, ask it to read the file directly.

Ask the agent to prepare a PR#

Include the skill in your task:

Fix the checkout decline message and open a PR. Use the diff-stage-evidence skill to select the browser tests that show the change, record the current commit and write review notes. Report any evidence you couldn't verify.

The agent should reuse your working browser environment and disposable fixtures. Watch the recordings for private information before publishing them.

Example PR description#

Given a Pest test named it('shows why a card was declined', ...) in tests/Browser/CheckoutTest.php, the complete selection name is it shows why a card was declined. A describe() group becomes part of that name; include it exactly as Pest reports it. A dataset scenario records all its variants.

An agent might write this after checking the actual recording:

Explain a declined card beneath the card field so customers can retry.

Browser videos: tests/Browser/CheckoutTest.php::it shows why a card was declined

Browser review:
1. `checkouttest-it-shows-why-a-card-was-declined`: Compare the new decline explanation beneath the card field with main. Watch the retry reach the confirmation screen.

Checks: checkout feature tests and browser regression passed.
Recorded at <full commit SHA>; the video was watched at normal speed.
CI evidence: <verified Diff Stage player URL for that SHA>.

Not shown: payment-provider responses use test fixtures. This video doesn't prove the live payment provider works.

Copy the review key from the generated filename without .webm; don't guess it from the test name. Browser videos: selects tests for execution and recording. Browser review: adds notes and their order, without changing which tests run. Replace the example SHA and URL with verified values, and report pending checks honestly.

Opening a PR yourself#

1. Choose the browser tests that show your change. Run your regression checks separately, then commit the final change.
2. Record the selected journeys locally, watch each through its final result and check for private information. Copy the flow keys from their filenames.
3. Add one Browser videos: path::complete Pest name line per scenario to the PR description. A file-only line records every test in that file. Add Browser review: notes that tell the reviewer where to look.
4. Open the PR and wait for CI. Follow its Diff Stage comment, check the recorded SHA matches the PR head, and watch the videos next to the approved main baseline.

For changes without useful browser evidence, omit selections and notes and explain which checks cover the change. After another commit, verify the new recordings before relying on the old comment.

See Comparing browser test videos before merging for the review controls and missing-baseline behavior.