From f262ff1bf3ef268a18ac93263d7ecf2b0b56668a Mon Sep 17 00:00:00 2001
From: Qiaochu Hu <110hqc@gmail.com>
Date: Sat, 7 Mar 2026 04:31:04 +0800
Subject: [PATCH] docs: improve snapshot usage guidance and add reproducibility
 check (#630)

Fixes #566: Clarify snapshot vs snapshot -i usage
- Add guidance that snapshot -i is for clickable/fillable elements
- Add guidance that snapshot (no flag) is for reading page content

Fixes #565: Add reproducibility verification before collecting evidence
- Add guidance to verify issues are reproducible before recording video
- Prevent wasting turns on false positives
---
 skills/dogfood/SKILL.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/skills/dogfood/SKILL.md b/skills/dogfood/SKILL.md
index be25ce5..dcd7d4d 100644
--- a/skills/dogfood/SKILL.md
+++ b/skills/dogfood/SKILL.md
@@ -190,9 +190,13 @@ agent-browser --session {SESSION} close
 ## Guidance
 
 - **Repro is everything.** Every issue needs proof -- but match the evidence to the issue. Interactive bugs need video and step-by-step screenshots. Static bugs (typos, placeholder text, visual glitches visible on load) only need a single annotated screenshot.
+- **Verify reproducibility before collecting evidence.** Before recording video or taking screenshots, verify the issue is reproducible with at least one retry. If it can't be reproduced consistently, it's not a valid issue.
 - **Don't record video for static issues.** A typo or clipped text doesn't benefit from a video. Save video for issues that involve user interaction, timing, or state changes.
 - **For interactive issues, screenshot each step.** Capture the before, the action, and the after -- so someone can see the full sequence.
 - **Write repro steps that map to screenshots.** Each numbered step in the report should reference its corresponding screenshot. A reader should be able to follow the steps visually without touching a browser.
+- **Use the right snapshot command.**
+  - `snapshot -i` — for finding clickable/fillable elements (buttons, inputs, links)
+  - `snapshot` (no flag) — for reading page content (text, headings, data lists)
 - **Be thorough but use judgment.** You are not following a test script -- you are exploring like a real user would. If something feels off, investigate.
 - **Write findings incrementally.** Append each issue to the report as you discover it. If the session is interrupted, findings are preserved. Never batch all issues for the end.
 - **Never delete output files.** Do not `rm` screenshots, videos, or the report mid-session. Do not close the session and restart. Work forward, not backward.