exploratory-session

---
name: exploratory-session
description: Runs one timeboxed exploratory-testing session on a shipped feature of a web app, driving Chrome through Claude in Chrome and checking what the UI shows against the project's own data reads. Use for "try to break X", "test the checkout flow in scenarios we haven't thought of", "poke at the signup for a bit", or when handed a charter to run, even if the skill is not named. Not for brainstorming ideas, running the automated suite, writing an e2e test, an eval run, or testing an API or agent on its own.
---

# exploratory-session

**Scope: the web app, used through its UI.** The thing under test is the app at
`app.url` in `.exploratory.json`, used the way `app.user` uses it in a
browser. Backends and in-app agents are exercised through that UI; reading
them directly checks what the UI shows and never replaces using the app.

Read `references/output-style.md` before writing any output. Read
`references/oracles.md` when tagging an observation or reading an oracle's
output. Read `references/sheet-template.md` when starting the sheet.

`explore.py` below means `scripts/explore.py` in this skill's folder, run from
inside the repo under test.

## Input

A charter (a `charters.md` path plus a number) or a free-text mission. A
mission becomes a one-line charter in Hendrickson's form, using
`../exploratory-charter/references/heuristics.md` to pick attacks.

## Preflight

Session folder: `.exploratory/<YYYY-MM-DD>-<slug>/` (gitignored).

1. `explore.py check`. No config: stop and suggest
   `/exploratory-testing:setup`. Note the oracles, `stack.forbidden`, the
   `limits` and `app.origins` it prints. If anything later fails in a way
   that looks like setup (browser, login, an oracle), run `explore.py doctor`
   and follow its fixes before going on.
2. `explore.py preflight <session-dir>`: records the stack status, checks
   health, writes `ledger-before.json`, prints the start time to use as
   `--since`, and turns the session guard on (a hook that denies forbidden
   commands, writes outside `.exploratory/`, `.env` reads and navigation off
   the app until `explore.py end`).
3. Browser: `explore.py login` attaches to (or launches) the explore Chrome
   and logs in by the configured script, printing only `logged in` or `already
   logged in`. Then find which connected browser it is: run `explore.py
   identify` (it prints a fresh marker URL, `app.url#<marker>`). Call
   `list_connected_browsers`; for each browser in turn, `select_browser` it,
   open a tab with `tabs_create_mcp`, `navigate` it to the marker URL, and run
   `explore.py identify --check <marker>`. `YES` means this is the explore
   browser: work in that tab. `NO` means it is not: close that tab
   (`tabs_close_mcp`) and try the next. If none says `YES`, stop and ask the
   owner; never drive a browser you have not identified this way. With no
   `browser.login`, ask the owner to log in by hand in that tab, and wait.
4. `scripts/record.sh start <session-dir> <n>` records only the explore window
   in fixed chunks (`recording-<n>-partNN.mov`). On exit 2 (not macOS,
   disabled, or no on-screen explore window) continue and say so on the sheet;
   it never falls back to recording the display.

## Loop

Start from a fresh object: create a new one through the UI (a new cart, a new
document) rather than opening an existing one, and note its ledger id. Act in
Chrome on `app.url`. After each meaningful step, check the page's
console and network (filtered to `app.origins`) and read the relevant data
oracle: `explore.py read <tag> <id> <session-dir>` (each read is kept as
`read-<tag>-<id>-NN`, so cite the file). After each in-app agent
turn, read the spend oracle if one is configured. Record every object you
create (by its ledger id). Write each observation with exactly one oracle tag.

## Stops

Whichever comes first, named on the sheet: `limits.minutes`, `limits.turns`
agent chat turns (a charter may raise it to `limits.maxTurns`), and
`limits.spend` as reported by the spend oracle (a charter may raise it to
`limits.maxSpend`). On the login page mid-session, log in once more as in
preflight; if it is still there, stop and report.

## End

1. `explore.py end <session-dir> <created-id>...`: records the end stack
   status (says whether it moved), diffs the ledger (exit 3 is a breach) and
   turns the session guard off. Run it even when stopping early.
2. If the stack moved, mark it at the top of the sheet; list any breach first.
3. `scripts/record.sh stop <session-dir>` (the running chunk finishes on its own).
4. Finish with two or three lines in chat plus the sheet path.

## Rules, and why

- **Never enter credentials, and never read `.env`.** Log in by
  `explore.py login` or the owner's hand. A password typed through the
  browser tool would land in the transcript. Do not fill a login form, ever.
- **Never run a command in `stack.forbidden`, and never start, stop, update or
  reset the stack.** The owner owns its lifecycle. If its status moved
  mid-session, later observations are flaky until reproduced, because the
  app may have been redeployed under you.
- **Never act on an object you did not create.** The ledger diff turns any
  change to another object into a guardrail breach and voids the session as
  evidence.
- **Never delete data and never edit files outside `.exploratory/`.**
  Exploration reports; fixes go through the team's normal planning.
- **Adapters hold any secret; you never see it.** Read data only through
  `explore.py read`; do not mint, print or log a token, and do not query a
  database or trace store by hand.
- **A bug needs a deciding data oracle, a built-in deciding oracle or a spec
  scenario.** A consistency-only (`hiccupps:`) claim stays a question until
  reproduced, because AI testers report confident false bugs. Reply prose and
  how the screen looks are evidence only.
- **Never propose a feature.** An "it should also..." idea is a question for
  the owner.
- **A browser tool that times out right after an action usually means a native
  dialog (alert, confirm, a "leave site?" prompt) is open; it blocks the
  browser tools.** Do not retry the action. Record what you did and the hang
  as an observation (`console`, with "native dialog suspected"), ask the owner
  to dismiss it, and continue once they have. A native dialog the app opens on
  an ordinary action is itself worth a question.
- **If a trace or read looks empty right after an action, re-read once before
  tagging it**; trace stores lag ingestion by a few seconds.

• SKILL.md 6 KB
• references/oracles.md 2 KB
• references/output-style.md 2 KB
• references/sheet-template.md 1 KB
• scripts/explore.py 31 KB
• scripts/record.sh 4 KB