@brunosps00/dev-workflow 0.11.0 → 0.13.0

package/scaffold/skills/dw-testing-discipline/references/ai-agent-gates.md

@@ -0,0 +1,170 @@
+# Seven AI agent gates — mandatory when an LLM writes tests
+
+LLMs have characteristic failure modes when authoring tests. These gates are forcing functions for the seven most common.
+
+Every test produced by an agent (via `/dw-run-task`, `/dw-bugfix`, `/dw-autopilot`, or any other code-generating flow) must pass all seven gates BEFORE the diff is presented for review.
+
+## Gate 1: Invariant first
+
+**The failure mode it blocks:** Agent writes 200 lines of test code without articulating what the test is supposed to prove.
+
+**The gate:**
+
+Before writing any test code, the agent prints:
+
+```
+INVARIANT: <one sentence: what behavior is true that the test verifies>
+OWNING_LAYER: <unit | integration | contract | e2e>
+EXISTING_SUITE: <path to existing test file the new test joins>
+```
+
+**Why it works:**
+- "Invariant" forces specific behavior naming.
+- "Owning layer" forces Law 2 (lowest detectable layer).
+- "Existing suite" forces extending coverage rather than spawning new files.
+
+**Verification:** In `/dw-code-review`, look for this 3-line preamble in the PR description or the commit body. Missing = REJECTED.
+
+## Gate 2: Owning layer
+
+**The failure mode it blocks:** Agent creates a new test file every time, scattering coverage across orphan files. Or, agent writes E2E tests for things unit could prove.
+
+**The gate:**
+
+The agent must:
+1. Identify the existing test suite that owns the module under test.
+2. Extend that suite, OR document why a new suite is needed (genuinely new module, new test pyramid layer).
+3. Map the test to the right layer per Law 2.
+
+**Verification:**
+- New test file in PR but existing file covers the same module? REJECTED.
+- E2E test for pure-logic invariant? REJECTED unless documented.
+- Unit test for cross-service flow? REJECTED — push to integration/E2E.
+
+## Gate 3: Real execution
+
+**The failure mode it blocks:** Agent writes tests that mock everything. They pass green forever and validate nothing.
+
+**The gate:**
+
+Every test path the agent writes must, at SOME layer, run against real systems before the diff merges:
+
+- Pure logic: unit only is fine.
+- Code that touches DB: must have at least one integration test running real DB (testcontainers, ephemeral container, dedicated test DB).
+- Code that calls external services: must have a contract test OR a sandbox-account smoke test.
+- UI interactions: must have at least one E2E run on a real preview environment.
+
+**Verification:** PR description must list the real-system runs that exercise the touched code. If no real-system path covers the change, REJECTED.
+
+## Gate 4: Failure → fix production
+
+**The failure mode it blocks:** Agent sees test red, modifies the test until green. Bug ships.
+
+**The gate:**
+
+When the agent encounters a failing test (its own or pre-existing):
+
+1. Print: `INVESTIGATING FAILURE: <test name>`
+2. Read production code in the path that produces the observed value.
+3. Print: `ANALYSIS: <2-3 sentences on whether production is wrong, test is wrong, or invariant changed>`
+4. Decide:
+   - Production wrong → fix production.
+   - Test wrong → fix test AND document the change in the commit body.
+   - Invariant changed → update the test AND open an ADR if the change is a public contract change.
+
+**Verification:** Every commit that changes a previously-green test must have an `ANALYSIS:` line in the commit body explaining the decision. Missing = REJECTED.
+
+## Gate 5: No snapshot without contract
+
+**The failure mode it blocks:** Agent reaches for `toMatchSnapshot()` whenever it doesn't know what to assert. Snapshot becomes the assertion. Drift goes unnoticed.
+
+**The gate:**
+
+Before adding a snapshot assertion, the agent classifies the artifact:
+
+- **PRODUCT_CONTRACT**: a stable contract worth pinning (e.g., serialized output of a public API, schema of a stored record). Snapshot is appropriate. Document the classification.
+- **IMPLEMENTATION_DETAIL**: HTML structure, internal representation, component tree shape. Snapshot is FORBIDDEN. Write specific assertions instead.
+
+**Verification:** Snapshots in the diff without a classification comment = REJECTED. Snapshots classified as IMPLEMENTATION_DETAIL = REJECTED.
+
+## Gate 6: No assertion on self-set mock
+
+**The failure mode it blocks:** Agent writes `mockFn.mockReturnValue('X')`, then asserts `expect(mockFn()).toBe('X')`. Proves nothing.
+
+**The gate:**
+
+The agent cannot assert on values it directly fed into a mock. Assertions must be on:
+- The OUTPUT of production code that consumed the mock.
+- The SIDE EFFECTS (DB state, network calls, event emissions) caused by production code.
+- The VISIBLE behavior (UI change, log line, response) the user/caller observes.
+
+**Verification:** Diff analysis flags pairs where a literal value appears in BOTH a mock setup AND an assertion. Flagged = REJECTED unless the agent can show the value passed through production code.
+
+## Gate 7: Negative companion
+
+**The failure mode it blocks:** Agent writes happy-path-only tests. Edge cases, error paths, boundaries uncovered.
+
+**The gate:**
+
+Every positive assertion the agent writes ships WITH at least one negative companion:
+
+- Asserting `createUser(validInput)` succeeds → also assert `createUser(invalidInput)` fails with a specific error.
+- Asserting `parseDate(validString)` returns a Date → also assert `parseDate(invalidString)` throws/returns null.
+- Asserting `transferFunds(...)` succeeds with sufficient balance → also assert it fails with insufficient balance.
+
+**Verification:** A PR adding N positive assertions must add ≥1 negative assertion per public path. Imbalance >3:1 (positive:negative) on a public path = REJECTED.
+
+## How the gates compose
+
+Together, the seven gates produce tests that:
+1. State what they prove (invariant first).
+2. Live at the right layer (owning layer).
+3. Exercise reality somewhere (real execution).
+4. Reveal bugs when red (failure → fix production).
+5. Assert specifically, not via snapshots (no snapshot w/o contract).
+6. Assert outputs, not setup (no self-mock assertion).
+7. Cover failures, not just success (negative companion).
+
+A test passing all seven is a test worth running. A test missing any one is more likely to mislead than help.
+
+## Override procedure
+
+If an agent (or user) wants to skip a gate, they must:
+1. State which gate is being skipped.
+2. State why (one sentence).
+3. Add a `// SKIP-GATE-N: <reason>` comment in the test.
+4. Open a follow-up issue tracking the gap.
+
+Without all four, the gate is enforced.
+
+## Prompt block to include when invoking the agent
+
+```
+You are about to write tests. Before producing test code, complete the
+seven-gate preamble:
+
+INVARIANT: ___
+OWNING_LAYER: ___
+EXISTING_SUITE: ___
+
+If you cannot complete these three lines, STOP and ask the user for
+the requirement (do not invent an invariant).
+
+Then, while writing tests:
+- Real execution: name the real-system path covering this code.
+- On red: investigate production before changing tests; print ANALYSIS.
+- Snapshots: classify as PRODUCT_CONTRACT or IMPLEMENTATION_DETAIL.
+- Assertions: never assert on values you fed into a mock.
+- Coverage: every positive assertion needs a negative companion.
+
+Tests that violate gates without explicit SKIP-GATE-N comments will be
+REJECTED at review.
+```
+
+`/dw-run-task` and `/dw-bugfix` inject this prompt before generating test code.
+
+## Why these seven and not more
+
+These are the seven LLM failure modes empirically observed in test generation across multiple projects (per pedronauck/skills/testing-boss, MIT, plus dev-workflow internal observation). Other tendencies exist; they're either covered by the positive patterns (e.g., wall-clock waits) or have lower hit-rate.
+
+If a NEW LLM failure mode appears that none of the seven catches, add a gate AND document the failure mode that motivated it. Don't add gates speculatively.

package/scaffold/skills/dw-testing-discipline/references/anti-patterns.md

@@ -0,0 +1,336 @@
+# Anti-patterns — 25 patterns across 5 families
+
+Each anti-pattern names the smell, shows the violation in pseudo-code, gives the fix, and notes how `/dw-code-review` detects it.
+
+---
+
+## Family 1: Brittleness (tests bound to internals)
+
+### A1. Implementation-detail selectors
+
+**Violation:**
+```javascript
+await page.click('.btn.btn-primary.checkout-button');
+```
+
+**Fix:** Use `getByRole('button', { name: 'Checkout' })`.
+
+**Detection:** Grep for `.click(`, `.querySelector(`, `cy.get('.`, `getByTestId(` with a class-flavored argument.
+
+### A2. Testing internal structure vs observable behavior
+
+**Violation:**
+```javascript
+expect(component.state.cart.items.length).toBe(3);
+```
+
+**Fix:** Assert what the user sees: `expect(await page.getByText('3 items in cart')).toBeVisible()`.
+
+**Detection:** Tests that import/inspect internal state, refs, or private fields. Class-based component tests that read `.state` directly.
+
+### A3. Testing private methods directly
+
+**Violation:**
+```javascript
+expect(orderService._calculateTax(...)).toBe(8.5);
+```
+
+**Fix:** Test the public method that uses tax calculation; verify the result. If the private method is independently complex, extract it to a module and test that module's public API.
+
+**Detection:** Identifiers starting with `_` accessed from tests.
+
+### A4. Snapshot-as-test (snapshot replacing assertion)
+
+**Violation:**
+```javascript
+expect(rendered).toMatchSnapshot();  // ← only assertion in test
+```
+
+**Fix:** Either:
+1. Write specific assertions about what the component renders, OR
+2. Use a snapshot AS A SECONDARY check after specific assertions, with a comment classifying the snapshot as `PRODUCT_CONTRACT` (UI contract worth pinning) — never `IMPLEMENTATION_DETAIL`.
+
+**Detection:** Tests where the only assertion is `toMatchSnapshot` or equivalent.
+
+### A5. Vague existence assertions
+
+**Violation:**
+```javascript
+expect(result).toBeTruthy();
+expect(element).toBeDefined();
+expect(button).should('exist');
+```
+
+**Fix:** Assert what you actually want: `expect(result.status).toBe('success')`, `expect(button).toBeEnabled()`, `expect(button).toHaveText('Continue')`.
+
+**Detection:** Tests asserting only existence/truthiness without follow-up semantic check.
+
+### A6. Action without assertion
+
+**Violation:**
+```javascript
+test('clicking save works', async () => {
+  await page.getByRole('button', { name: 'Save' }).click();
+  // ← no assertion. What did "works" mean?
+});
+```
+
+**Fix:** Define what "works" means. Assert the observable outcome: URL changed, modal closed, success message visible, data persisted.
+
+**Detection:** Tests with `await x.click()` or `await x.type()` followed by no `expect(...)`.
+
+---
+
+## Family 2: Flakiness (tests randomizing verdicts)
+
+### A7. Static sleeps / fixed-timeout waits
+
+**Violation:**
+```javascript
+await page.waitForTimeout(2000);
+```
+
+**Fix:** `await expect(page.getByText(/order confirmed/i)).toBeVisible({ timeout: 5000 })` — wait on the actual condition.
+
+**Detection:** Grep for `waitForTimeout`, `cy.wait(<number>)`, `sleep(`, `Thread.sleep`, `time.sleep` in test files.
+
+### A8. Test order dependency / hidden shared state
+
+**Violation:** Test B passes only after Test A has run because A populates a shared cache or DB row.
+
+**Fix:** Each test sets up its own state in `beforeEach`. Verify by running tests with `--shuffle` or `--randomize`.
+
+**Detection:** Tests fail when run with `.only`. Tests fail with `--shuffle`. Setup in `beforeAll` instead of `beforeEach`.
+
+### A9. Non-deterministic inputs (clock, RNG, locale)
+
+**Violation:**
+```javascript
+test('today is Monday', () => {
+  expect(new Date().getDay()).toBe(1);  // fails 6 days a week
+});
+```
+
+**Fix:** Mock the clock (`vi.useFakeTimers()`, `jest.useFakeTimers()`, `freezegun` in Python). Seed RNG. Pin locale.
+
+**Detection:** Tests using `new Date()`, `Date.now()`, `Math.random()`, `Intl.DateTimeFormat` without fakes.
+
+---
+
+## Family 3: Mock misuse (tests testing the test setup)
+
+### A10. Asserting the mock exists
+
+**Violation:**
+```javascript
+expect(mockFn).toBeDefined();
+```
+
+**Fix:** Don't assert on mock setup. If the mock is wrong, the behavior assertion downstream will fail naturally.
+
+**Detection:** Mock functions referenced in assertions without `toHaveBeenCalled` semantics.
+
+### A11. Mock drift
+
+**Violation:** Mocked API response set up 6 months ago still returns `{ status: 'OK' }` while the real API now returns `{ ok: true }`.
+
+**Fix:** Contract testing (Pact, schemathesis) or periodic recording (msw + real-traffic capture). Re-validate mocks against real APIs quarterly.
+
+**Detection:** Tests with mocks that haven't been touched in >90 days against APIs that have changed. Hard to detect in CI; needs explicit contract checks.
+
+### A12. Over-mocking child components
+
+**Violation:**
+```javascript
+vi.mock('./UserAvatar');
+vi.mock('./UserMenu');
+vi.mock('./UserBanner');
+// ... testing nothing real
+```
+
+**Fix:** Mock at boundaries (HTTP, DB, third-party SDKs). Render real children unless they're genuinely expensive or test-irrelevant.
+
+**Detection:** Test files with >3 module mocks of internal modules.
+
+### A13. Incomplete mocks (missing fields the code reads)
+
+**Violation:**
+```javascript
+const mockUser = { id: 1 };  // missing email, but code reads user.email
+```
+
+**Fix:** Use a factory that supplies sensible defaults for ALL fields the type/contract declares.
+
+**Detection:** Runtime errors like `Cannot read property 'X' of undefined` inside production code under test.
+
+### A14. Mocking wrong level (mocking methods the logic depends on)
+
+**Violation:**
+```javascript
+// Testing OrderService, but mocking its private calculate() method
+const service = new OrderService();
+vi.spyOn(service, 'calculate').mockReturnValue(100);
+expect(service.processOrder(...)).toBe(/* uses mocked 100 */);
+```
+
+You've tested the SCAFFOLD, not the logic.
+
+**Fix:** Mock at the EDGE (DB call, HTTP call, time). Let internal logic run.
+
+**Detection:** Spies on methods of the System Under Test itself.
+
+---
+
+## Family 4: Process (team and suite pathologies)
+
+### A15. Coverage as vanity metric
+
+**Violation:** PR comments demanding "you need to hit 90% coverage" with no discussion of what the coverage means.
+
+**Fix:** Coverage is a flashlight. Use it to FIND blind spots. Don't optimize for the number.
+
+**Detection:** Cultural; visible in PR templates that gate on coverage percentage.
+
+### A16. Happy-path-only coverage
+
+**Violation:** Every test exercises the success case. Edge cases, error paths, boundary values uncovered.
+
+**Fix:** For each unit, write at minimum: happy path + 1 boundary + 1 invalid input + 1 failure path.
+
+**Detection:** Tests where every assertion is positive (`toBe`, `toEqual`) and none is negative (`toThrow`, `toReject`).
+
+### A17. Eternal `beforeAll` / shared setup hiding dependencies
+
+**Violation:**
+```javascript
+beforeAll(async () => {
+  await db.users.create([100 users]);
+  await db.orders.create([500 orders]);
+});
+```
+
+Tests now SHARE state. Order matters. Cleanup is fragile.
+
+**Fix:** `beforeEach` with minimal setup specific to each test.
+
+**Detection:** `beforeAll` blocks creating data (vs `beforeAll` blocks doing one-time framework setup like spinning testcontainers).
+
+### A18. Cleanup in `afterEach` (use `beforeEach` instead)
+
+**Violation:**
+```javascript
+afterEach(async () => {
+  await db.users.deleteAll();
+});
+```
+
+If a test fails mid-run, cleanup might not run; next test starts dirty.
+
+**Fix:** `beforeEach` with explicit setup-from-clean (truncate + seed). Reliable regardless of previous test outcome.
+
+**Detection:** `afterEach` blocks doing state reset.
+
+### A19. Magic strings and logic in tests
+
+**Violation:**
+```javascript
+const TIMESTAMP = '2024-01-15T10:30:00Z'; // why?
+expect(formatted).toBe('a long string with embedded specifics');
+```
+
+When the test fails, what was the test's INTENT?
+
+**Fix:** Use factories with named defaults. Extract magic values to constants with documenting names. Use snapshot testing for legitimate snapshot cases (with classification).
+
+**Detection:** Test files with ≥10 string literals not bound to a named variable.
+
+### A20. Testing against third-party sites you don't control
+
+**Violation:**
+```javascript
+test('Google homepage loads', async ({ page }) => {
+  await page.goto('https://google.com');
+  expect(await page.title()).toContain('Google');
+});
+```
+
+You're testing Google's availability, not your code.
+
+**Fix:** Mock the third party. Use a wiremock or msw to fake their responses. If you must call them, do it in a separate "external dependencies up" smoke test, not unit/integration.
+
+**Detection:** External URLs in test code outside designated smoke tests.
+
+### A21. Quarantine-as-cemetery
+
+**Violation:**
+```javascript
+test.skip('flaky on CI sometimes', () => { /* ... */ });
+// commented 8 months ago, no owner, no fix-by date
+```
+
+**Fix:** Every skip/quarantine has a NAMED OWNER and a FIX-BY DATE. Tracking issue exists. PR that introduces the skip says exactly when the test gets fixed.
+
+**Detection:** Skipped tests without comments/labels naming owner and date.
+
+### A22. Retry-as-fix (auto-retry hiding real bugs)
+
+**Violation:**
+```javascript
+// jest.config or playwright.config
+retries: 3,
+```
+
+A flaky test is a SIGNAL. Retrying until green hides it.
+
+**Fix:** When a test is flaky, FIX IT (probably a race condition or non-deterministic input). Quarantine if you can't fix immediately. Never just retry.
+
+**Detection:** CI config with retry counts. Test runners showing "1 retry succeeded" badges.
+
+### A23. Duplicate tests across pyramid layers
+
+**Violation:** Same scenario tested at unit, integration, AND E2E. Triple maintenance, no triple value.
+
+**Fix:** Apply Law 2 — lowest layer wins. Drop higher-layer duplicates.
+
+**Detection:** Search for the same scenario name across `tests/unit`, `tests/integration`, `tests/e2e`.
+
+### A24. Weakening tests to make them pass
+
+**Violation:**
+```diff
+- expect(orders.length).toBe(5);
++ expect(orders.length).toBeGreaterThan(0);
+```
+
+The "fix" makes the test useless.
+
+**Fix:** Read Law 3. Fix production OR document WHY the assertion is weaker.
+
+**Detection:** PR diff shows assertion relaxation without commit body explanation.
+
+### A25. Mock-driven confidence (test asserts on its own setup)
+
+**Violation:**
+```javascript
+const mock = vi.fn().mockReturnValue('hello');
+expect(mock()).toBe('hello');
+```
+
+You wrote `hello` in the mock. You asserted `hello`. You proved nothing.
+
+**Fix:** Assert on the OUTPUT of the production code that consumed the mock — not on the mock itself.
+
+**Detection:** Tests asserting equality between a value the test body created and a value the test body retrieved.
+
+---
+
+## How `/dw-code-review` uses this catalog
+
+For each diff hunk under a test path:
+1. Run regex scans for the patterns flagged "Detection" above.
+2. Each hit becomes a finding with severity from this skill's `dw-review-rigor` integration.
+3. Hits classified as Brittleness/Flakiness/Mock-misuse → severity `high`.
+4. Hits classified as Process → severity `medium`.
+5. Hits where the SAME test has multiple patterns → severity `critical` (suite-health smell, not just one test).
+
+A PR with ≥1 `high` test anti-pattern that lacks ADR justification gets REJECTED.

package/scaffold/skills/dw-testing-discipline/references/flaky-discipline.md

@@ -0,0 +1,163 @@
+# Flaky discipline — taxonomy, quarantine, SLOs
+
+A flaky test is one that produces different verdicts (pass/fail) on the same code across runs. They corrode trust in the suite faster than any other category of test debt.
+
+## The four root causes (in order of frequency)
+
+### Cause 1: Race conditions (concurrency)
+
+**Tells:**
+- Test passes locally, fails in CI (or vice versa).
+- Failure rate correlates with CI machine load.
+- Adding `await page.waitForTimeout(100)` "fixes" it.
+
+**Common scenarios:**
+- Async operation completes after test moves on (missing `await`).
+- Two requests sent simultaneously, response order matters.
+- DOM update happens after assertion runs.
+- Database write not yet committed when read fires.
+
+**Fix:**
+- Replace wall-clock waits with condition-based waits (`waitFor`, `toBeVisible`, `expect.poll`).
+- Add proper `await` on every async operation.
+- Use transaction boundaries explicitly when test reads its own write.
+
+### Cause 2: Test order dependency
+
+**Tells:**
+- Test passes when suite runs in order, fails with `--shuffle`.
+- Test fails when run with `.only` in isolation.
+- Failures cluster on first run after CI restart but not afterwards.
+
+**Common scenarios:**
+- `beforeAll` populates shared state; second test mutates it; third test fails.
+- Test A creates a global mock; Test B inherits it unexpectedly.
+- Database row persists across tests because cleanup is in `afterEach` but a test threw mid-execution.
+
+**Fix:**
+- Move state creation from `beforeAll` to `beforeEach`.
+- Reset shared state in `beforeEach` (clean slate every test).
+- Avoid global mocks; scope mocks to the test that needs them.
+- Run with `--shuffle` in CI to catch new order dependencies.
+
+### Cause 3: Non-deterministic inputs
+
+**Tells:**
+- Test fails at month boundary, year boundary, DST change.
+- Test fails based on hostname, locale, timezone.
+- Test fails when a flaky RNG produces edge values.
+
+**Common scenarios:**
+- `new Date()` in production code, tested without clock fake.
+- `Math.random()` for IDs, tested without seed.
+- `Intl.DateTimeFormat` rendering based on system locale.
+- File paths with timestamps, hash IDs based on time.
+
+**Fix:**
+- Mock the clock (`vi.useFakeTimers`, `freezegun`).
+- Seed RNG explicitly in tests (`Math.random = () => 0.5` or via DI).
+- Pin locale and timezone in CI environment AND in test setup.
+
+### Cause 4: External dependencies
+
+**Tells:**
+- Test fails when a third-party service has an outage.
+- Test fails when CI runs against a real API and hits rate limits.
+- Test fails differently for different geographic CI runners.
+
+**Common scenarios:**
+- Direct call to external API in unit tests.
+- DNS lookup baked into test execution path.
+- CDN-hosted resources in E2E tests.
+
+**Fix:**
+- Mock external services at unit/integration layers.
+- Use contract tests instead of live calls.
+- For E2E, use a sandbox account / dedicated test environment.
+
+## Quarantine workflow
+
+When a test flakes:
+
+### Within 1 hour of detection
+
+1. **Quarantine the test.** Add `.skip` or equivalent. Add a comment:
+
+   ```javascript
+   test.skip('FLAKY-2026-05-12: race condition in checkout flow — owner: bruno, fix-by: 2026-05-19', () => {
+     // ...
+   });
+   ```
+
+2. **File a tracking issue.** Title: `FLAKY: <test name>`. Body includes:
+   - Test name and file
+   - Failure mode observed (race? order-dependency? non-determinism?)
+   - First detection: CI run URL, timestamp
+   - Hypothesis (if any)
+   - Owner and fix-by date
+
+3. **Note in CI.** The next CI run shows "1 quarantined" — make this visible on the dashboard.
+
+### Within 24 hours
+
+1. **Named owner assigned.** Not "team X" — a person.
+2. **Fix-by date set.** Default 5 business days. Major flake (production-path test): 2 days.
+
+### When fix-by passes without fix
+
+Escalate:
+- Pair the owner with someone for a debug session.
+- If still unfixed after 2× the fix-by window, the test is removed (not skipped). A failing un-skipped test is better than a perpetually skipped test.
+
+## SLOs
+
+### `flaky_rate` (first-class metric)
+
+- Definition: `(tests that pass on retry but fail on first run) / (total test runs)`.
+- Target: < 1–2% per week.
+- Alert at: > 5% on any given day.
+
+### `time-to-fix-flaky`
+
+- Definition: hours from quarantine to fix-merged.
+- Target: median < 24 hours; p95 < 7 days.
+
+### `quarantine inventory`
+
+- Definition: count of currently-skipped tests with `FLAKY-*` markers.
+- Target: < 10 at any time.
+- Alert at: > 25 (the quarantine has become a cemetery — emergency cleanup).
+
+## What NOT to do
+
+- **Auto-retry as fix.** `retries: 3` in CI config is hiding flakes, not fixing them. The 4th run that finally passes still validated nothing.
+- **Increase timeouts indefinitely.** A timeout that grows from 5s to 30s "to make CI pass" means the test isn't waiting on the right condition.
+- **Remove the test without investigation.** "It's been flaky forever, delete it" — sometimes correct, but make sure the underlying invariant is captured elsewhere.
+- **Mark skip without owner.** A skip is a debt. An unowned debt is a perpetual liability.
+
+## When a test should be permanently removed
+
+A flaky test should be DELETED (not just skipped) when:
+
+1. The invariant it tests is covered elsewhere (duplicate per A23).
+2. The invariant it tests is no longer a real requirement.
+3. The test was always probabilistic by design and never had value.
+
+Deletion is acceptable; abandonment-by-skip is not.
+
+## Real-systems-at-final-gate principle
+
+Many flakes come from mocks drifting from reality. The defense:
+
+- **Unit:** mock the world; fast feedback; flake budget tiny here.
+- **Integration:** real DB (testcontainers); mock external services with contract validation.
+- **Contract:** Pact / schemathesis verifying producer-consumer agreement.
+- **E2E:** real services in a preview environment; near-zero mocks.
+
+When CI is wired this way, a flake at unit usually = race or order-dependency (fixable). A flake at E2E usually = real environment issue (fix the environment, not the test).
+
+## Integration with dev-workflow
+
+- `/dw-fix-qa` uses this taxonomy when retest cycles produce inconsistent results: classify the flake, apply the right fix, document.
+- `/dw-code-review` flags tests being modified that have a `FLAKY-*` marker — review must verify the flake is now actually fixed, not just made less likely.
+- `/dw-run-qa` weekly summary includes the `flaky_rate` metric.