BugBug

View saved version →

---
name: bugbug-context-discovering
description: Discovers BugBug project, repository, and tested-application context. Always run this skill before any other BugBug skill, including test authoring, step authoring, selector authoring, test debugging, test refactoring, project reporting, or YAML work. Project list checks are exluded.
---

# BugBug Context Discovering

## Preflight

1. Resolve the target BugBug project before reading or mutating project data.
2. Capture repository state before relying on local source evidence or editing
   local files.
3. If the current repository appears to be the app under test, inspect the
   tested-application repository context before using source-code evidence.

## Inputs

- User request, current workspace, available BugBug session context, linked
  `bugbug.yaml`, and any project, test, suite, run, or URL identifiers.
- Optional tested-application source code when the current workspace is the app
  under test.

## Safety

- Do not mutate BugBug data while discovering context.
- Do not expose secrets from `bugbug.yaml`, environment files, credentials, or
  local configuration.
- Treat existing uncommitted changes as user-owned.
- Stop before platform mutation when the target project cannot be confirmed.

## Workflow

1. Read `references/project-context.md` to resolve or confirm the BugBug project.
2. Read `references/repository-state.md` to capture local Git state when a shell
   and repository are available. Skip this step on MCP-only clients.
3. Read `references/tested-app-repository-context.md` only when the current
   repository may be the tested application and source evidence would affect the
   work. Skip this step on MCP-only clients.
4. When the next skill will create, move, or organize tests or components,
   read the folder structure as described in `references/project-context.md`.
5. Carry the discovered project id, folder structure, repository state, and
   tested-app evidence into the next BugBug skill.

### MCP-Only Clients

When the client has no shell or filesystem, steps 2 and 3 do not apply. Resolve
the project from a caller-supplied id or `bugbug_list_projects`, then continue
to the next skill with the project id alone. Missing repository state is an
expected condition on these clients, not a blocker — do not stop the work for
it, and do not ask the user to create or link a `bugbug.yaml`.

## Output

- Confirmed project id or the blocker preventing confirmation.
- Test and component folder paths with ids, when the work places or organizes
  tests or components.
- Relevant dirty repository files or statement that repository state could not
  be captured.
- Tested-app source evidence used, or confirmation that none was needed.
- Any context limits that affect authoring, debugging, refactoring, reporting, or
  YAML work.
- Preference of work type: directly on platform vs yaml in current linked repository

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Read `references/project-context.md` to resolve the target BugBug project.
- Read `references/repository-state.md` before relying on local source evidence
  or editing local files.
- Read `references/tested-app-repository-context.md` before using the tested
  application's source code as evidence.

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-project-reporting
description: Creates read-only BugBug project health reports for PM and QA audiences using run-history aggregates and optional export-based inventory analysis. Use for project health, trends, release risk, flakiness, stale tests, or coverage reporting. Run bugbug-context-discovering first.
---

# BugBug Project Reporting

## Preflight

1. Run `bugbug-context-discovering` without changing platform state.
2. Determine whether the audience is PM, QA, or both.
3. Confirm the reporting window and project scope.

## Inputs

- Target BugBug project.
- Reporting audience: PM, QA, or both.
- Reporting window. Default to 30 days and keep it at or below 90 days.
- Optional project export when inventory, coverage, suite organization, or
  maintenance-debt context is needed.

## Safety

- Use read-only actions. Never mutate BugBug data.
- Stop before any cleanup, rename, delete, run, or suite change; reporting
  findings do not authorize platform mutations.
- Use existing run-list tools for run history; run history is not part of project
  export snapshots.
- Use project export only for inventory, coverage, suite organization, and
  maintenance-debt context.

## Workflow

1. Page `bugbug_list_test_runs` and `bugbug_list_suite_runs` across the bounded
   reporting window.
2. Export the project once when inventory, suite, component, or coverage context
   is required.
3. Aggregate pass rate, failures, flakiness, staleness, and maintenance signals
   supported by the available evidence.
4. Produce the audience-specific report.
5. If evidence is insufficient to support a trend, coverage claim, or failure
   class, state the limitation instead of filling the gap with inference.

Until backend aggregation endpoints exist, aggregate bounded run-list pages in
the skill workflow and return summary data only.

## Output

### PM report

- Executive summary.
- Feature or flow coverage gaps.
- Trend versus the previous period when available.
- Risks affecting release confidence.
- Recommended actions in product language.

### QA report

- Pass rate, top failing tests, flaky tests, and stale tests.
- Suite health and maintenance debt.
- Failure classes when evidence is available.
- Verification and cleanup actions in execution order.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Load `bugbug-context-discovering` during Preflight.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-selectors-authoring
description: Authors, reviews, repairs, and optimizes BugBug element selectors. Use before creating or changing any DOM-targeted step, assertion, condition, visual region, drag target, upload target, or selector preset. Run bugbug-context-discovering first.
---

# BugBug Selectors Authoring

Canonical rules for authoring BugBug element selectors. Follow this when
designing, creating, reviewing, repairing, or optimizing any step that targets a
DOM element. Use it as an authoring and validation checklist, and validate
authored selectors with real runs.

## Preflight

1. Run `bugbug-context-discovering` before using project or source-code evidence.
2. Confirm the step intent, target element role, page context, and available DOM
   or screenshot evidence.
3. When source code for the tested app is available, prefer confirmed stable test
   attributes or accessible names from source evidence.

## Inputs

- Step intent and step type.
- Existing `selectorsPresets` when editing or repairing.
- DOM snapshot, queried element details, screenshots, logs, and optional tested
  application source context.
- Optional page context: shadow dom/iframe/window context, virtual scroll, responsive state.

## Safety

- Do not invent selectors without observed DOM or source evidence.
- Do not use framework internals, generated IDs, deep indexes, dynamic text, or
  absolute structure unless no better target exists and the brittleness is
  documented.
- Keep assertion expectations out of selectors when assertion fields can express
  them.

## Workflow

1. Decide whether a selector is **required** for the step type.
2. Pick the target element **role**: action target, assertion target, drag
   source, drag drop target, or visual-regression region.
3. Choose the shortest stable selector from the preferred strategy order below,
   and add at least 3 possible stable selectors following that order.
4. Build a **new active preset** as the preferred path.
5. Verify uniqueness with DOM evidence via `bugbug_query_dom_snapshot_element`;
   interaction targets normally need a single match.
6. Use selector groups for element relationships and presets for alternatives.
   Do not confuse a group chain (a relationship) with fallback alternatives
   (selectors inside one group).
7. Check whether page elements have stable attributes. If they do not and the
   related code is available, suggest adding new stable attributes.
8. Run the affected test when a live URL and profile are available.

### Author-Verify Loop

1. Choose the shortest stable candidate from the priority order.
2. Verify uniqueness with `bugbug_query_dom_snapshot_element`.
3. Require `matchCount === 1` for interaction targets unless the step
   intentionally targets a repeated collection item through a parent/child chain.
4. If non-unique, anchor to a stable parent or choose a stronger attribute — read
   *Removing a position index* in `references/strategies.md`.
5. Run the affected test when a live URL exists.

### Selector Data Model

- **Presets are alternatives.** Each is tried as an independent whole path, so
  write every preset to stand on its own.
- **Groups inside one preset form a chain.** The first group finds the base
  element; each later group resolves **relative to the previous group's result**,
  by `relation`: `descendant` (`>>`) queries inside it, `ancestor` (`<<`)
  searches its parents, `sibling` (`~`) searches siblings via its parent.
- **Selectors inside one group are alternatives.** An active, valid selector is
  preferred; otherwise the remaining candidates are probed and one may be
  promoted to active after a successful run. Order them best-first.
- Do not add `xpath=` or `css=` prefixes to API selectors. Prefixes belong only
  in YAML local-file shorthand.
- A short note whenever a brittle selector is unavoidable.

Read `references/presets.md` for payload shapes, the YAML shorthand, and worked
examples of each chain pattern.

### Preferred authoring strategy order

This is the canonical ranking. Prefer the earliest tier that yields a stable,
unique selector, and use it whenever you compare two candidates.

1. **Custom test attributes** configured for the project (`data-testid`,
   `data-test`, or the project's own convention).
2. **Text and text-like attributes**: user-facing text, `placeholder`, `alt`,
   `title`, `aria-label`, `aria-description` — only when stable, not volatile or
   localized.
3. **Form name** (`name`), when not generated.
4. **Id**, when not generated or dynamic.
5. **A semantically unique tag** (`title`, `body`, `html`).
6. **A unique non-dynamic attribute** (`type`, `role`, …) that is unique on its
   own.
7. **ARIA attributes**, when meaningful and authored.
8. **Data attributes**, when product-authored and describing the element rather
   than its state.
9. **Other attributes**, including URL attributes (`href`, `src`, `action`,
   `cite`, `download`, `poster`) with shortened stable matching when long.
10. **Short tag/XPath under a stable parent**.
11. **Semantic class**, only when unique and no better signal exists.
12. **Indexed selectors and absolute XPath** — last resort only.

Two candidates at the same tier are separated by path length: fewer segments
wins. A class-based or indexed selector is demoted regardless of which signal
produced it, so a test attribute that still needs an index ranks below a plain
text selector that does not.

Read more about strategies in `references/strategies.md`.

### Hard Avoid Rules

- **Framework / no-code / internal attributes:** React, Angular, Vue, Gatsby,
  Wix, Bubble, Webflow, Elementor, Shopify, Material UI, Radix, Mantine
  internals; React Aria (`data-react-aria-`); Guideflow (`data-guideflow-`);
  BugBug internals (`data-bugbug-`, `data-bb-input-id`); password-manager
  attributes (`data-form-type`, `data-1p-ignore`, `data-bwignore`,
  `data-lpignore`); browser-extension attributes.
- **Generated IDs:** anything containing known generated markers — `ember`,
  `select2`, `react-aria`, Mantine/Radix id prefixes, or React `useId` patterns.
- **UUID / hash / numeric-looking dynamic values**, unless covered by an accepted
  URL/title/alt exception.
- **Boolean ARIA values** like `aria-*="true"` / `aria-*="false"`.
- **Object-looking values** like `{...}`.
- **Non-URL attribute values longer than 250 characters.**
- **Non-semantic / generated classes**, unless non-semantic classes are
  explicitly enabled for the project.
- **Deep `nth-child` / `nth-of-type` chains** unless no better signal exists and
  the selector is documented as brittle.
- **Text-only selectors on dynamic content**, counters, prices, timestamps,
  translated copy, or personalized labels.
- Selectors for **`script`** and **`style`** elements.
- **Text selectors** shorter than 2 chars, longer than 250 chars, matching huge
  `innerHTML`, or extracted across an iframe boundary.
- Avoid using `self::`.
- Avoid `or`, `and` if it's not necessary.

### XPath vs CSS

- Always prefer XPath over CSS if possible.
- Use **XPath** for: text matching, parent/ancestor/sibling relationships,
  relative chains, and SVG or name-healed elements.
- Use **CSS** only for simple, stable, direct selectors where it is clearer, e.g.
  `button[data-testid='save']`.
- XPath text should follow this behavior: try direct `normalize-space(text())`
  first, then fall back to `normalize-space(.)` when the direct text match is
  insufficient.
- Do not overcomplicate selectors.

### Good / Bad Examples

Use examples as pattern checks, not as copy-paste rules. The exact selector still
needs verification against the actual page state.

| Case | Bad | Good | Why |
| --- | --- | --- | --- |
| Stable test attribute exists | `//button[normalize-space(.)='Save']` | `//button[@data-testid='save-settings']` | Product-owned test attributes are less likely to change than copy. |
| Generated id | `//*[@id='react-aria-:r5:']` | `//button[@aria-label='Open menu']` | Generated IDs change between renders or sessions. |
| Indexed target | `(//button)[2]` | `//form[@data-testid='billing-form']//button[@data-testid='billing-save']` | A stable parent documents the intended context and avoids position coupling. |
| Dynamic text | `//span[normalize-space(text())='$42.19']` | `//section[@data-testid='cart-summary']//span[@data-testid='cart-total']` | Prices, counters, timestamps, and personalized values are volatile. |
| Assertion text | `//*[contains(., 'Payment successful')]` | `//div[@data-testid='payment-status']` | The selector locates the region; the assertion checks the expected text separately. |
| Deep structure | `/html/body/div[2]/main/div[3]/button` | `//button[@data-testid='submit-order']` | Absolute structure is brittle compared with semantic attributes. |
| Shadow DOM target | `//button[@data-testid='confirm']` | `//payment-widget[@data-testid='payment-widget']` + child group `//button[@data-testid='confirm']` | Target the shadow host first, then resolve the element inside it with a separate group. |
| Stripe / PayPal iframe | `//iframe[@name='__privateStripeFrame122k8912b']` | `//iframe[contains(@name, '__privateStripeFrame')]` or `//iframe[contains(@name, '__zoid__paypal_buttons')]` | Match only the stable provider fragment; omit dynamic suffixes from iframe names. |
| Virtual list row | `(//li[@role='option'])[5]` | `//div[contains(@class,'rc-virtual-list-holder')]` + child group `//li[normalize-space(.)='Item 5']` | Virtual lists recycle DOM nodes, so a bare index resolves to a different row after scrolling. |

## Output

- Authored or recommended `selectorPresets` shape.
- Evidence used to justify selector stability and uniqueness.
- Any unavoidable brittleness and the reason no stronger hook was available.
- Recommended stable test attribute additions when the app lacks reliable hooks.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Read `references/strategies.md` to learn more about selectors generation
  strategies and resolving selectors in known situations.
- Read `references/presets.md` for `selectorsPresets` payload shapes, the YAML
  shorthand and its prefix/whitespace rules, and worked examples of each chain
  pattern.
- Load `bugbug-context-discovering` during Preflight.

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-steps-authoring
description: Creates and updates BugBug test steps. Use when choosing step types, building step payloads, naming steps, setting assertions or visual checks, or materializing element-targeting steps. Run bugbug-context-discovering first.
---

# BugBug Steps Authoring

## Preflight

1. Run `bugbug-context-discovering` before creating or updating steps.
2. Load `bugbug-selectors-authoring` before authoring any step that targets a DOM
   element.
3. Confirm the target test, insertion point, and authorized mutation scope.

## Inputs

- Requested user action or assertion.
- Target test and surrounding steps.
- Available DOM evidence, screenshots, source-code evidence, variables, and
  artifacts needed by the step.

## Safety

- Do not invent test data, credentials, secrets, selectors, or artifact
  references.
- Prefer built-in step types and assertion fields over custom JavaScript.
- Keep step changes within the user's requested flow or authorized repair scope.
- Stop before mutation when required step fields or target placement are
  uncertain.

## Workflow

1. Read `references/step-type-routing.md` to choose the most specific step type.
2. Read `steps/{stepType}.md` after choosing each step type and double-check
   required fields before creating or updating the step.
3. For step types that require `selectorsPresets`, provide selectors backed by
   observed DOM evidence. Load `bugbug-selectors-authoring` first.
4. For `assert` and `ifCondition`, read `references/assertion-routing.md` before
   choosing assertion fields.
5. For visual checks, use `selectorsPresets` for `elementVisualRegression`.
   `pageVisualRegression` does not require selectors. Both accept
   `visualRegressionMaxDiff`.
6. Add `blockId` when the step belongs to a conditional block. Use the owning
   `ifCondition` step id.
7. Read the focused create or update schema for each step type before calling
   BugBug MCP mutation tools.
8. Name steps in product language. Avoid generic names like "Step 1" or "Click
   button". Include notes only when they add useful context.

## Output

- Step types chosen and why they match the requested behavior.
- Created or updated step identities and payload-relevant details.
- Any brittle selectors, missing required fields, external dependencies, or
  verification limits.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Read `references/step-type-routing.md` for choosing the correct step type.
- Read `references/assertion-routing.md` for choosing assertion fields.
- Read generated `steps/` files for full step payload definitions.

Referenced files: 35 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-test-run-debugging
description: Validates and debugs BugBug test runs. Use to inspect an existing or latest test run, classify failures, inspect logs, DOM snapshots, screenshots, focus on a failed step run, or find a supported fix.
---

# BugBug Test Run Debugging

## Preflight

1. Run `bugbug-context-discovering` before inspecting or repairing test runs.
2. If a repair may change DOM-targeted steps, load
   `bugbug-selectors-authoring`.
3. Confirm the project, test run, test, or step run context before diagnosis.

## Inputs

Resolve at least one of:

- `testRunId` (preferred) to inspect a specific run.
- `testId` to inspect the latest run for that test.
- `stepRunId` to focus on a specific step run within the selected run.

## Safety

**The iron law: no repair without run evidence first.** A failed step tells you
*where* the run stopped, not *why*. Until Phases 1 and 2 of the `Workflow` are
complete, do not propose or apply a repair. Rewriting a selector because a step
failed on a selector is a symptom fix.

- Do not debug suite runs with this skill. Use test-level runs only.
- Do not start a new run just because a `testId` was provided. Inspect the latest
  run first.
- Do not mutate a test unless the user explicitly requests the specific repair.
- Treat `stepRunId` as an optional focus, not a required failure identifier.
- Stop after two failed repairs on the same step. Question the step instead.
- Stop when no project, test, run, or step evidence can be confirmed. Ask for the
  missing identifier or selection instead of guessing.

## Workflow

```mermaid
flowchart TD
    A["Phase 1: Gather evidence<br>(run payload, failed step, artifacts)"] --> B{"Reproducible?"}
    B -->|"passes on re-run"| C(["Classify as flaky<br>report timing/state cause"])
    B -->|"fails consistently"| D["Phase 2: Compare<br>vs. last passing run"]
    B -->|"cannot re-run"| D
    D --> E["Classify failure<br>(see Failure routing)"]
    E --> F["Phase 3: State ONE hypothesis<br>'X is root cause because Y'"]
    F --> G{"Evidence confirms it?"}
    G -->|no| H["Discard, form new hypothesis"]
    H --> F
    G -->|yes| I{"Repair authorized<br>by Safety?"}
    I -->|no| J(["Stop<br>recommend smallest repair"])
    I -->|yes| K["Phase 4: Apply ONE<br>smallest change"]
    K --> L["Re-run and verify"]
    L --> M{"Step passes?"}
    M -->|yes| N(["Report fix & evidence"])
    M -->|"no, attempts < 2"| F
    M -->|"no, attempts >= 2"| O(["Stop<br>question the step, not the selector"])
```

Complete each phase before starting the next.

### Phase 1: Gather evidence

1. Inspect the provided run with `bugbug_get_test_run`. If only `testId` is
   available, find its latest run with `bugbug_list_test_runs` first.
2. Treat the returned run payload as the default evidence source. Follow its
   artifact and screenshot links only when more evidence is needed. Never
   construct run resource URIs manually.
3. Read the error code and message on the failed step before forming any opinion.
   The code (`ELEMENT_DOES_NOT_EXIST`, `FAILED_WAITING_CONDITIONS`, and similar)
   already narrows the routing.
4. Focus on the failed step with `bugbug_get_failed_step_run_details`.
5. Establish reproducibility. Check earlier runs of the same test: does this step
   fail every time, or intermittently? An intermittently failing step is a timing
   or state problem, and repairing its selector will not fix it.

### Phase 2: Compare against a passing run

1. Find the most recent passing run of the same test with
   `bugbug_list_test_runs` (filter by `status=passed`).
2. Compare the failed step against its last passing execution: selector used,
   waiting conditions, resolved variables, and page state.
3. List every difference before deciding which one matters. Do not assume a
   difference is irrelevant because it looks cosmetic.
4. Check what changed around the run: app deployment, test edits, profile or
   variable changes, environment.
5. Classify the failure using **Failure routing** below.

### Phase 3: Form one hypothesis

1. State it explicitly: "I think X is the root cause because Y." Name the
   evidence Y refers to.
2. Verify the hypothesis against the DOM snapshot, screenshots, or run logs
   before touching the test. `bugbug_query_dom_snapshot_element` confirms whether
   a selector resolves in the captured DOM.
3. If the evidence contradicts the hypothesis, discard it and form a new one. Do
   not stack a second theory on top of the first.
4. If you cannot form an evidence-backed hypothesis, say so and report what
   additional evidence is needed. Do not guess.

### Phase 4: Repair and verify

Only enter this phase when the user has explicitly authorized the specific
repair. Otherwise stop and recommend it.

1. Apply the single smallest change that addresses the confirmed root cause. No
   bundled cleanups, no "while I'm here" edits to neighbouring steps.
2. Validate with a new run and confirm the previously failing step now passes.
3. Confirm no later step broke as a result.
4. If the step still fails, count your attempts:
   - **Fewer than 2 repairs tried**: return to Phase 3 with the new run's
     evidence and form a different hypothesis.
   - **2 or more repairs tried**: stop. Do not attempt another repair.

### After 2 failed repairs: question the step

Repeated failed repairs on the same step usually mean the step itself is wrong,
not its selector. Stop and ask:

- Is this the right step type for the interaction?
- Is a `switchContext` step missing for an iframe, or shadow-host selectors
  missing from the preset?
- Is a required waiting condition missing, or is an active one meaningless for
  this UI state?
- Did an earlier step fail to reach the expected application state, making this
  step unreachable as written?
- Is the test design itself the problem — missing setup, wrong profile, or a flow
  that no longer exists in the product?

Report this to the user as a design question. Do not attempt repair #3.

### Failure routing

- **Selector problem**: Confirm the active selector is broken, compare it with
  the last passing run, and use screenshot plus DOM evidence for replacements.
- **Visual regression**: Compare expected, observed, and diff screenshots; decide
  whether to report a regression or update the baseline.
- **Assertion problem**: Explain expected versus observed behavior and where the
  fix belongs.
- **Waiting conditions problem**: Inspect failed and skipped waiting-condition
  results, then locate the fix in test state, app state, data, environment, or
  waiting-condition configuration.
- **Test data or variables problem**: Identify missing or invalid variables,
  credentials, tenant data, or preconditions. Check whether the variable was
  unresolved, empty, or wrong before repairing the step that visibly failed. Do
  not invent secrets.
- **App or product problem**: Cite the run evidence and report the product
  behavior that changed.
- **Environment problem**: Cite network, console, timeout, region, profile, or
  infrastructure clues.

### Red flags

If you catch yourself thinking any of these, return to Phase 1.

| Thought | Reality |
|---------|---------|
| "The step failed on a selector, so rewrite the selector" | The error code names the symptom. A resolving selector on a wrong page is still a failure. |
| "Just bump the timeout and re-run" | Timeout increases are valid only when evidence shows the condition eventually resolves. |
| "Let me fix these three steps at once" | You cannot tell which change worked, and you may mask a second cause. |
| "It failed once, that's enough to diagnose" | Check reproducibility first. Intermittent failures are timing or state, not selectors. |
| "I'll re-run it and see what happens" | Re-running without a hypothesis is guessing with extra steps. |
| "One more repair attempt" (after 2) | 2+ failures means the step or test design is wrong. Question it instead. |
| "The user will want this other cleanup too" | Repairs are authorized individually. Recommend, don't apply. |

## Output

- Selected test run and failed-step context.
- Triage confidence
- Summary
- Evidence-backed failure classification.
- The hypothesis you confirmed, and the evidence confirming it.
- Affected files, if tested app codebase available
- Smallest proposed solution or next diagnostic action.
- Verification actions
- Explicit blockers, uncertainty, and any repair requiring user confirmation.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Load `bugbug-context-discovering` during Preflight.
- Read `references/selectors-troubleshooting.md` for selector failure diagnosis
  and repair.
- Read `references/assertion-troubleshooting.md` for assertion failure diagnosis
  and repair.
- Read `references/visual-regression-review.md` for screenshot comparison and baseline decisions.
- Read `references/waiting-conditions-results-check.md` for
  `FAILED_WAITING_CONDITIONS` diagnosis and repair decisions.
- Read `references/variables-troubleshooting.md` for unresolved, empty, or wrong
  variable diagnosis, including profile scope and secret placeholders.
- Load `bugbug-selectors-authoring` before changing DOM-targeted steps.

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-tests-authoring
description: Creates and maintains BugBug tests with AI agents from an approved plan. Use for creating tests, editing steps, organizing reusable assets, optimizing reuse, or producing BugBug automation changes through CLI, SDK, or MCP surfaces. Defers to bugbug-tests-planning when tests still need to be designed or scoped.
---

# BugBug Tests Authoring

## Preflight

1. Load `bugbug-tests-planning` before designing tests or reusable assets.
2. Run `bugbug-context-discovering` before creating, editing, running, or
   importing BugBug tests.
3. Load `bugbug-steps-authoring` before materializing steps.
4. Load `bugbug-selectors-authoring` before creating or changing DOM-targeted
   steps.

## Inputs

An approved plan supplies these. Sources are the request itself, existing BugBug
assets, product flow descriptions, and discovered evidence.

- User intent and requested authoring scope.
- Project context and target suite.
- Test name, purpose, owner boundary, and run profile.
- Start URL or target page.
- Existing components, variables, suites, and profiles to reuse.
- Target test and component folders, if the plan places assets in folders.
- New assets to create, if any.
- Step-level flow: setup, user actions, and expected assertions.
- Required credentials or test data source. Never invent secrets.

If any of these is missing and cannot be inferred from existing BugBug assets,
stop and ask for it before creating or mutating tests.

## Safety

- Keep platform mutations within the user's requested authoring scope.
- Do not invent product intent, test data, credentials, secrets, selectors, or
  reusable asset references.
- When repairing a failed authored test, change only behavior covered by the
  original authoring request.
- Stop before creating, editing, running, or importing anything when the target
  project cannot be confirmed.

## Workflow

1. Start from an approved plan. If planning is still needed, load
   `bugbug-tests-planning` and finish the plan before mutating BugBug resources.
2. Create the test shell, groups, steps, and assertions from the approved plan
   by following `The Process`.
3. Run the test with `bugbug_run_test`. Watch it with
   `bugbug_watch_run_progress`, then read details with `bugbug_get_test_run`.
4. If the test fails, load `bugbug-test-run-debugging`, inspect the run, and make
   only repairs allowed by `Safety`.
5. Re-run until the intended flow passes, repair scope is exhausted, or evidence
   proves an external blocker.

### The Process

Use this flow only after planning and project discovery are done. You receive a
prepared test plan and materialize it into BugBug assets. Each step carries the
judgment behind it; *Process Flow* below owns the branching.

1. **Validate the provided plan against existing BugBug assets.** The plan is an
   input, not a draft — authoring materializes it rather than rediscovering the
   product or redesigning the suite architecture. Reopening design decisions here
   silently produces tests nobody scoped.
   - Resolve existing suites, profiles, variables, and reusable components with
     their list/get tools.
   - Confirm every ID before mutation. The current MCP surface can read profiles
     but cannot create them; stop when the required profile does not exist.
   - Do not run broad discovery here. If the plan cannot be executed, report the
     missing planning input and stop instead of improvising the gap.
   - Resolve the planned folder paths to ids with `bugbug_list_folders`.

2. **Place assets in folders when the plan says so.** Folders are the project's
   own organization; an agent that invents its own layout scatters tests where
   nobody looks for them.
   - Reuse an existing folder that matches the project's convention before
     creating a new one. Folder names are unique among siblings, ignoring case.
   - Create a folder only when the plan calls for it. Build nested folders one
     at a time: create the parent, then pass its id as `parentId`.
   - A test goes only into a `test` folder and a component only into a
     `component` folder. Plain groups are never placed in folders.
   - Folders need a paid plan. On a plan error, tell the user and keep the
     assets at the root; do not retry.
   - MCP tools: `bugbug_list_folders`, `bugbug_create_folder`

3. **Create required variables** Never invent
   what only the user knows: credentials, secrets, and test data come from the
   request or existing assets. An invented secret produces a test that fails for
   a misleading reason.
   - Use variables for base URLs, tenant data, and repeated form values.
   - For secrets, accept the tool's temporary value and tell the user to replace
     it through the returned BugBug URL. Never invent a secret.
   - Use camelCase for variable name.
   - MCP tools: `bugbug_get_variables_list`, `bugbug_create_new_variable`

4. **Create the test shell**
   - Set its name, notes, and screen-size type, plus `folderId` when the plan
     places the test in a folder. This tool does not assign a suite or run
     profile.
   - Keep the test focused on one user flow.
   - Do not create placeholder tests with vague names or TODO steps. Empty shells
     are fine only as a short-lived step before adding the planned content.
   - MCP tool: `bugbug_create_tests` (batch related test shells in one call)

5. **Create groups or components under the new test**
   - Use `isComponent: true` only for a genuinely reusable flow, with
     `folderId` when the plan places the component in a folder.
   - Keep each group or component focused on one responsibility.
   - Reuse an existing component instead of recreating it.
   - MCP tools: `bugbug_insert_component_into_test`, `bugbug_create_groups`

6. **Add setup steps**
   - Prefer reused auth/session components over logging in through the UI in every
     test.
   - Use direct `goto` navigation when intermediate navigation is not under test.
   - Prepare data through API/setup components when available instead of clicking
     through unrelated UI to manufacture state.
   - For flows blocked on a received email — registration, email verification,
     password reset, magic-link login, invitations — read
     `references/email-flows.md` and use the per-run BugBug Inbox mailbox. Never
     hardcode a mailbox address; a fixed address collides with itself on the
     second run.
   - MCP tool: `bugbug_create_steps`

7. **Add action steps** Waits target observable
   state: fixed sleeps trade correctness for the appearance of stability — they
   slow the suite and still flake under load.
   - Load `bugbug-steps-authoring` for step type choice and required fields.
   - Use specific step types (`click`, `type`, `select`, `goto`, `uploadFile`,
     etc.) before reaching for `execute`.
   - Use `execute` only for interactions that genuinely cannot be represented by
     normal BugBug steps.
   - Use `Javascript assertion` only for assertions that genuinely cannot be
     represented by regular BugBug assertions.
   - Do not add fixed sleeps. Wait for observable product state with waiting
     conditions and assertions.
   - MCP tool: `bugbug_create_steps`

8. **Add assertions that prove the flow worked.**
   Assertions are the proof, not the actions — a run of green action steps only
   shows commands executed, not that the product did the right thing.
   - Assert the product state after important state changes and at the final
     outcome.
   - Prefer element-specific assertions over page-level checks.
   - Check visible text, URL, field value, enabled/disabled state, created data,
     or another user-observable result.
   - Do not rely on action steps alone as proof that the flow works.
   - MCP tool: `bugbug_create_steps`

9. **Wire variables and components deliberately.**
   - Use variables instead of hardcoded URLs, credentials, tenant names, and
     repeated form values.
   - Use components for repeated setup, navigation, and flows.
   - Keep destructive actions explicit in names and notes so nobody runs them by
     accident.

10. **Attach the test to its suite.**
    - Create suite when the suite does not exist.
    - MCP tool: `bugbug_create_suite`

11. **Review the created test before running it.**
    - The test is independent and does not depend on another test's run order.
    - The setup is minimal: reused auth and targeted data prep.
    - The flow has no artificial waits.
    - The selectors are stable enough to survive normal UI changes.
    - The assertions prove the intended behavior, not just that commands executed.
    - The test is still one focused flow, not a broad demo script.

12. **Run the created test.** Creation is not complete until the new test has
    been executed at least once to confirm it works.
    - Report the latest run result with the created test assets.
    - Do not mark the test ready without either a passing run or a documented
      external blocker that prevented verification.
    - MCP tool: `bugbug_run_test`, `bugbug_run_suite`

13. **Repair within the original scope.** When an authored test fails, change
    only behavior covered by the original authoring request. Widening scope
    during a repair turns a debugging pass into unreviewed design work, so
    report a genuine external blocker rather than engineering around it.

### Process Flow

The graph owns control flow — branching, stop conditions, and where the run
ends. It intentionally does not restate step substance or rationale; both live
in *The Process* above.

```mermaid
flowchart TD
    A{"Approved plan?"} -->|no| B["Load bugbug-tests-planning<br>(finish plan first)"]
    B --> A
    A -->|yes| C["Validate plan against existing assets<br>(resolve & confirm IDs)"]
    C --> D{"Plan executable?"}
    D -->|missing profile or input| E(["Stop<br>report missing planning input"])
    D -->|yes| D2{"Planned folders exist?"}
    D2 -->|no| D3["Create planned folders<br>(parent first)"]
    D2 -->|yes| F["Create variables"]
    D3 --> F
    F --> G["Create test shell"]
    G --> H{"Reusable component exists?"}
    H -->|yes| I["Insert existing component"]
    H -->|no| J["Create groups/components"]
    I --> K["Add setup steps"]
    J --> K
    K --> L["Add action steps"]
    L --> M["Add assertions"]
    M --> N{"Suite exists?"}
    N -->|no| O["Create suite"]
    N -->|yes| P["Read full suite, then update<br>(preserve runProfileId & tests)"]
    O --> Q["Review before running"]
    P --> Q
    Q --> R["Run created test<br>(watch, then read run details)"]
    R --> S{"Passed?"}
    S -->|yes| T(["Report created assets & result"])
    S -->|no| U{"Repair allowed by Safety<br>and scope remaining?"}
    U -->|yes| V["Load bugbug-test-run-debugging<br>and repair"]
    V --> R
    U -->|no| W(["Stop<br>report blocker or exhausted scope"])
```

The run has three terminal states: a passing test, an unexecutable plan, and an
exhausted or externally blocked repair loop. Only the repair loop cycles within
a single run; a new authoring request re-enters at the top.

### Capability routing

Which surface to reach for while authoring:

- **Live platform action or filtered query**: Use a BugBug MCP tool.
- **Known-ID reads**: Follow MCP hub resource links; never construct dynamic
  resource URIs.
- **Custom public API automation**: Use `@bugbug-io/sdk`.
- **Unclear endpoint or payload shape**: Use
  https://app.bugbug.io/docs/schema/.

For explicit YAML import/export, generation, validation, repair, or local
`bugbug.yaml` workflows, hand off to `bugbug-yaml-authoring`.

## Output

- Created or reused suite, profile, component, folder, and variable IDs.
- Folder path of each created test and component, or root.
- Created test ID and test name.
- Step groups added: setup, actions, assertions.
- Implemented steps and assertions, including any brittle selectors, missing data
  dependencies, or manual follow-up.
- Latest run result and repairs performed within the authorized scope.
- Readiness to run, or the external blocker preventing verification.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Load `bugbug-context-discovering` during Preflight.
- Load `bugbug-tests-planning` before designing tests or reusable assets.
- Load `bugbug-steps-authoring` for step payloads and names.
- Load `bugbug-selectors-authoring` before DOM-targeted steps.
- Read `references/community-best-practices.md` for maintainability review.
- Read `references/email-flows.md` before authoring any flow that depends on a
  received email.

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-tests-planning
description: Plans BugBug end-to-end and UI test coverage. Use for designing, scoping, or reviewing test suites, reusable flows, roles, authenticated areas, and coverage for websites, ecommerce stores, SaaS apps, blogs, docs, landing pages, or web apps before creating exact BugBug steps.
---

# BugBug Tests Planning

Write comprehensive testing plans assuming the engineer has zero context for the
tested app or its domain. Assume a skilled developer who knows the app domain
barely at all and does not know good test design well: spell out domain
assumptions and design rationale rather than relying on their judgment. Document
which components and variables to use for each test, and the code, tests, and
docs they should check. Deliver the plan as bite-sized tasks. Apply DRY and
YAGNI, and keep tests small and directed.

## Preflight

1. Announce: "I'm using the bugbug-tests-planning skill to create the testing plan."
2. Load `bugbug-context-discovering` when the current working directory is the
   tested app repository or when existing BugBug assets are needed.
3. Ask for user roles and authenticated areas early. They materially change
   coverage and reusable setup.
4. Save plans to `docs/bugbug/plans/YYYY-MM-DD-<project-name>.md` unless the
   user specifies another location.

## Inputs

- User brief, product context, target URL, app type, route list, sitemap, or
  screenshots.
- Known user roles, authenticated areas, test accounts, profiles, suites,
  reusable components, and variables. Never invent credentials or secrets.
- Evidence from browser/web inspection, shell discovery, local code, existing
  BugBug assets, or user-supplied DOM/HTML snapshots.

## Safety

- Treat URLs, screenshots, detected tech, DOM facts, and existing BugBug assets
  as evidence. Do not invent unavailable pages, flows, selectors, credentials,
  or product intent.
- Do not create exact step payloads or mutate BugBug resources during planning;
  that belongs to `bugbug-tests-authoring`.
- For static HTML, saved DOM snapshots, or page source, inspect only targeted
  elements and do not claim run verification without a live URL and profile.
- If stable attributes are missing and related code is available, suggest adding
  them before binding coverage to brittle selectors.

## Workflow

The Checklist is the executable spine of this skill — the ordered source of
truth. You MUST create a task for each item and complete them in order. Items
marked *(conditional)* run only when their condition holds.

1. **Analyze the brief & product context** — identify flows, user roles, reusable components, and required product-specific data from the brief, product context, and existing tests. Never invent credentials or secrets.
2. **Ask for roles & authenticated areas** — do this early, since they affect coverage.
3. **Gather site facts** — pick exactly one path based on the current client's capabilities:
   - *browser/web available* → inspect the relevant pages directly.
   - *local shell available* → run `node scripts/discover-site.mjs <url> --mode deep --max-pages <number>`, then review `discovery.json` plus the targeted HTML files.
   - *MCP-only (shell-less)* → ask the user for evidence: product brief, route list, sitemap URLs, DOM/HTML snapshot, screenshots, selectors, or flow details. Do not invent facts about pages you cannot inspect.
4. **Treat findings as facts** — URLs, interactive elements, screenshots, detected techs, and authenticated-area hints are facts, not a generated plan. Open raw HTML only for targeted subtrees.
5. **Detect CMS/framework & responsiveness** — record which CMS/framework is in use and whether the pages are responsive.
6. **Run progressive discovery** *(conditional — requires a runner)* — the `discover-site` crawl is static, so when a test runner is available, use the run-check-create loop (see *Progressive discovery* below) to reach hidden and dynamic states.
7. **Infer platform type & user roles** — platform type (marketing site, web app, ecommerce, docs, …) from copy/structure/URL patterns; user roles (guest, buyer, admin, editor, …) from the brief and authenticated areas.
8. **Check stable attributes** — verify page elements carry stable attributes. *(conditional)* If they don't and the related code is available, suggest adding new stable attributes.
9. **Identify project context & inspect existing suites** — establish the project context and inspect the existing test or suite.
10. **Check for existing reusable components/flows** — if a component or reusable flow already exists, reuse it instead of creating a new one.
11. **Consult the scenario catalog** — read the relevant guidebook from `references` before selecting coverage.
12. **Design candidate suites & tests** — use the discovered facts and the user brief. Keep each test focused on one user flow; define its preconditions and expected result, but leave exact step payloads for the creation phase.
13. **Group flows into suites** — split any giant end-to-end scenario (login → order → payment → cancellation) into separate focused tests, one responsibility each. Design clear ownership boundaries (guest vs. authenticated, role-specific paths); prefer a small first version and add suites only for real product boundaries.
14. **Place the healthcheck test** — always put a focused healthcheck test in a dedicated healthcheck suite.
15. **Propose folders** — give each planned test and component a folder path (for example `Checkout/Guest`). Follow the project's existing folders when it has any; otherwise propose a shallow layout by product area or role, and only when the plan has enough tests to need one.

**Terminal state:** once suites, tests, and reusable components are designed with preconditions and expected results, hand off to `bugbug-tests-authoring`. Do NOT write exact step payloads here — that is the creation phase's job.

**Maintenance re-entry:** after any major product, role, or authenticated-area change, restart from step 1 to refresh evidence before continuing. This happens outside a single planning run, not as part of it.

### Process Flow

The graph owns control flow — branching, and where the run stops. It intentionally does not restate step substance (see the Checklist) or rationale (see *The Process*).

```mermaid
flowchart TD
    A["Analyze brief & product context"] --> B["Ask for roles & authenticated areas"]
    B --> C{"Which client capabilities?"}
    C -->|browser/web| D["Inspect pages via browser/web"]
    C -->|local shell| E["Run discover-site.mjs<br>(static crawl)"]
    C -->|MCP-only| F["Request evidence from user<br>(brief, routes, DOM, screenshots)"]
    D --> G["Treat findings as facts"]
    E --> G
    F --> G
    G --> H{"Runner available?"}
    H -->|yes| I["Progressive discovery loop<br>(reach hidden states)"]
    H -->|no| J["Infer platform type & user roles"]
    I --> J
    J --> K{"Stable attributes present?"}
    K -->|no| L["Suggest adding stable attributes<br>(if code available)"]
    K -->|yes| M{"Reusable component/flow exists?"}
    L --> M
    M -->|yes| N["Reuse existing component/flow"]
    M -->|no| O["Design candidate suites & tests<br>(one flow each)"]
    N --> O
    O --> P["Group flows into suites<br>(split giant E2E scenarios)"]
    P --> Q["Place healthcheck in its own suite"]
    Q --> Q2["Propose folder paths<br>(follow existing folders)"]
    Q2 --> R(["Hand off to creation phase"])
```

The terminal state is handing off to the creation phase; it has no outgoing edges. Refreshing evidence after a product change re-enters the flow at the top in a *new* run — it is not a loop within one run.

### The Process

This section carries the *why* behind the steps — the judgment the checklist can't. It does not repeat the step list.

**Evidence is discovered, not invented.** Everything you gather — URLs, interactive elements, screenshots, detected techs, authenticated-area hints — is a fact to build on, never a substitute for inspection. If you cannot inspect a page, say so and ask for evidence; do not fill the gap with assumptions. Never invent credentials or secrets. Open raw HTML only for the targeted subtree you need, not whole pages.

**Discovery is static by default.** A single crawl or snapshot sees only the surface. Dynamic pages hide states behind interaction (logged-in areas, wizard steps, expanded menus), so a static pass alone under-reports coverage. Use progressive discovery to reach those states when a runner is available.

**Stable selectors are worth fighting for.** If elements lack stable attributes and you can see the code, propose adding them rather than binding tests to brittle CSS/XPath. Brittle selectors are the most common cause of flaky suites, and it is far cheaper to fix them at design time.

**One test, one flow.** A test that spans login → order → payment → cancellation fails for a dozen unrelated reasons and tells you nothing precise. Split it into focused tests with clear ownership boundaries (guest vs. authenticated, per-role paths). Prefer a small first version and add suites only for real product boundaries — not speculative ones (YAGNI).

**Email-dependent flows are in scope.** Registration, email verification, password reset, magic-link login, and invitations are testable, not blockers to plan around: BugBug gives every run its own throwaway mailbox at `{{testRunId}}@bugbug-inbox.com`, readable during the run. Because the address is different each run, signup never collides with an existing account — so plan registration as a repeatable test. Two consequences for the plan: state which flows depend on a received email so the creation phase wires the mailbox. Do not specify mailbox mechanics here — `bugbug-tests-authoring` owns them.

**Folders are for people browsing the project.** Suites decide what runs together; folders decide where someone finds a test. Match the folders the project already has, because a second competing layout is worse than none. For a new project, keep folders shallow (one or two levels, by product area or role) and skip them for a handful of tests. Tests and components live in separate folder trees. Folders need a paid plan, so mark them as optional when the plan is unknown.

**Design, don't implement.** The output of planning is suites, tests, and reusable components with preconditions and expected results. Exact step payloads belong to the creation phase; writing them here couples the plan to details that shift once real DOM work begins.

### Progressive discovery

Uses BugBug infrastructure and test artifacts to reach the next, hidden states of dynamic pages. It is a run-check-create loop and **requires a test runner**.

```mermaid
flowchart TD
    A["Run an existing test<br>(e.g. Login)"] --> B["Inspect returned DOM snapshot"]
    B --> C{"New user flow revealed?"}
    C -->|yes| D["Discover flows & extend the plan"]
    C -->|no| E(["Stop<br>(no new states surface)"])
    D -->|repeat| A
```

## Output

- A saved testing plan with bite-sized implementation tasks.
- Proposed suites, tests, reusable components, variables, roles, preconditions,
  and expected results.
- Proposed folder path for each test and component, or root.
- Evidence used, evidence gaps, assumptions, and any missing user input.
- Clear handoff to `bugbug-tests-authoring` for creating the approved plan.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Search or read targeted sections in
  `references/common-websites-tests-guidebook.md` for common web, blog, landing
  page, or docs flows.
- Search or read targeted sections in `references/ecommerce-tests-guidebook.md`
  for services pages or ecommerce flows.
- Search or read targeted sections in `references/saas-tests-guidebook.md`
  for SaaS signup, onboarding, workspace, collaboration, billing, or
  account-management flows.
- Run `scripts/discover-site.mjs` when shell-based HTML or sitemap sampling
  would improve the plan.
- Load `bugbug-context-discovering` when existing project or tested-app context
  is required.
- Load `bugbug-selectors-authoring` before designing, creating, reviewing,
  repairing, or optimizing a DOM-targeted step.

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-tests-refactoring
description: Analyzes and refactors BugBug tests, groups, components, suites, names, and duplication. Use read-only analysis mode unless the user explicitly requests mutations. Run bugbug-context-discovering first.
---

# BugBug Tests Refactoring

## Preflight

1. Run `bugbug-context-discovering` before analysis or refactoring.
2. Load `bugbug-tests-authoring` before reviewing or changing tests.
3. Load `bugbug-steps-authoring` before reviewing or changing steps.
4. Load `bugbug-selectors-authoring` before reviewing or changing selectors.
5. Confirm explicit mutation authorization before applying refactors.

## Inputs

- Target project, test, suite, or bounded project scope.
- Requested analysis or refactoring outcome.
- Explicit mutation authorization when changes are requested.
- Optional tested-application source context.

## Safety

- Start in read-only analysis mode. Requests to review, analyze, recommend, find
  improvements, or explain what should change do not authorize mutations.
- Mutate BugBug data only when the user explicitly requests execution.
- Never delete a group or suite until replacement behavior has been verified or
  the user explicitly accepts unverified cleanup.
- Stop before mutation when the target IDs, replacement behavior, or acceptance
  of unverified cleanup cannot be confirmed.
- Do not run shell commands, install packages, or write files outside the
  workspace without the user's approval.

## Workflow

1. Read the project through the BugBug MCP list and get tools. Use a local
   project export only when the user asks for it.
2. Analyze naming, duplication, reusable components, selector quality, suite
   organization, and folder organization within the requested scope.
3. Return recommendations when operating in read-only mode.
4. When mutations are authorized, apply them in this order:
   1. Rename for readability.
   2. Extract reusable components.
   3. Reorganize suites.
   4. Reorganize folders.
5. Run affected tests after each mutation batch when a live environment is
   available.
6. If verification fails, diagnose the failure before continuing with further
   refactors.

## Output

- Evidence-backed smells, duplication, and organizational findings.
- Ordered refactoring recommendations with affected tests and assets.
- When execution is authorized, a summary of mutations and verification results.
- Explicit unverified behavior, blockers, or cleanup requiring acceptance.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Load `bugbug-context-discovering` during Preflight.
- Load `bugbug-selectors-authoring` before selector review or selector changes.
- Read `references/project-analysis.md` for the analysis workflow and its smell
  catalog.
- Read `references/extract-component.md` before extracting a reusable component.
- Read `references/readability-rename.md` before bulk readability renames.
- Read `references/suite-organization.md` before restructuring suites.
- Read `references/folder-organization.md` before creating, moving, renaming, or
  deleting folders, or moving tests and components between folders.

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: bugbug-yaml-authoring
description: Creates, edits, reviews, validates, repairs, summarizes, and explains BugBug YAML files. Use for BugBug test, suite, project, component, profile, step action, action_details, schema, semantic, or safety-review YAML work.
---

# BugBug YAML v1

## Preflight

1. Run `bugbug-context-discovering` before YAML work.
2. Require a linked or selected BugBug project only for platform interaction.
3. Treat existing uncommitted changes as user-owned.

## Inputs

- YAML text or file paths and the requested create, edit, review, validate,
  repair, summarize, or explain operation.
- Bundled schema assets and examples for local validation.
- Optional export YAML from `bugbug tests export <testId> --format yaml`.
- Explicit import intent before synchronizing changes to BugBug.

## Safety

- Do not invent unsupported schema types, step actions, fields, IDs, URLs,
  selectors, references, secrets, or missing business data.
- Repair only schema-proven or semantically proven defects. Preserve valid data.
- Preserve exported slugs, variable names, and secret flags unless asked to
  change them. Generate readable kebab-case slugs only for new objects.
- Never fabricate `component_source` or suite `test_source` values.
- Use secret placeholders such as `{{password}}` and set `has_secret_value:
  true` where supported.
- Validate against the bundled schema and semantic rules before returning YAML.
- Treat semantic warnings as review prompts, not automatic proof that a file is
  invalid.
- Require explicit confirmation before `bugbug tests import`.
- Stop when replacement values, validation evidence, or import confirmation are
  missing.

## Workflow

1. Identify the requested YAML operation and root type.
2. For provided YAML text, save it to a temporary file and validate it before
   reasoning from it.
3. For generation, load relevant generation, root-type, structure, action,
   assertion, and variable guidance.
4. For review or repair, load the review checklist first.
5. Validate created or edited files against
   `assets/bugbug-yaml-v1.schema.json`; compare with bundled examples.
6. Apply the semantic checks for `action` and `action_details` relationships.
7. For repairs, change only proven defects and validate again.
8. Return YAML only after validation passes, or report exact unresolved fields.
9. If validation or semantic review still fails, repeat only for proven defects;
   otherwise return the blocker.

### Capability routing

- **Validate or review locally**: Use the bundled schema and examples.
- **Export an existing platform test**: Run
  `bugbug tests export <testId> --format yaml`; use ZIP export when artifacts are
  needed.
- **Import edited YAML**: Run `bugbug tests import <file.yaml>` only as allowed
  by `Safety`.
- **Resolve a schema conflict**: Use the live `sourceUrl` recorded in
  `assets/schema-metadata.json` only when the bundled schema conflicts with a
  current import response.

All platform interaction goes through the `bugbug` CLI; all other work remains
local.

### Root envelope

Every BugBug YAML v1 document contains:

- `schema_version: "1.0"`.
- `schema_type`: `test`, `suite`, `project`, `component`, or `profile`.
- `data`: an object matching the selected `schema_type`.

## Output

- Valid YAML for creation, editing, or repair tasks.
- Structural validation errors and semantic warnings for review tasks.
- Exact unresolved fields when safe repair or generation cannot continue.
- Safe export or import guidance without implicit platform synchronization.

## Resources

Resolve bundled resource paths relative to this skill directory.

- `assets/bugbug-icon.svg` is the OpenAI UI icon for this skill.
- Use `assets/bugbug-yaml-v1.schema.json` for validation.
- Use `assets/schema-metadata.json` for bundled schema metadata and live fallback
  URL.
- Compare generated or repaired files with `examples/valid/` and
  `examples/invalid/`.
- Read `references/format.md` for the envelope and validation model.
- Read `references/root-types.md` for type-specific fields.
- Read `references/project-structure.md` for bundle layout, cross-object
  references, import identity, test groups, and slug semantics.
- Read `references/step-actions.md` for supported actions and selector
  serialization.
- Read `references/assertions.md` for assertion and conditional fields.
- Read `references/variables.md` for interpolation, overrides, and secrets.
- Read `references/semantic-validation.md` for action-detail relationships and
  recursive validation.
- Read `references/generation-rules.md` before generating new YAML.
- Load `bugbug-context-discovering` before using project or repository context.
- Load `bugbug-selectors-authoring` only when choosing a durable element target
  requires selector guidance.

Referenced files: 26 — file references are metadata, not package contents.