# Browser QA Integration Implementation Handoff

## Status

- Date: 2026-05-18
- Source type: discussion-to-implementation-doc
- Status: ready for implementation planning
- Intended next step: create and execute the sibling implementation plan.
- Recommended plan: docs/plans/browser-qa-integration/browser-qa-integration-plan.md
- Recommended execution state: docs/plans/browser-qa-integration/browser-qa-integration-execution-state.md

## Purpose

Agent-kit already has browser-facing evidence primitives and thin tool skills,
but it does not yet have one canonical workflow skill that behaves like a QA
engineer for browser-facing acceptance checks. The current `web-qa` name also
does not fit the surrounding agent-kit taxonomy well because it mixes static web
evidence with active browser QA.

This source document captures the naming decision and the implementation
boundary for integrating the existing QA-related browser skills into a coherent
workflow without copying gstack's large self-contained skill style.

## Confirmed Facts

- `web-qa` currently orchestrates static and active browser evidence with
  `web-evidence`, Browser, Chrome, Playwright, and `browser-session`.
- `web-evidence` is static HTTP/HTTPS evidence only. It does not execute
  JavaScript, reuse cookies, drive a browser, or capture screenshots.
- `browser-session` records goals, steps, statuses, and artifact paths. It is an
  evidence ledger, not a browser driver.
- `playwright` is a thin wrapper around the Playwright CLI and requires
  browser artifacts to live under `out/playwright/`.
- `agent-browser` is a legacy fallback for CLI-driven `snapshot -i` / `@ref`
  browser automation when native Browser or Chrome tooling is unavailable or
  insufficient.
- `canary-check`, `test-first-evidence`, `review-evidence`, and `skill-usage`
  already provide adjacent workflow evidence primitives that can be cited by a
  higher-level QA workflow.
- `gh-fix-ci` already points agents at active browser evidence when deploy or
  status evidence requires JavaScript, screenshots, console summaries, DOM
  interaction, authenticated browser state, or deploy preview inspection.
- The current implementation gap is workflow-level orchestration: report-only
  QA, fix-loop QA, acceptance-gate QA, scenario selection from plans, and
  consistent links back to execution state.
- The original gstack analysis retained a useful report shape at
  `out/projects/graysurf__agent-kit/20260517-142040-gstack-analysis/gstack/qa/templates/qa-report-template.md`.
  It includes a 0-100 health score, category scores, before/after evidence, and
  Ship Readiness summary fields.

## Naming Evaluation

### Recommended Name

Use `browser-qa` as the canonical workflow skill name.

Reasons:

- It matches existing repo taxonomy that already distinguishes Browser Runtime
  and Browser Evidence.
- It describes the active surface accurately: Browser, Chrome, Playwright,
  screenshots, DOM observations, console summaries, network summaries, and
  authenticated browser state.
- It keeps `web-evidence` available for static HTTP/HTTPS checks while avoiding
  the overloaded `web-qa` phrase.
- It is short enough to be a natural skill invocation while still clearly
  workflow-level.

### Names Rejected

- `web-qa`: too broad and ambiguous; "web" sounds like URL/static HTTP checks,
  while the intended workflow is real browser QA.
- `browser-qa-evidence`: accurate but too tool-like for the canonical workflow
  entrypoint.
- `browser-evidence`: hides the QA workflow and sounds like a primitive.
- `runtime-qa`: too broad for a browser-specific workflow and likely to collide
  with non-browser runtime checks.
- `qa-browser`: less idiomatic than `browser-qa` and inconsistent with the
  existing noun-purpose skill names.

## Decisions

- Add `browser-qa` as the canonical high-level workflow skill under
  `skills/workflows/qa/browser-qa/`.
- Keep `web-qa` as a temporary compatibility alias or transition note rather
  than the canonical entrypoint.
- Do not add a new browser daemon, persistent browser service, or gstack-style
  generated preamble in this implementation slice.
- Keep deterministic capture and record behavior in existing primitives such as
  `web-evidence`, `browser-session`, `canary-check`, `test-first-evidence`, and
  `review-evidence`.
- Let `browser-qa` own judgment and orchestration: mode selection, scenario
  selection, evidence requirements, fix-loop boundaries, redaction rules, and
  execution-state linkage.
- Adopt the gstack QA report template shape under
  `skills/workflows/qa/browser-qa/assets/templates/qa-report-template.md`; do not place
  it under compatibility `web-qa` or copy gstack's broader `/qa` skill.

## Scope

- Create the canonical `browser-qa` workflow skill.
- Integrate existing browser and evidence skills into one QA workflow contract.
- Rename or de-emphasize `web-qa` so future agents discover `browser-qa` first.
- Update catalog docs, tooling index docs, and nearby automation workflows that
  currently mention `web-qa`.
- Add focused tests that preserve naming, compatibility, artifact, and redaction
  contracts.
- Add a reusable browser QA report template with 0-100 scoring dimensions,
  before/after screenshot fields, and Ship Readiness summary fields.
- Add plan/execution guidance so UI or browser-facing work can require
  browser-session evidence when appropriate.

## Non-Scope

- Do not implement a new nils-cli browser driver in this repo.
- Do not replace project-owned Playwright or E2E test suites.
- Do not persist raw cookies, credentials, auth headers, secret URLs, unredacted
  network logs, customer data, or Chrome profile state.
- Do not bypass CAPTCHA, MFA, payments, destructive flows, or access controls.
- Do not create a large gstack-style all-in-one skill that duplicates shared
  policy and primitive behavior.
- Do not treat QA report scores as evidence by themselves; they must summarize
  cited browser/session artifacts or be marked untested.
- Do not require browser QA for every implementation task; require it only when
  acceptance depends on browser behavior, screenshots, layout, JavaScript, DOM
  interaction, authenticated browser state, console output, network behavior, or
  deploy-preview inspection.

## Implementation Boundaries

`browser-qa` should be a workflow skill, not a new tool primitive. It should
coordinate the existing tools as follows:

- Use `web-evidence` for static URL checks when status, headers, redirects, and
  redacted text preview are sufficient.
- Use Browser or Chrome for interactive inspection, local targets, authenticated
  browser state, or user-profile-dependent checks.
- Use Playwright when a repeatable CLI-driven browser path is better than
  interactive inspection and the target does not require the user's existing
  Chrome state.
- Use `agent-browser` only as a legacy fallback when `snapshot -i` / `@ref`
  behavior is needed or native tooling is unavailable.
- Use `browser-session` to record browser QA goals, executed steps, statuses,
  and artifact paths.
- Use `test-first-evidence` before behavior-changing fixes discovered through
  QA when a failing test or explicit waiver is needed.
- Use `canary-check` for one caller-owned post-fix command that is not already a
  project-required test gate.
- Use `review-evidence` when a QA finding becomes a review finding or final
  validation record.
- Use `skill-usage` only when the workflow invocation itself needs retained
  evidence.

## Requirements

- The canonical entrypoint is `browser-qa`.
- Existing `web-qa` references are either migrated or left as explicit
  compatibility references that point to `browser-qa`.
- The new skill supports at least these workflow modes:
  - report-only: inspect and report findings without editing.
  - fix-loop: reproduce, fix within scope, validate, and record before/after
    evidence.
  - acceptance-gate: prove or disprove a browser-facing acceptance criterion for
    plan execution, release, CI, issue follow-up, or PR delivery.
- Active browser success cannot be recorded without a real browser action and at
  least one artifact or observation recorded in `browser-session`.
- Browser QA evidence must be redacted and project-scoped.
- Browser QA reports should use the canonical template when the user asks for a
  report, a fix-loop summary, or a ship-readiness decision.
- Plan execution can link browser QA evidence from execution state without
  copying large reports into plan documents.

## Acceptance Criteria

- `skills/workflows/qa/browser-qa/SKILL.md` exists, passes skill contract
  validation, and explains when to use `browser-qa`.
- `web-qa` no longer appears as the preferred canonical QA entrypoint in README
  or tooling index docs.
- Any retained `web-qa` skill clearly states its compatibility status and points
  agents to `browser-qa` for new work.
- README and tooling index list browser QA in the workflow layer while preserving
  lower-level Browser Runtime and Browser Evidence tools.
- Automation workflows that previously referenced `web-qa active mode` point to
  `browser-qa` or clearly distinguish primitive evidence from the workflow.
- Tests cover the new skill contract, catalog references, compatibility status,
  redaction guardrails, and plan/execution browser evidence guidance.
- Tests cover the QA report template's 0-100 health/category scores,
  before/after evidence fields, and Ship Readiness section.
- Repository docs and markdown checks pass.

## Validation Plan

Recommended commands for implementation:

```bash
scripts/check.sh --tests -- -k 'browser_qa or web_qa or agent_workflow_primitives or gh_fix_ci or release_workflow or issue_follow_up or plan_workflow'
scripts/check.sh --docs
scripts/check.sh --markdown
scripts/check.sh --all
```

Before commit, run:

```bash
scripts/check.sh --pre-commit
```

## Risks And Guardrails

- Avoid turning `browser-qa` into a fat copy of gstack `/qa`; keep shared
  primitives and project policy in their existing layers.
- Avoid breaking existing agents that still invoke `web-qa`; use a compatibility
  window unless implementation intentionally chooses a breaking removal.
- Do not let `browser-session` appear to drive a browser. It records evidence
  only.
- Do not let static `web-evidence` satisfy claims that require JavaScript,
  screenshots, layout, DOM interaction, authenticated state, console logs, or
  network behavior.
- Keep run artifacts out of commits unless a project explicitly defines a
  retained, redacted evidence path.

## Execution

- Recommended next artifact:
  `docs/plans/browser-qa-integration/browser-qa-integration-plan.md`
- Recommended execution-state path:
  `docs/plans/browser-qa-integration/browser-qa-integration-execution-state.md`
- Current execution status: complete.

## Retention Intent

This document is temporary implementation source material for the plan bundle.
After the implementation lands, durable guidance should live in the new
`browser-qa` skill, catalog docs, tooling index, and affected workflow skills.
The plan-source folder can then be cleaned up through the normal plan cleanup
flow when no longer useful.
