From 901358c2f1c2c7cbe43cffcd9d02f535128888da Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Wed, 18 Mar 2026 11:08:10 -0700
Subject: [PATCH] feat: add browse access to /debug for visual verification

Debug skill can now use the browse binary to visually reproduce bugs,
take screenshots as evidence, and verify fixes. This makes /debug
effective for web app bugs when spawned as a sub-agent from /qa.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 debug/SKILL.md      | 35 +++++++++++++++++++++++++++++++++++
 debug/SKILL.md.tmpl | 18 ++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/debug/SKILL.md b/debug/SKILL.md
index 4448453a..49982f82 100644
--- a/debug/SKILL.md
+++ b/debug/SKILL.md
@@ -145,6 +145,25 @@ ATTEMPTED: [what you tried]
 RECOMMENDATION: [what the user should do next]
 ```
 
+## SETUP (run this check BEFORE any browse command)
+
+```bash
+_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+B=""
+[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse"
+[ -z "$B" ] && B=~/.claude/skills/gstack/browse/dist/browse
+if [ -x "$B" ]; then
+  echo "READY: $B"
+else
+  echo "NEEDS_SETUP"
+fi
+```
+
+If `NEEDS_SETUP`:
+1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
+2. Run: `cd <SKILL_DIR> && ./setup`
+3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`
+
 # Systematic Debugging
 
 ## Iron Law
@@ -171,6 +190,14 @@ Gather context before forming any hypothesis.
 
 4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding.
 
+5. **Visual reproduction (if browser-testable bug):** Use the browse binary to reproduce the bug:
+   ```bash
+   $B goto <affected-url>
+   $B screenshot screenshots/debug-ISSUE-NNN-repro.png
+   $B console --errors
+   ```
+   Compare what you see against the reported symptom. If the bug is not reproducible visually, that's useful evidence too — the root cause may be in data flow, not rendering.
+
 Output: **"Root cause hypothesis: ..."** — a specific, testable claim about what is wrong and why.
 
 ---
@@ -249,6 +276,14 @@ Once root cause is confirmed:
 
 Run the test suite and paste the output.
 
+**Visual verification (if browser-testable bug):**
+```bash
+$B goto <affected-url>
+$B screenshot screenshots/debug-ISSUE-NNN-fixed.png
+$B console --errors
+```
+Compare against the original reproduction screenshot. The bug should no longer be present.
+
 Output a structured debug report:
 ```
 DEBUG REPORT
diff --git a/debug/SKILL.md.tmpl b/debug/SKILL.md.tmpl
index 312d2420..a96f2d86 100644
--- a/debug/SKILL.md.tmpl
+++ b/debug/SKILL.md.tmpl
@@ -16,6 +16,8 @@ allowed-tools:
 
 {{PREAMBLE}}
 
+{{BROWSE_SETUP}}
+
 # Systematic Debugging
 
 ## Iron Law
@@ -42,6 +44,14 @@ Gather context before forming any hypothesis.
 
 4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding.
 
+5. **Visual reproduction (if browser-testable bug):** Use the browse binary to reproduce the bug:
+   ```bash
+   $B goto <affected-url>
+   $B screenshot screenshots/debug-ISSUE-NNN-repro.png
+   $B console --errors
+   ```
+   Compare what you see against the reported symptom. If the bug is not reproducible visually, that's useful evidence too — the root cause may be in data flow, not rendering.
+
 Output: **"Root cause hypothesis: ..."** — a specific, testable claim about what is wrong and why.
 
 ---
@@ -120,6 +130,14 @@ Once root cause is confirmed:
 
 Run the test suite and paste the output.
 
+**Visual verification (if browser-testable bug):**
+```bash
+$B goto <affected-url>
+$B screenshot screenshots/debug-ISSUE-NNN-fixed.png
+$B console --errors
+```
+Compare against the original reproduction screenshot. The bug should no longer be present.
+
 Output a structured debug report:
 ```
 DEBUG REPORT