# How to Configure Browser Verification for Frontend UI Stories with the dev-browser Skill

> Learn to configure browser verification for frontend UI stories in Ralph. Add acceptance criteria to trigger the dev-browser skill for automatic headless UI validation.

- Repository: [Ryan Carson/ralph](https://github.com/snarktank/ralph)
- Tags: how-to-guide
- Published: 2026-04-13

---

**To configure browser verification for frontend UI stories in Ralph, append the literal acceptance criterion "Verify in browser using dev-browser skill" to the story's acceptance criteria list, which triggers the agent to automatically load the `dev-browser` skill and validate the UI in a headless Chromium instance.**

The Ralph autonomous agent enforces a strict quality gate for any user story that modifies frontend code. According to the `snarktank/ralph` source code, a frontend UI story cannot be marked as complete until the visual changes are verified in a real browser using the `dev-browser` skill. This verification workflow is defined across three critical files: [`skills/ralph/SKILL.md`](https://github.com/snarktank/ralph/blob/main/skills/ralph/SKILL.md), [`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md), and [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md).

## Why Browser Verification is Mandatory

Ralph treats frontend UI stories as **incomplete by default** to prevent false positives where code compiles but renders incorrectly. The `dev-browser` skill runs a headless Chromium instance that navigates to the relevant page, exercises the UI interactions defined by the story, and confirms the acceptance criterion is satisfied. This ensures deterministic CI outcomes and eliminates the need for external test harnesses.

## Step-by-Step Configuration

### Declare the Mandatory Acceptance Criterion

Every frontend UI story must declare a specific acceptance criterion that instructs the agent to perform browser verification. In [`skills/ralph/SKILL.md`](https://github.com/snarktank/ralph/blob/main/skills/ralph/SKILL.md) (line 1012), the **Ralph PRD Converter** automatically injects this entry when it detects a UI-related story.

The criterion must appear as the **last item** in the `acceptanceCriteria` array and use the exact literal string:

```json
{
  "id": "US-002",
  "title": "Display status badge on task cards",
  "description": "As a user, I want to see task status at a glance.",
  "acceptanceCriteria": [
    "Each task card shows a colored status badge",
    "Badge colors: gray=pending, blue=in_progress, green=done",
    "Typecheck passes",
    "Verify in browser using dev-browser skill"
  ],
  "priority": 2,
  "passes": false,
  "notes": ""
}

```

*The presence of this string in [`prd.json`](https://github.com/snarktank/ralph/blob/main/prd.json) makes the verification step discoverable by tooling and mandatory for the agent.*

### Configure the Agent Prompt

The agent's behavior is guided by the **global prompt** defined in [`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) (line 83). This file contains a dedicated "Browser Testing (Required for Frontend Stories)" block that instructs the agent to load the skill before finishing any frontend story.

The prompt specifies four sequential steps:

1. Load the `dev-browser` skill
2. Navigate to the relevant page
3. Verify the UI changes work as expected
4. Take a screenshot if helpful for the progress log

```text

## Browser Testing (Required for Frontend Stories)

1. Load the `dev-browser` skill
2. Navigate to the relevant page
3. Verify the UI changes work as expected
4. Take a screenshot if helpful for the progress log

```

### Runtime Execution Flow

When the agent processes a story where the `passes` flag remains `false`, it executes the verification workflow described in [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) (line 203):

- The **agent loop** invokes the `dev-browser` skill
- A **headless Chromium instance** launches and visits the target URL
- The skill executes the **interaction script** defined by the story requirements
- Upon successful verification, the skill returns a **success signal** and the agent flips the `passes` flag to `true`

If verification fails, the flag remains `false` and the agent logs the failure for the next iteration.

## Implementation Examples

### PRD JSON Structure

The following example from `prd.json.example` demonstrates the complete structure for a UI story requiring browser verification:

```json
{
  "id": "US-002",
  "title": "Display status badge on task cards",
  "description": "As a user, I want to see task status at a glance.",
  "acceptanceCriteria": [
    "Each task card shows a colored status badge",
    "Badge colors: gray=pending, blue=in_progress, green=done",
    "Typecheck passes",
    "Verify in browser using dev-browser skill"
  ],
  "priority": 2,
  "passes": false,
  "notes": ""
}

```

### Progress Log Output

After successful execution, [`progress.txt`](https://github.com/snarktank/ralph/blob/main/progress.txt) records the verification step:

```markdown

## 2026-04-13 14:20 – US-002

Thread: https://ampcode.com/threads/xyz123
- Added badge component to TaskCard.tsx
- Updated CSS for badge colors
- Loaded dev-browser skill → navigation to /tasks succeeded
- Badge displayed correctly, screenshot captured
- passes: true

```

## Key Configuration Files

| File | Role | Key Location |
|------|------|--------------|
| [`skills/ralph/SKILL.md`](https://github.com/snarktank/ralph/blob/main/skills/ralph/SKILL.md) | Defines PRD-to-JSON conversion rules and the mandatory acceptance criterion string | Line 1012 |
| [`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) | Global agent prompt containing the "Browser Testing (Required for Frontend Stories)" execution block | Line 83 |
| [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) | Human-readable specification of the browser verification workflow | Line 203 |
| `prd.json.example` | Reference implementation showing proper acceptance criteria structure | Example UI stories |

## Summary

- **Mandatory criterion**: Every frontend UI story must include the literal string `Verify in browser using dev-browser skill` as the final acceptance criterion.
- **Automatic execution**: The agent reads the global [`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) configuration and automatically loads the `dev-browser` skill when this criterion is present.
- **Headless validation**: The skill runs a headless Chromium browser to perform visual verification before the story's `passes` flag can be set to `true`.
- **Self-contained workflow**: All verification logic resides within the Ralph repository; no external testing frameworks are required.
- **Traceability**: The verification requirement is encoded directly in [`prd.json`](https://github.com/snarktank/ralph/blob/main/prd.json), making it parsable by CI/CD tooling.

## Frequently Asked Questions

### What is the exact acceptance criterion string required for browser verification?

The string must be exactly: **"Verify in browser using dev-browser skill"**. This literal text is detected by the Ralph PRD Converter in [`skills/ralph/SKILL.md`](https://github.com/snarktank/ralph/blob/main/skills/ralph/SKILL.md) and triggers the agent to load the `dev-browser` skill during execution. Any variation in capitalization or wording will not activate the verification workflow.

### Can I use the dev-browser skill for backend-only stories?

No. The `dev-browser` skill is specifically designed for **frontend UI stories** that require visual verification in a browser. Backend stories that only modify API endpoints or database schemas should not include this acceptance criterion, as the skill attempts to navigate to pages and interact with DOM elements that would not exist in non-UI contexts.

### Where does Ralph define the browser verification logic?

The verification workflow is defined across three files: the conversion rules reside in [`skills/ralph/SKILL.md`](https://github.com/snarktank/ralph/blob/main/skills/ralph/SKILL.md) (line 1012), the agent execution instructions are in [`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) (line 83) under the "Browser Testing (Required for Frontend Stories)" section, and the high-level behavior specification is documented in [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) (line 203).

### What happens if the browser verification fails?

If the `dev-browser` skill detects that the UI does not behave as expected—such as missing elements, incorrect styling, or failed interactions—it returns a **failure signal** to the agent loop. The story's `passes` flag remains `false`, preventing the story from being marked complete, and the failure details are logged in [`progress.txt`](https://github.com/snarktank/ralph/blob/main/progress.txt) for the next iteration cycle.