refactor(aidd-dev): streamline browser QA setup

Keep dependency recovery explicit while preserving deterministic Playwright and video evidence.

Author: alexsoyes

plugins/aidd-dev/CATALOG.md

@@ -161,6 +161,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 | Group | File | Description |
 |-------|------|---|
+| `actions` | [00-prerequisites.md](skills/11-browser-qa/actions/00-prerequisites.md) | - |
 | `actions` | [01-load-scope.md](skills/11-browser-qa/actions/01-load-scope.md) | - |
 | `actions` | [02-prepare-run.md](skills/11-browser-qa/actions/02-prepare-run.md) | - |
 | `actions` | [03-run-scenarios.md](skills/11-browser-qa/actions/03-run-scenarios.md) | - |

plugins/aidd-dev/skills/11-browser-qa/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: 11-browser-qa
 description: Run post-review browser QA and produce short named videos for a locked happy path and sourced browser edge cases. Use when the user wants concise reviewer evidence for a web journey. Not for API, CLI, automated tests, diff review, or application fixes.
-argument-hint: load-scope | prepare-run | run-scenarios
+argument-hint: prerequisites | load-scope | prepare-run | run-scenarios
 ---
 
 # Browser QA
 
 ```mermaid
 flowchart LR
-  scope["load-scope"] --> prepare["prepare-run"] --> run["run-scenarios"]
+  prerequisites["prerequisites"] --> scope["load-scope"] --> prepare["prepare-run"] --> run["run-scenarios"]
 ```
 
 ## Actions
@@ -17,6 +17,7 @@ Read only the next action's file before running it.
 
 | #   | Action          | Does                                                       |
 | --- | --------------- | ---------------------------------------------------------- |
+| 00  | `prerequisites` | Verify the browser runner and media dependencies            |
 | 01  | `load-scope`    | Lock one happy path and a bounded set of sourced edge cases |
 | 02  | `prepare-run`   | Resolve the shortest deterministic path to executable runs |
 | 03  | `run-scenarios` | Record, normalize, verify, reset, and report every scenario |

plugins/aidd-dev/skills/11-browser-qa/actions/00-prerequisites.md

@@ -0,0 +1,28 @@
+# 00 - Prerequisites
+
+Verify the runner dependencies before resolving the QA scope.
+
+## Input
+
+None.
+
+## Output
+
+Verified `npx`, Playwright CLI `0.1.17`, `ffmpeg`, and `ffprobe`.
+
+## Process
+
+1. **Check.** In one pass, resolve `npx`, run `npx --yes @playwright/cli@0.1.17 --version`, and resolve `ffmpeg` and `ffprobe`.
+2. **Continue.** When every check passes, continue without reporting it.
+3. **Resolve.** When a dependency is missing, ask one concise question: the user installs the listed dependencies, or authorizes you to install them now.
+   1. If the user installs them, provide only the shortest platform-appropriate commands and stop until they confirm completion.
+   2. If authorized, install only the missing dependencies, then rerun every check.
+4. **Stop.** Report the shortest decisive error when installation is declined or a recheck fails.
+5. **Protect.** Never add runner or media dependencies to the application manifest.
+
+## Test
+
+- Passing checks produce no message.
+- A missing dependency produces one choice and no unapproved installation.
+- Either installation path reruns every check before continuing.
+- No application dependency file changes.

plugins/aidd-dev/skills/11-browser-qa/actions/02-prepare-run.md

@@ -1,18 +1,18 @@
 # 02 - Prepare Run
 
-Resolve every operational dependency before retained recording begins.
+Resolve the application state and scenario paths before retained recording begins.
 
 ## Input
 
-Earlier defined scope.
+Verified prerequisites and the earlier defined scope.
 
 ## Output
 
-A successfull prepared run with a reachable application, authenticated sessions, deterministic fixtures, executable scenario steps, proven teardown, and available recording and media tools.
+A successful prepared run with a reachable application, authenticated sessions, deterministic fixtures, executable scenario steps, and proven teardown.
 
 ## Process
 
-1. **Preflight.** Batch the independent checks for the application, pinned Playwright CLI, `ffprobe`, `ffmpeg`, and the fixed `1280×720` viewport.
+1. **Preflight.** Check the application and fixed `1280×720` viewport.
 2. **Reuse.** Read `aidd_docs/memory/testing.md` first when it exists. 
    1. Resolve Browser QA entry, auth, fixtures, and reset from its `Browser QA` section, then a directly related browser test, then one targeted browser snapshot. 
    2. Stop searching as soon as the run is executable.

plugins/aidd-dev/skills/11-browser-qa/references/run-scope-playwright-cli.md

@@ -1,37 +1,37 @@
 # Playwright CLI runner
 
-Run browser QA through the Playwright Agent CLI. It produces human-viewable WebM recordings without adding a test dependency to the application.
+Playwright Agent CLI produces WebM evidence without becoming an application dependency.
 
-## Invocation
+## Version and invocation
 
-Use the framework pin below. The current version is `0.1.17`.
+Support `@playwright/cli >= 0.1.17`; execute the framework pin `@playwright/cli@0.1.17`. Upgrade it deliberately, never through `latest` during QA.
 
 ```bash
 npx --yes @playwright/cli@0.1.17 -s=qa-<run-id> <command>
 ```
 
-Upgrade the pin deliberately with the framework, never by using `latest` during a QA run.
+`run-code` takes one `page` argument: pass `async page => { ... }`, never bare statements. Keep stdout, stderr, and exit status visible; no redirects, pipes, command substitutions, or `|| true`. A `SyntaxError` or non-zero exit invalidates the take.
 
-`run-code` receives one `page` argument. Pass a complete function with the exact shape `async page => { ... }`, never bare statements. Keep its stdout, stderr, and exit status visible: never redirect, pipe, use command substitution, append `|| true`, or otherwise mask them. A `SyntaxError` or non-zero exit invalidates the take.
+## Recording
 
-## Recording contract
-
-Use one named session and one raw WebM per scenario. Fix the browser viewport and recording frame at `1280×720`. Reach the prepared initial state before `video-start`. Drive every recorded interaction in one `run-code`; never issue recorded click, fill, or scroll commands separately. Hold the initial state for `1000 ms`. Wait `300 ms` between scenario actions and after every scroll. Verify the observable result, hold it for `1000 ms`, then stop. Run `video-stop` only after `run-code` exits successfully.
+- One named session and raw WebM per scenario; viewport and frame `1280×720`.
+- Reach the initial state before `video-start`; put every recorded interaction in one `run-code`.
+- Never record separate click, fill, or scroll commands.
+- Hold the initial and verified final states for `1000 ms`.
+- Wait `300 ms` between actions and after each scroll.
+- Run `video-stop` only after `run-code` succeeds.
 
 ```bash
 npx --yes @playwright/cli@0.1.17 -s=qa-<run-id>-<scenario-slug> resize 1280 720
 npx --yes @playwright/cli@0.1.17 -s=qa-<run-id>-<scenario-slug> video-start raw-<evidence-name>.webm --size=1280x720
-# Replace the example locators and omit the scroll block when irrelevant.
+# Replace the locators; omit the scroll block when irrelevant.
 npx --yes @playwright/cli@0.1.17 -s=qa-<run-id>-<scenario-slug> run-code 'async page => {
   const pause = milliseconds => page.waitForTimeout(milliseconds);
   await pause(1000);
-
   await page.getByRole("button", { name: "first action" }).click();
   await pause(300);
-
   await page.mouse.wheel(0, 600);
   await pause(300);
-
   await page.getByRole("button", { name: "final action" }).click();
   await page.getByText("observable expected outcome").waitFor({ state: "visible" });
   await pause(1000);
@@ -40,21 +40,21 @@ npx --yes @playwright/cli@0.1.17 -s=qa-<run-id>-<scenario-slug> video-stop
 npx --yes @playwright/cli@0.1.17 -s=qa-<run-id>-<scenario-slug> close
 ```
 
-`video-stop` writes under `.playwright-cli/` in the current directory. Use `raw-happy-path.webm` and `raw-edge-case-<scenario-slug>.webm`.
+`video-stop` writes to `.playwright-cli/` in the current directory. Name raw files `raw-happy-path.webm` or `raw-edge-case-<scenario-slug>.webm`.
 
-## Duration gate
+## Duration
 
-Inspect every raw take in one call.
+Probe each raw take once. Maximum 12 seconds, never a target; do not pad or extend.
 
 ```bash
 ffprobe -v error -select_streams v:0 \
   -show_entries stream=codec_name,width,height:format=duration \
-  -of json raw-<evidence-name>.webm
+  -of json <input.webm>
 ```
 
-Twelve seconds is a maximum, never a target. Never pad or extend a shorter take. When `ffmpeg` is unavailable, only an already-short raw take can pass. A take above 12 seconds reports `blocked: media-postprocess-unavailable`.
+Without `ffmpeg`, only an already-short raw take passes; otherwise report `blocked: media-postprocess-unavailable`.
 
-Never infer the first action from a scene-change threshold and never trim the head: the initial one-second hold is required evidence. Before trimming tail time, extract and inspect frames immediately before and after the proposed cut. Reject a cut that removes the observable result or its final one-second hold.
+Never trim the head or infer the first action from scene changes. Inspect both sides of a tail cut; reject one that removes the result or final one-second hold.
 
 ```bash
 qa_cut_frames=$(mktemp -d)
@@ -64,22 +64,32 @@ ffmpeg -v error -ss <cut-plus-0.25-seconds> -i raw-<evidence-name>.webm \
   -frames:v 1 "$qa_cut_frames/after.png"
 ```
 
-Re-encode without audio. Use only a visually verified tail cut; omit `-to` when none is needed.
+## Normalization
+
+Re-encode without audio. Use only a visually verified tail cut; omit `-to` when unused.
 
 ```bash
 ffmpeg -y -to <verified-end-seconds> -i raw-<evidence-name>.webm \
   -an -vf "fps=12,scale=1280:-2:force_original_aspect_ratio=decrease" \
   -c:v libvpx-vp9 -crf 36 -b:v 0 <evidence-name>.webm
 ```
 
-When the meaningful take still exceeds 12 seconds, remove non-scenario actions and record it again. Never accelerate a take because that invalidates the pacing contract. Report blocked when the required journey cannot fit.
+Above 12 seconds, remove non-scenario actions and record again. Never accelerate. Block when the required journey cannot fit.
+
+## Validation
 
-Inspect the final file with the same `ffprobe` command, then extract frames at four frames per second and inspect them in chronological order. Require the initial state, every scenario action, every transition, and the final observable result to be visible. The initial and final holds must each span at least four sampled frames. `ffprobe` alone never validates a take.
+Probe the final file, then inspect four frames per second chronologically.
 
 ```bash
 qa_final_frames=$(mktemp -d)
 ffmpeg -v error -i <evidence-name>.webm -vf "fps=4" \
   "$qa_final_frames/frame-%03d.png"
 ```
 
-Require codec `vp9`, width `1280`, and duration at most 12 seconds. Remove raw takes, cut-point frames, and final validation frames only after every final WebM passes both gates.
+Require:
+
+- codec `vp9`, width `1280`, duration at most 12 seconds;
+- initial state, every action and transition, and final result visible;
+- initial and final holds spanning at least four sampled frames.
+
+`ffprobe` alone is insufficient. Delete raw takes, cut-point frames, and validation frames only after every final WebM passes both checks.