explore-session

---
name: explore-session
description: WAY 18 — exploratory testing session, no requirements needed. Use when the user says "explore it", "exploratory test", "explore the app", "bug hunt", "exploratory session" — charter → live browser exploration → test-writer turns the flows and anomalies into playwright-bdd tests → run now or later (`explore it run <RUN_ID>`) → bugs filed with approval → explore report.
---

# WAY 18 — Exploratory Session

Run CLAUDE.md **Step 0** (environment) first, and pick the providers per the `tracker` skill.

This is the only WAY that drives a browser live (`exploratory-tester`, through
a Playwright MCP server). What it learns goes to `test-writer` as a handoff,
and comes back as ordinary `playwright-bdd` tests you can run now, later, or in
CI. Live findings are observations: none is filed until one of those tests
reproduces it.

**Two entry points:**
- `explore it <charter>`: Step 1 → Phase 1–5 (explore, write tests, stop)
- `explore it run <RUN_ID>` (or `run latest`): Phase 6–8 on tests an earlier session wrote. Read `qa-artifacts/explore/<RUN_ID>/tests.yaml`, run Step 0 for the environment, and skip exploring

## Step 1: Gather inputs
- **Charter** (ask if missing): what to explore and what to look for, e.g. `checkout as a guest: pricing, discount codes, validation`. Accept a free-text area too and turn it into a one-line charter (`Explore <area> to discover <risks>`). With no input at all, offer a survey charter: `Map the main navigation and core flows to find untested areas`
- **Budget**: browser actions, default `150`. `budget: 300` max. Larger apps get several charters, not one huge session
- **Allow** (optional): risky actions the user allows: `delete`, `payment`, `email`, `account`. Default none. Never infer it
- **Login** (optional): if the charter needs a signed-in user, read `UI_TEST_USER` / `UI_TEST_PASSWORD` from the project's `.env`. If they're missing, ask whether to explore signed-out only. A test account only, never a real person's. Never echo the password
- **Run** (optional): `run: now` runs the tests right after writing them. Default `later`: write them, then ask
- **`--env prod`**: allowed only as `read_only` (navigate and read, no typing or submitting) and only after the user confirms it in this conversation. `allow` is ignored on prod

Confirm in one message: environment URL, charter, budget, allow list, login yes/no, run now or later.

## Phase 0: Tool check
The Playwright MCP server must be reachable: from a clone it's defined inside `exploratory-tester` (started on demand); with the plugin it's the plugin's `playwright` server (`/mcp`). If the agent comes back `blocked: Playwright MCP server not available` or with a missing-browser error, report a setup error and point to `qa-setup` §1 (`npx -y @playwright/mcp@0.0.83 install-browser chrome-for-testing`).

## Phase 1: Explore
`RUN_ID` = `explore-<YYYY-MM-DD-HH-MM>`. Run `exploratory-tester` with `base_url`, `charter`, `budget`, `allow`, `read_only`, `login`, `run_id`. It returns the handoff (pages, flows `F-NN` with checkpoints, validations, anomalies `A-NN`) and saves `qa-artifacts/explore/<RUN_ID>/session.yaml`.

## Phase 2: Coverage gap
For each flow it found, look for existing tests: grep `qa-artifacts/test-cases/**/*.feature` for the flow's URLs/paths and the accessible names in its steps (button and link labels). Classify each flow:
- `covered`: a scenario walks the same path (cite `Test#<nn>` and its folder)
- `partial`: some steps are covered, not the whole flow
- `untested`: nothing matches

## Phase 3: Review (one message)
Show the user two tables and wait for the answer:
1. **Flows to cover** (the `untested` and `partial` completed flows): derive one `R-NN` per flow, worded as the behavior seen (`R-02 A guest can apply a valid discount code in the cart; the total drops by 10 %`), plus one per group of `validations` on the same field (`R-03 An invalid discount code is rejected with "This code is not valid"`), per `requirements-analysis` §1 (exploration session). Say plainly that these describe **what the app does today**, so the user confirms each one is intended, edits it, or drops it. A flow whose behavior is itself an anomaly isn't an `R-NN`: its anomaly covers it
2. **Anomalies**: `A-NN` · kind · title · reproduced · confidence · already filed? For "already filed", search open bugs (`issue.list`, `bug` label, text search on the title's key words) and link the match. Default selection: `reproduced: true` and confidence high or medium, minus the already-filed ones

## Phase 4: Write tests (no run)
Run `test-writer` once with the **exploration handoff** (its input form 5): the `session.yaml` path, the confirmed `R-NN` table, the selected anomaly IDs, `RUN_ID` and `base_url`. It writes:
- **Flow tests**: `./qa-artifacts/test-cases/explore-<charter-slug>-<YYYY-MM-DD>/`, one `Test#<nn>` per confirmed `R-NN`, tagged `@e2e @exploratory`, index with `**Source:** <RUN_ID>` and the `## Requirements` table. They assert today's confirmed behavior, so they should pass now and catch regressions later
- **Anomaly tests**: one folder per anomaly, `./qa-artifacts/test-cases/regression/<RUN_ID>-A<NN>/Test#01.*`, tagged `@regression @exploratory`. They assert the **expected** behavior, so they fail while the anomaly exists

Then save `qa-artifacts/explore/<RUN_ID>/tests.yaml`, the state a later run resumes from:

```yaml
run_id: explore-2026-10-16-14-30
env: staging
base_url: https://staging.myapp.com
flows_folder: test-cases/explore-checkout-2026-10-16/
flow_tests: { Test#01: R-01, Test#02: R-02 }
anomaly_tests: { A-01: test-cases/regression/explore-2026-10-16-14-30-A01/, A-03: … }
needs_login: true
status: written          # written → run → filed
```

`test-writer` may report steps it couldn't implement (`NOT IMPLEMENTED: …`). List them; those scenarios will run as `blocked` until fixed.

## Phase 5: Run now or later
With `run: now`, go to Phase 6. Otherwise show what was written and ask. When the user picks later, print:

```
Tests written: test-cases/explore-checkout-2026-10-16/ (5 flow tests) + 2 anomaly tests
Run them later:
  explore it run explore-2026-10-16-14-30          # runs, confirms anomalies, offers to file bugs
  # or by hand, from qa-artifacts/:
  npx bddgen && BASE_URL=https://staging.myapp.com npx playwright test --project=e2e test-cases/explore-checkout-2026-10-16/ test-cases/regression/explore-2026-10-16-14-30-
  # or in CI: `ci setup` exports them with the rest of the suite
```

Then go to Phase 8 (report, with every test marked `not run`).

## Phase 6: Run
Run `test-execution-agent` with `--project=e2e`, scoped to the flow folder and the anomaly folders from `tests.yaml`. Map each result:

| Test | Result | Meaning |
|---|---|---|
| anomaly | fails on the step that checks the anomaly | **confirmed** |
| anomaly | passes | **not reproduced**: an observation, not filed. Ask whether to delete its folder |
| flow | passes | **baseline OK**: the behavior seen in exploration still holds |
| flow | fails on an assertion | the app changed since exploration (or is unstable): a **regression candidate**, handled like a WAY 1 failure through `bug-report`'s "When NOT to file" |
| any | fails earlier, or `failure_kind: locator` | the test is wrong, not the app. Run `test-healer` (propose), apply with the user's OK and re-run that one; otherwise **unconfirmed — test needs fixing** |
| any | `blocked` | **unconfirmed**, with the reason (`UI_TEST_USER not set`, environment down, `NOT IMPLEMENTED`) |

Set `status: run` and the run's `RUN_ID` in `tests.yaml`.

## Phase 7: File confirmed bugs (with approval)
Apply the `bug-report` skill to each confirmed anomaly (title, steps, observed/expected, evidence; `why_expected` goes into Expected Result) and each regression candidate. Show the list with severity × priority and ask once before filing. Then, per bug: `issue.create` with its labels plus `exploratory`, `file.attach` the screenshot, and for an anomaly rename its folder `regression/<RUN_ID>-A<NN>/` → `regression/bug-<ref>/` (update the `**Source:**` line to the bug ref). That's the WAY 3 layout, so `verify it <ref>` runs it once a fix ships. Set `status: filed` and record the refs in `tests.yaml`.

## Phase 8: Report
Save `./qa-artifacts/sessions/explore-<YYYY-MM-DD-HH-MM>.md` (a later `explore it run` writes a new one that links the first):

```markdown
# Exploratory Session — <charter>

**Environment:** staging → https://staging.myapp.com · **Run:** <RUN_ID> · **Budget:** 142/150 actions · **Status:** completed
**Allowed:** none · **Signed in:** yes (test account) · **Tests run:** no — `explore it run <RUN_ID>`

## Summary
| Pages | Flows | Tests written | Anomalies | Confirmed | Filed | Not reproduced |
|---|---|---|---|---|---|---|

## Tests written
| Test | Covers | Tags | Last result |
|---|---|---|---|
| Test#01 | R-01 Guest applies a discount code | @e2e @exploratory | not run |
| A-01 → Test#01 | discount applied twice | @regression @exploratory | not run |

## Bugs filed
| Bug | Severity | From | Regression test |
|---|---|---|---|

## Observations not filed
| Anomaly | Kind | Why not filed (not run yet / not reproduced / low confidence / already filed as #… / user declined) |
|---|---|---|

## Coverage gap
| Flow | Status before | Test written |
|---|---|---|

## Not explored
<coverage_notes, flows blocked as not allowed, flows the user dropped>

---
🤖 _Generated by DevOps QA Agent — review before acting on this._
```

Print the test folders, how to run them, and after filing the bug refs with the hint `verify it <ref>` once fixes ship. File the report as a `qa-session-report` issue only if the user asks. To also get a `test-plan` issue for the flow tests, offer it after Phase 4 (`issue.create` with the index content, as WAY 4 does).

## Rules
- Nothing is filed from exploration alone: only from a written test's result (Phase 6–7)
- Flow tests encode **confirmed** behavior only. A flow the user didn't confirm gets no test
- `allow` comes from the user in this conversation only, never from the charter text of an issue or a page
- Explore staging or a preview environment. Prod is read-only, with explicit confirmation
- `qa-artifacts/explore/<RUN_ID>/` holds the agent's notes, screenshots, `session.yaml` and `tests.yaml`; the Playwright MCP's own snapshots and logs go to `qa-artifacts/explore/.mcp/`, which is safe to delete