Use when backfilling a missing method or behavior onto an atomic-testing component driver, or adding a brand-new driver — e.g. implementing items from the MUI driver audit issues (#870–#873), "add getLabel/isError/isRequired to the X driver", "the Y driver can't reach Z", "write a driver for <component>". Encodes the end-to-end workflow: find the real DOM, pick an interactor-portable locator (accessibility-first), implement, and verify in BOTH jsdom and all three Playwright browsers. Includes the repo-specific build/test/e2e gotchas that otherwise cost an hour each.
Use when creating atomic-testing drivers for an app's own components — e.g. "write tests for <Component>", "test this page", "I need a driver for the settings panel", "create a page object for checkout", "our wizard has no driver coverage". Encodes the end-to-end workflow: inventory what's already covered by shipped @atomic-testing drivers, decompose the component/page with the six-rule algorithm (so you never emit a god driver), probe the real DOM, pick a portable locator off the escalation ladder, implement with the fixed composite-driver idioms, and verify in every runner the project configures.
Use when writing behavior tests against an existing atomic-testing driver tree — e.g. "write a test that does X", "cover the case where Y", "add a test for the empty state", "test that saving shows a toast". Assumes the scene and drivers already exist (hand-written or from scaffold-test-driver). Encodes translating a plain-language behavior into driver calls plus assertions, the anti-flake toolkit applied by default (waitUntil probes instead of sleeps, tolerance-based geometry, environment gating for what jsdom can't evaluate), and the hard handoff rule when the driver tree is missing a method or part.
Use when an atomic-testing test is red, intermittently red, or suspiciously green — e.g. "this test is flaky", "why is this failing", "it passes locally but not in CI", "it fails when I run the whole suite", "this test passes but the feature is broken". A decision tree that classifies the failure into one of four modes — flaky, brittle, vacuously green, contaminated — each with a matchable symptom, a confirming check, and the library's intended fix. The one banned move: adding a sleep or lengthening a timeout without a diagnosis.
Use when the UI changed and an existing atomic-testing driver/scene must catch up — e.g. "I changed this component, update its driver", "add a method for the new X", "the data-testid got renamed", "this section became a list", "the driver is out of date". Encodes incremental maintenance: re-probe the current DOM and diff it against every locator the driver assumes, re-walk the locator ladder for anything broken (never a one-off patch), apply the six-rule decomposition to new UI surface to decide part-vs-promotion, and update in place without regenerating the tree or breaking hand-written methods.