16 added, 0 removed. Audit A to A.
---
name: browse-and-verify
description: "Browse a URL with Playwright to validate links, find page sections, and extract content for quiz sources. Trigger: validate link, check this URL, find the section, browse page, what does this page say about, verify source."
metadata:
type: protocol
invocation: both
practice: null
---
# Browse and Verify
Dispatch to the **browser** specialist agent (`.kiro/agents/browser.json`) for URL validation, section extraction, and heading discovery. The browser agent has the Playwright MCP configured — the default agent does NOT load Playwright (40+ tools would degrade tool selection).
## Setup
The browser agent is at `.kiro/agents/browser.json` with `@playwright/mcp` configured headless. Dispatch to it for any browsing task rather than loading Playwright in the main context.
If the browser agent is unavailable, fall back to the `web_fetch` tool (built-in, no MCP needed).
## When to use
- **Before adding a quiz source link**: navigate to the URL, verify the page loads and the content exists
- **When finding the right section to link**: browse the page and look for heading IDs/anchors
- **When writing explanations**: read the relevant section to ground your explanation in the source
- **When a learner questions a source**: re-read the section to confirm accuracy
## Workflow: Validate and find the right section
1. **Navigate** to the page URL
2. **Check the snapshot** — does the page load? Is the content relevant?
3. **Find headings** — look for section IDs in the accessibility snapshot to construct `#anchor` links
4. **Read the section** — confirm the content actually answers/addresses the quiz question
5. **Write the source entry** with the specific URL#anchor, label, and section description
## Quality rules for quiz source links
1. **Always browse before committing** — dead links and irrelevant pages erode trust
2. **Link to the most specific section** — use `#anchor` IDs from headings
3. **Read the section** to confirm it actually helps answer the question
4. **Write the `section` field** based on what you read, not assumptions
5. **If no good anchor exists**, link to the page and describe which paragraph is relevant
6. **Never link to generic overviews** — the linked page must significantly help answer the specific question
7. **Multiple targeted links > one vague link** — e.g., both the spec section AND the AWS implementation docs
## Fallback: web_fetch
When Playwright MCP is not configured or the page is simple (static HTML, no JS rendering needed):
```
web_fetch url="https://iceberg.apache.org/spec/" search_terms="manifest lists" mode="selective"
```
This returns ~10 lines around matches. Sufficient for validation but won't find heading IDs as reliably.
+ ## Escalation Decision Tree
+
+ **Default to `web_fetch` first** — it's faster (no browser startup) and sufficient for most documentation pages:
+
+ 1. Try `web_fetch` with `search_terms` (selective mode)
+ 2. If content is empty or minimal (JS-rendered page): escalate to Playwright
+ 3. If you need heading IDs / anchor discovery: escalate to Playwright
+ 4. If the page requires interaction (login, cookie consent, expand sections): Playwright required
+
+ | Page type | Tool | Why |
+ |-----------|------|-----|
+ | Static docs (most sources) | `web_fetch` | Fast, sufficient |
+ | AWS docs (some JS-rendered) | Playwright | Content loads dynamically |
+ | Pages needing `#anchor` discovery | Playwright | Accessibility snapshot shows heading refs |
+ | Any page where fetch returns empty | Playwright | JS rendering needed |
+
## When NOT to use Playwright
- **Page is static HTML** and you only need to check if it loads → use `web_fetch` in `truncated` mode
- **You need a HEAD request** (just check HTTP status) → `web_fetch` is lighter
- **Content is already in your context** from a prior fetch → don't re-browse