Dogfood

Use agent-browser Only For Browser Automation

Prerequisites

• A local dev server you can start (bin/dev, rails server, npm run dev, etc.).
• agent-browser installed. Check:
  bashCopy

  command -v agent-browser >/dev/null 2>&1 && echo "Ready" || echo "NOT INSTALLED"

  If not installed, stop and tell the user to install agent-browser (run /ce-setup to print the current install command), then re-run this skill — this workflow cannot function without it.

Reusing Compound-Engineering Skills

Workflow

0. Scope        Pick the branch, get onto it (offer worktree), never touch the trunk
1. Analyze      Diff branch vs trunk, understand every change
2. Map+Matrix   Map user flows as Mermaid flowcharts, then derive the test matrix as a task list
3. Serve        Detect port, start dev server, open agent-browser
4. Execute      Work the matrix one item at a time with agent-browser
5. Fix loop     On failure: fix -> add regression test -> commit -> continue
6. Report       Write durable doc to docs/dogfood-reports/ (flows, matrix, fixes, learnings, verdict)

Phase 0: Scope and Get on the Right Branch

1. Identify the target — keep PR identity; do not switch the working tree yet.
   • PR number: the target is the PR — carry the number through every later step (trunk check, isolation, checkout). Read its head only for display (gh pr view <number> --json headRefName,isCrossRepository), but do not reduce it to a bare branch name: a fork PR's head can even be named main/master. Do not check out yet.
   • Branch name: the target is that branch.
   • Blank: the target is the current branch.
2. Refuse to run on the trunk — branch/blank targets only. If a branch-name or blank target resolves to the trunk (main/master/the detected default), stop — there is no diff to dogfood. A PR is always diffable (it has a base), so this check never applies to a PR target; never refuse /ce-dogfood <number> just because the PR's head branch happens to be named main.
3. Decide isolation by what you're testing; let ce-worktree own the worktree mechanics. Do not re-derive worktree detection or creation here — ce-worktree handles existing-isolation detection, the harness-native tool, attaching to a ref, and the "already checked out" constraint, and reports its decision back. The only call this skill makes is whether to ask for isolation at all:
   • Blank / current-branch target: do not isolate — dogfood in place. You are already on the branch under test, the fix-commits belong on it, and git cannot check the same branch out in a second worktree anyway. (If you happen to already be in a worktree, that is fine — you are simply dogfooding here.)
   • A PR or a different named branch: this is an existing ref to test without disturbing your current checkout. Offer isolation (platform's blocking question tool). On yes, invoke ce-worktree to isolate that target ref — it attaches a worktree to the ref (or, if already isolated, checks it out in place; or reports "already checked out at <path> — work there" when the ref is live elsewhere). Act on ce-worktree's verdict; the primary checkout is never switched. On no, check the target out in place (gh pr checkout <number> for a PR, git checkout <branch> for a branch), confirming first if uncommitted changes would be disturbed.
4. Resume if a prior run exists. Look for an existing report at docs/dogfood-reports/*-<branch-slug>-dogfood.md (see the branch-slug rule under Resumability). If one is found with unfinished scenarios, ask whether to resume it or start fresh. To resume, re-hydrate the task list from its matrix: Pass/Fixed/Skipped stay done; Pending and in_progress become the remaining auto-runnable work. The two Blocked states are not auto-runnable — Blocked (needs human verify) and Blocked (human decision) are waiting on a person, so surface them to the user and ask how to proceed rather than silently re-queuing them.

Resumability (stop and return at any point)

• The task list (the harness's task tool — TaskCreate/TaskUpdate on Claude Code, update_plan on Codex, or the equivalent elsewhere) is the live to-do — one task per matrix scenario. Mark each in_progress when you start it and completed only when it genuinely passes.
• The report doc at docs/dogfood-reports/<YYYY-MM-DD>-<branch-slug>-dogfood.md is the durable checkpoint that survives across sessions. <branch-slug> is the branch name lowercased with every run of non-alphanumeric characters (slashes included) collapsed to a single - (e.g. feature/Foo_Bar -> feature-foo-bar). Create it as soon as the matrix exists (end of Phase 2) by instantiating references/dogfood-report-template.md (read that template now if you haven't) so the checkpoint carries the template-owned section shape from the start — then fill in every scenario at Pending, and update it incrementally — after each scenario is judged and after each fix is committed — not only at the end. An interrupted run must leave a template-shaped checkpoint, not a bare matrix.

Phase 1: Analyze Changes

# Resolve the trunk to a ref that actually exists. Start from the detected
# default name (origin/HEAD, then gh), then fall back to common names. For each
# candidate prefer a local branch; else use the remote-tracking ref QUALIFIED as
# origin/<branch> — an unqualified name resolves via refs/remotes/<name>, NOT
# refs/remotes/origin/<name>, so a remote-only trunk would otherwise miss. This
# qualification applies to the detected default too (PR/CI checkouts often have
# only origin/main, no local main).
DEFAULT=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')
DEFAULT=${DEFAULT:-$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null)}
TRUNK=""
for cand in "$DEFAULT" main master; do
  [ -n "$cand" ] || continue
  if git show-ref --verify --quiet "refs/heads/$cand"; then
    TRUNK=$cand; break
  elif git show-ref --verify --quiet "refs/remotes/origin/$cand"; then
    TRUNK="origin/$cand"; break
  fi
done
TRUNK=${TRUNK:-main}

git diff --name-only "$TRUNK...HEAD"   # what changed
git diff "$TRUNK...HEAD"               # how it changed

Phase 2: Map the Flows, Then Build the Matrix

2a. Map the user flows (required)

Email example: it's not enough that "an email sends." Does it go to the right recipient? When the user clicks through, does the app land on and scroll to the right message? Does the content make sense? Does the whole flow align with the product's vision and UX? The flowchart must carry the click-through and its destination, not stop at "email sent."

2b. Derive the matrix from the flows

Phase 3: Detect Port and Start the Dev Server

agent-browser open "http://localhost:${PORT}"
agent-browser snapshot -i

Phase 4: Execute the Matrix

1. Document what you're testing (the journey and the expected outcome).
2. Drive it with agent-browser — navigate, snapshot for interactive refs, click, fill, submit, follow the journey to its real end state:
   bashCopy

   agent-browser open "http://localhost:${PORT}/<route>"
   agent-browser snapshot -i
   agent-browser click @e1
   agent-browser fill @e2 "value"
   agent-browser screenshot "$(mktemp -d)/<scenario>.png"   # scratch dir, not the repo root
   agent-browser errors      # check console/page errors

   Write transient screenshots to OS temp (e.g. mktemp -d), never the repo root. Only copy a screenshot into the report's location if you intend to embed it in the final report.
3. Judge both correctness and experience: right data, right destination, sensible content, no console errors, and does it feel aligned with the product?
4. Walk it as each persona. Re-run the journey in your head from each primary persona's perspective (from Phase 1) and ask where they'd feel a paper cut — a small friction that wouldn't fail a functional test but degrades the experience: a confusing label, an extra click, an unexpected jump, a slow-feeling step, missing feedback, copy that doesn't match how that persona thinks. A scenario can be functionally Pass yet still carry paper cuts. Note each paper cut, which persona feels it, and its severity.
5. Record pass/fail plus any paper cuts, with specifics. Mark the task completed only when it genuinely passes. Paper cuts do not block a Pass, but a sharp paper cut (one severe enough to fix now) is routed into the Phase 5 fix loop just like a failure — apply the same auto-fix-vs-escalate judgment to it. Log the rest in the report.

Phase 5: Fix Loop (Autonomous)

1. Investigate the root cause. If it's non-obvious, use ce-debug.
2. Apply the fix in the code.
3. Add an automated regression test that fails before the fix and passes after, so the bug can't return. This is the default for behavioral and code bugs. When an automated test is genuinely impractical — a pure copy, spacing, or visual fix with no behavioral assertion to make — substitute a documented browser-replay or screenshot check and state in the report why no automated test was meaningful. Do not invent a hollow test just to satisfy the step.
4. Commit the fix with a clear message (use ce-commit). One logical fix per commit.
5. Re-run the failing scenario in the browser to confirm it now passes; then continue the matrix.
6. If the bug carried a reusable lesson, capture it with ce-compound.

Phase 6: Write the Report Artifact