supipowers 1.2.6 → 1.5.0

package/skills/fix-pr/SKILL.md

@@ -5,95 +5,126 @@ description: Critically assess PR review comments — verify, investigate ripple
 
 # PR Review Comment Assessment
 
-## Core Principle
+Critically assess each PR review comment — verify the concern, investigate ripple effects, then accept with a fix or reject with evidence.
 
-Review comments are suggestions to evaluate, not orders to follow.
-Assess each one critically before acting. The reviewer may lack context you have.
+## Quick Reference
 
-## Assessment Framework
+| Aspect      | Detail |
+|-------------|--------|
+| **Trigger** | Invoked on a PR with review comments to address |
+| **Input**   | PR number/URL, diff, review comments, full repo access |
+| **Output**  | Per-comment decision record, grouped fix plan, reply text per comment |
+| **Scope**   | Only comments on the current PR; do not refactor beyond what comments require |
 
-### For Each Comment, Answer:
+## Assessment Framework
 
-1. **Is this valid?** Read the actual code being commented on. Does the concern apply?
-2. **Is this important?** Bug fix vs style preference vs premature optimization.
-3. **What breaks if we change this?** Trace callers, check tests, find ripple effects.
-4. **Does the reviewer have full context?** They often review diffs, not the full picture.
-5. **Is this YAGNI?** "You should also handle X" — but does X actually occur?
+For each comment, answer:
 
-### Verdict Categories
+1. **Valid?** Read the actual code (not just the diff). Does the concern apply?
+2. **Severity?** Bug > correctness > consistency > style. Style-only comments are low priority.
+3. **What breaks if changed?** Trace callers, check tests, find ripple effects.
+4. **Full context?** Reviewers see diffs, not full files. They may miss structural reasons.
+5. **YAGNI?** "You should also handle X" — does X actually occur in this codebase?
 
-- **ACCEPT**: Valid concern, should fix. Evidence: the code has the problem described.
-- **REJECT**: Invalid, unnecessary, or would cause harm. Evidence: why this doesn't apply.
-- **INVESTIGATE**: Need to check more before deciding. List what to check.
+### Verdicts
 
-### Investigation Protocol
+- **ACCEPT** — Valid concern, will fix. Evidence: the code has the described problem.
+- **REJECT** — Invalid, unnecessary, or harmful to change. Evidence: why it doesn't apply.
+- **INVESTIGATE** — Need more information. List exactly what to check.
 
-When INVESTIGATE:
-1. Read the file(s) mentioned in full (not just the diff)
-2. Search for usages of the symbol/pattern being discussed
-3. Check test coverage for the area
-4. Look at git blame — why is the code written this way?
-5. Then decide ACCEPT or REJECT with evidence
+## Investigation & Ripple Effect
 
-## Ripple Effect Analysis
+When a comment is non-obvious or touches shared code:
 
-Before accepting any change:
-1. **Who calls this?** Search for usages of the function/method/class
-2. **Who depends on this behavior?** Check tests that assert current behavior
-3. **What imports this?** Follow the dependency graph
-4. **Is this a public API?** Changes to public interfaces affect consumers
+1. Read the full file(s) — not just the diff context
+2. Search for usages of the symbol/pattern under discussion
+3. Check test coverage — does a test assert the current behavior?
+4. Follow the dependency graph: who calls this? who imports this? is it a public API?
+5. Check git blame — why is the code written this way?
+6. If ripple effects are significant, include them in the fix plan
 
-If ripple effects are significant, note them in the plan so the fixer handles them.
+Then decide ACCEPT or REJECT with evidence. INVESTIGATE is not a final state.
 
 ## Grouping Strategy
 
-Group comments that:
-- Touch the same file
-- Touch tightly coupled files (caller/callee, type/implementation)
-- Relate to the same logical concern (e.g., "error handling in module X")
+| Group together | Keep separate |
+|---|---|
+| Same file | Unrelated files/areas |
+| Coupled files (caller/callee, type/impl) | Cosmetic vs functional changes |
+| Same logical concern | Independent features |
+
+Address grouped comments in a single commit with a bullet list of changes.
+
+## Output Template
 
-Keep separate:
-- Comments on unrelated files/areas
-- Cosmetic vs functional changes
-- Independent features or concerns
+For each comment, produce:
 
-## Comment Reply Guidelines
+```
+Comment: #ID by @reviewer on file:line
+Verdict: ACCEPT | REJECT
+Reasoning: [1-2 sentences with evidence]
+Ripple effects: [list or "none"]
+Group: [group-id or "standalone"]
+```
 
-### For ACCEPT:
-- "Fixed. [description of change]."
-- "Fixed in [file]. Also updated [related file] to maintain consistency."
+### Reply Format
 
-### For REJECT:
-- "Investigated — [reason this doesn't apply]. The current implementation [explanation]."
-- "This is intentional: [reason]. Changing it would [consequence]."
+**ACCEPT:** "Fixed. [description of change]." or "Fixed in [file]. Also updated [related file] for consistency."
 
-### For grouped fixes:
-- "Addressed these comments together in [commit]. Changes: [bullet list]."
+**REJECT:** "Investigated — [reason this doesn't apply]. The current implementation [explanation]." or "This is intentional: [reason]. Changing it would [consequence]."
 
-**Never use performative agreement.** No "Great catch!", "You're absolutely right!", etc.
-Technical acknowledgment only.
+**Grouped:** "Addressed these comments together in [commit]. Changes: [bullet list]."
 
-## Common Reviewer Mistakes to Watch For
+## Worked Example
 
-| Pattern | Reality |
-|---------|---------|
-| Suggesting abstraction for code used once | YAGNI — one usage doesn't need a helper |
-| Requesting error handling for impossible states | Trust internal code; only validate at boundaries |
-| Style preferences disguised as correctness | If it works and is readable, style is preference |
-| Suggesting patterns from a different language | Follow THIS codebase's patterns |
-| Not seeing the full file (diff-only context) | They may miss why code is structured this way |
-| "This could be a security issue" without specifics | Ask for the specific attack vector |
-| "Add tests for X" when X is already tested | Check before accepting |
+> **Review comment** by @alice on `src/config.ts:42`:
+> "This should validate the input before passing it to `loadConfig`. What if `path` is undefined?"
 
-## Decision Record
+**Investigation:**
+1. Read `src/config.ts` — `loadConfig` is only called from `cli/init.ts` which already validates all args via Zod schema.
+2. `grep` for other callers — none. Single call site.
+3. `path` is typed `string` (non-optional) in the function signature; TypeScript enforces this at compile time.
 
-For each comment, record:
+**Decision:**
 ```
-Comment #ID by @user on file:line
-Verdict: ACCEPT | REJECT | INVESTIGATE
-Reasoning: [1-2 sentences]
-Ripple effects: [list or "none"]
-Group: [group-id]
+Comment: #12 by @alice on src/config.ts:42
+Verdict: REJECT
+Reasoning: `path` is typed as required `string` and the sole caller validates via Zod before invocation. Adding a runtime check duplicates the type system and the caller's validation.
+Ripple effects: none
+Group: standalone
 ```
 
-This record serves as the basis for reply content and fix planning.
+**Reply:** "Investigated — `path` is a required `string` param and the only caller (`cli/init.ts:18`) validates all args through a Zod schema before this point. Adding a runtime check would duplicate both the type constraint and the caller's validation."
+
+## Common Reviewer Mistakes
+
+| Pattern | Response |
+|---------|----------|
+| Abstraction for code used once | YAGNI — one usage doesn't need a helper |
+| Error handling for impossible states | Only validate at system boundaries |
+| Style preference framed as correctness | If it works and is readable, style is preference |
+| Patterns from a different language/codebase | Follow THIS codebase's conventions |
+| "Security issue" without a specific vector | Ask for the specific attack scenario |
+| "Add tests for X" when X is already tested | Verify coverage before accepting |
+| Diff-only context (missing full file) | They may miss structural reasons for the code |
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| Read full file before deciding on a comment | Accept comments without verifying the concern |
+| Provide evidence for every ACCEPT and REJECT | Use performative agreement ("Great catch!", "You're right!") |
+| Check ripple effects before accepting changes | Fix cosmetic comments before functional ones |
+| Search for existing patterns before introducing new ones | Assume the reviewer has full context |
+| Resolve every INVESTIGATE to ACCEPT or REJECT | Leave comments unaddressed |
+
+## Final Checklist
+
+Before submitting:
+
+- [ ] Every comment has a verdict (ACCEPT or REJECT) with evidence
+- [ ] No INVESTIGATE verdicts remain unresolved
+- [ ] Ripple effects checked for every ACCEPT
+- [ ] Related comments grouped; each group addressed in one commit
+- [ ] Reply text is technical — no performative agreement
+- [ ] Fix plan covers all ACCEPT verdicts, including ripple effects

package/skills/planning/SKILL.md

@@ -5,15 +5,24 @@ description: Guides collaborative brainstorming, design, and planning — from i
 
 # Planning Skill
 
-Guide the user through a complete planning flow: brainstorm → design → spec → review → plan. This skill is loaded by `/supi:plan`.
+Guide the user through a complete planning flow: brainstorm → design → spec → review → plan. Loaded by `/supi:plan`.
 
-<HARD-GATE>
-Do NOT write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
-</HARD-GATE>
+You **MUST NOT** write code or scaffold until the user approves the design.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| Scope | Single feature or decomposed sub-project |
+| Input | User's initial request + repo state (files, docs, commits) |
+| Output | Design doc at `.omp/supipowers/specs/YYYY-MM-DD-<topic>-design.md`, implementation plan |
+| Phases | Explore → Clarify → Brainstorm → Design & Save → Review Loop → User Gate → Plan |
+| Task size | 2–5 minutes each, checkbox syntax |
+| Specs | Local only — never commit to git |
 
 ## Process
 
-Follow these phases in order. Do not skip or combine them.
+Follow phases in order. Do not skip or combine them.
 
 ### Phase 1: Explore Project Context
 
@@ -21,67 +30,102 @@ Before asking questions, understand the current state:
 
 - Check files, docs, recent commits
 - Understand existing architecture and patterns
-- If the request covers multiple independent subsystems, flag it immediately and help decompose into sub-projects
+- If the request covers multiple independent subsystems, flag it and help decompose into sub-projects
 
 ### Phase 2: Ask Clarifying Questions
 
-- One question at a time — never overwhelm with multiple questions
-- Prefer multiple choice when possible, open-ended is fine too
-- Focus on: purpose, constraints, success criteria
-- Continue until you have enough clarity to propose approaches
+Determine the planning mode: problem exploration, solution ideation, assumption testing, or strategy exploration.
+
+- One question at a time — never batch multiple questions
+- Prefer multiple choice when possible; open-ended is fine too
+- Focus on: purpose, constraints, success criteria, non-goals
+- If missing evidence blocks brainstorming, name the research gap explicitly
+- Continue until purpose, constraints, success criteria, and non-goals are each addressed
+
+**Example — good vs. bad clarifying question:**
 
-### Phase 3: Propose 2-3 Approaches
+```
+BAD (open-ended, unbounded):
+"What kind of authentication do you want?"
+
+GOOD (multiple choice, scoped):
+"For auth, which fits best?
+ a) Session-based (server-rendered, simple)
+ b) JWT (stateless, API-first)
+ c) OAuth provider only (GitHub/Google, no local accounts)
+ d) Something else — describe briefly"
+```
 
-- Present 2-3 different approaches with trade-offs
+### Phase 3: Brainstorm, Then Propose 2–3 Approaches
+
+- Internally generate 5–7 directions before converging
+- Pressure-test with: one opposite option, one simplification/removal, one cross-domain analogy
+- Name traps when they appear: solutioning too early, one-idea brainstorm, analysis paralysis
+- Present only the strongest 2–3 approaches with trade-offs
 - Lead with your recommended option and explain why
+- For the leading option, capture the biggest unknown and the cheapest validation step
 - Wait for the user to choose before proceeding
 
-### Phase 4: Present Design
+**Example — brainstorm output format:**
+
+```
+### Approaches
+
+**A) Event-sourced (recommended)**
+- How: Append-only event log, projections for read models
+- Pro: Full audit trail, temporal queries
+- Con: Higher upfront complexity, eventual consistency
+- Biggest unknown: Event schema evolution strategy
+- Cheapest validation: Spike a single aggregate with 3 events
+
+**B) Traditional CRUD + audit table
+- How: Mutable rows, trigger-based audit log
+- Pro: Familiar, immediate consistency
+- Con: Audit coverage depends on discipline, no temporal queries
+
+**C) Hybrid — CRUD with event log for critical paths
+- How: Standard CRUD; event-source only billing and permissions
+- Pro: Complexity only where value is highest
+- Con: Two persistence patterns to maintain
+```
+
+### Phase 4: Present Design & Save
 
 Once aligned on approach:
 
-- Scale each section to its complexity (a few sentences if straightforward, up to 200-300 words if nuanced)
-- Cover: architecture, components, data flow, error handling, testing
+- Cover: architecture, components, data flow, error handling, testing strategy
+- Scale sections by integration points: ≤2 integration points → 2–3 sentences; 3+ → up to 300 words
 - Ask after each section whether it looks right so far
-- Apply YAGNI ruthlessly — remove unnecessary features
+- Apply YAGNI — cut features that aren't required now
 - Design for isolation: smaller units with clear boundaries
+- Prefer DRY, TDD
 
-### Phase 5: Write Design Doc
-
-Once the user approves the design:
+Once approved, save to `.omp/supipowers/specs/YYYY-MM-DD-<topic>-design.md`. Keep local — do not commit to git.
 
-- Save to `.omp/supipowers/specs/YYYY-MM-DD-<topic>-design.md`
-- Use clear, concise writing
-- Commit the design document to git
-
-### Phase 6: Spec Review Loop
-
-After writing the design doc:
+### Phase 5: Spec Review Loop
 
 1. Dispatch a spec-document-reviewer sub-agent to verify completeness
 2. If **Issues Found**: fix the issues, re-dispatch the reviewer
-3. Repeat until **Approved** (max 5 iterations, then surface to human)
+3. Repeat until **Approved** (max 5 iterations; after 5, present remaining issues to user and ask whether to proceed or continue fixing)
 
-### Phase 7: User Review Gate
+### Phase 6: User Review Gate
 
-Ask the user to review the spec before proceeding:
+> "Spec written to `<path>`. Please review it and let me know if you want changes before we write the implementation plan."
 
-> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+Wait for approval. Only proceed once approved.
 
-Wait for their response. Only proceed once approved.
+### Phase 7: Create Implementation Plan
 
-### Phase 8: Create Implementation Plan
-
-Break into bite-sized tasks (2-5 minutes each). Each task must have:
+Break into tasks of 2–5 minutes each. Each task must have:
 
 - Name
-- **files**: Exact paths the agent will touch
-- **criteria**: Acceptance criteria (testable)
+- **files**: exact paths the agent will touch (include test files)
+- **criteria**: acceptance criteria (testable)
 - **complexity**: `small` | `medium` | `large`
 
-Include exact code in the plan, not vague descriptions. Use checkbox syntax (`- [ ]`) for tracking steps.
+Steps use checkbox syntax (`- [ ]`). Include function signatures or pseudocode — not vague descriptions, not full implementations.
 
-## Plan Structure
+**Plan template:**
 
 ```
 ---
@@ -98,7 +142,7 @@ tags: [<relevant>, <tags>]
 ## Tasks
 
 ### 1. <Task name>
-- **files**: src/path/to/file.ts
+- **files**: src/path/to/file.ts, src/path/to/file.test.ts
 - **criteria**: <what success looks like>
 - **complexity**: small
 
@@ -106,12 +150,25 @@ tags: [<relevant>, <tags>]
 - [ ] Step 2: Run test to verify it fails
 - [ ] Step 3: Write minimal implementation
 - [ ] Step 4: Run test to verify it passes
-- [ ] Step 5: Commit
 ```
 
-## Principles
-
-- Each task should be completable in 2-5 minutes
-- Include test files in the files list
-- Prefer small, focused tasks over large ones
-- DRY, YAGNI, TDD, frequent commits
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| One question at a time in Phase 2 | Write code before design approval |
+| Present 2–3 approaches with trade-offs | Skip brainstorming for "obvious" solutions |
+| Wait for user approval at each gate | Combine or skip phases |
+| Include test files in task file lists | Include git commit/push steps for specs |
+| Name research gaps instead of guessing | Present every explored branch (show finalists only) |
+
+## Final Checklist
+
+- [ ] All phases followed in order
+- [ ] Purpose, constraints, success criteria, and non-goals addressed in Phase 2
+- [ ] 2–3 approaches presented with trade-offs before design
+- [ ] Design doc saved to `.omp/supipowers/specs/` (not committed)
+- [ ] Spec review loop completed (sub-agent approved or user overrode)
+- [ ] User approved spec before implementation plan
+- [ ] Every task has files, criteria, complexity, and checkbox steps
+- [ ] Task steps reference signatures/pseudocode, not vague descriptions

package/skills/qa-strategy/SKILL.md

@@ -5,15 +5,20 @@ description: E2E QA strategy — flow-based product testing with disciplined tri
 
 # E2E QA Strategy
 
-Test the product the way a user uses it. Every test simulates a real user flow — navigating, clicking, filling forms, waiting for responses. If a human wouldn't do it, don't test it here.
+Test the product the way a user uses it. Every test simulates a real user flow — navigating, clicking, filling forms, waiting for responses.
 
 **This is NOT unit or integration testing.** This pipeline tests complete user journeys through the running application.
 
-## Iron Law
+## Quick Reference
 
-**EVERY FAILURE GETS A VERDICT BEFORE THE NEXT TEST RUNS.**
-
-Don't accumulate failures to analyze later. Triage each failure immediately: real bug, flaky test, or stale assertion? Unclassified failures are useless data.
+| Aspect | Detail |
+|--------|--------|
+| **Scope** | End-to-end Playwright tests against a running app |
+| **Input** | Running app URL, optional prior test results for regression comparison |
+| **Output** | Test files (one flow per file), triage verdicts for every failure, regression report |
+| **Core rule** | Every failure gets a verdict before the next test runs |
+| **Priority** | Critical/High flows first; stop adding flows when context reaches ~80% capacity |
+| **Independence** | Each test is self-contained — no shared state, no execution order dependency |
 
 ## Flow Prioritization
 
@@ -24,7 +29,7 @@ Don't accumulate failures to analyze later. Triage each failure immediately: rea
 | **Medium** | Secondary features | Settings, profile, notifications |
 | **Low** | Polish | Theme toggle, tooltips, animations |
 
-Test critical and high flows first. Skip low flows when hitting the token budget. A session that thoroughly tests 5 critical flows beats one that superficially touches 20.
+A session that thoroughly tests 5 critical flows beats one that superficially touches 20.
 
 ## Flow Discovery
 
@@ -36,7 +41,7 @@ Before writing tests, understand what the product does:
 4. **Find auth boundaries** — public vs protected; test both sides
 5. **Check CRUD operations** — create, read, update, delete for core entities
 
-Compare against the previous matrix (if any) to detect new, removed, and changed flows.
+If prior test results exist, compare to detect new, removed, and changed flows.
 
 ## Playwright Discipline
 
@@ -66,12 +71,10 @@ await expect(page.getByText('Loading...')).not.toBeVisible();
 // BAD — arbitrary delay, flaky by design
 await page.waitForTimeout(3000);
 
-// BAD — unreliable for SPAs
+// BAD — unreliable for SPAs (sockets stay open; resolves before dynamic content loads)
 await page.waitForLoadState('networkidle');
 ```
 
-`waitForTimeout` is never acceptable. `networkidle` is equally unreliable — SPAs keep sockets open, so it either hangs or resolves before dynamic content loads. Wait for the specific element or response that proves the page is ready.
-
 ### One Flow Per File
 
 ```typescript
@@ -83,55 +86,74 @@ test.describe('Checkout flow', () => {
 });
 ```
 
-Each test is independent — no shared state, no execution order dependency.
-
 ## Failure Triage
 
-When a test fails, classify it immediately:
+When a test fails, classify it **immediately** — before running the next test.
 
 | Verdict | Meaning | Action |
 |---------|---------|--------|
-| **Bug** | App behavior is wrong | Record regression. Do not fix the test. |
+| **Bug** | App behavior is wrong | Record as regression. Do not change the test assertion — the test is correct, the app is broken. |
 | **Stale assertion** | App changed intentionally | Update the test to match new behavior. |
-| **Flaky** | Non-deterministic failure | Fix the locator or wait condition. Re-run. |
-| **Test error** | Test code is wrong | Fix and re-run. Does not count as a retry. |
+| **Flaky** | Non-deterministic failure (evidence of randomness required) | Fix the locator or wait condition. Re-run once. |
+| **Test error** | Test code itself is wrong | Fix the test code and re-run. |
 
 ### Triage Process
 
 1. **Read the error.** What element wasn't found? What URL didn't match? What assertion failed?
-2. **Check if the app changed.** Did a route move? Did a button get renamed? Is there a new loading state?
-3. **Distinguish bug from change.** Intentional app change → update test. Unintentional breakage → regression.
-4. **Don't retry blindly.** If you can't explain why a test failed, investigating beats retrying.
+2. **Check if the app changed.** Did a route move? Did a button get renamed? New loading state?
+3. **Distinguish bug from change.** Intentional change → update test. Unintentional breakage → regression.
+4. **Don't retry blindly.** If you can't explain why a test failed, investigate before retrying.
+
+### Example: Classifying a Real Failure
+
+```
+Error: expect(getByRole('heading', { name: 'Dashboard' })).toBeVisible()
+  → Timeout 5000ms exceeded.
+  → Call log: waiting for getByRole('heading', { name: 'Dashboard' })
+```
+
+| Step | Finding |
+|------|---------|
+| Read error | Heading "Dashboard" not found after login |
+| Check app | Route `/dashboard` now redirects to `/home`; heading changed to "Home" |
+| Verdict | **Stale assertion** — intentional redesign |
+| Action | Update test: navigate to `/home`, assert "Home" heading |
 
 ## Regression Analysis
 
 A regression is a flow that **was passing** and now **fails**.
 
+Regressions are the pipeline's highest-priority output.
+
 For each regression, record:
-- Which flow broke
-- What the previous status was
-- What the current error is
-- Whether it's a real bug or an intentional change
-
-**Regressions are the highest-priority output of the pipeline.** A session that finds zero regressions in a stable app is successful. A session that misclassifies a regression as a flaky test has failed.
-
-## Red Flags — STOP and Investigate
-
-- Accumulating failures without triaging each one
-- Retrying a test without understanding why it failed
-- Testing internal state (stores, localStorage, cookies) instead of what the user sees
-- Tests that depend on execution order or shared state
-- Using `waitForTimeout` or `networkidle` instead of explicit conditions
-- Spending the token budget on low-priority flows while critical flows remain untested
-- Classifying a regression as "flaky" without evidence of non-determinism
-- Ignoring error states — test what happens when the API errors, the network is slow, or input is invalid
-
-## Quality Signals
-
-| Good Session | Bad Session |
-|-------------|-------------|
-| Every failure has a verdict | Failures accumulated without triage |
-| Critical flows tested first | Random flow ordering |
-| Regressions clearly identified | "Some tests failed" |
-| Tests are independent and resilient | Tests depend on execution order |
-| Token budget spent on high-value flows | Budget wasted on low-priority flows |
+
+| Field | Value |
+|-------|-------|
+| **Flow** | Which user flow broke |
+| **Previous status** | Last known passing state |
+| **Current error** | Error message and failing assertion |
+| **Classification** | Real bug or intentional change |
+
+## Session Checklist
+
+Before finishing, verify every item:
+
+| Check | Pass | Fail |
+|-------|------|------|
+| Every failure has a verdict | ✓ | Failures left unclassified |
+| Critical flows tested before lower-priority | ✓ | Random or low-priority-first ordering |
+| Regressions recorded with all fields | ✓ | Vague "some tests failed" |
+| Tests are independent and resilient | ✓ | Tests depend on execution order or shared state |
+| Context spent on high-value flows | ✓ | Low-priority flows tested while critical flows skipped |
+| Error states tested (API errors, bad input) | ✓ | Only happy paths covered |
+
+## MUST / MUST NOT
+
+| MUST | MUST NOT |
+|------|----------|
+| Triage every failure before proceeding | Accumulate failures to analyze later |
+| Use resilient locators (role, label, text, testid) | Use CSS selectors or DOM position |
+| Wait for explicit conditions (element, response) | Use `waitForTimeout` or `networkidle` |
+| Test what the user sees | Test internal state (stores, localStorage, cookies) |
+| Provide evidence before classifying a failure as "flaky" | Classify regressions as flaky without proof of non-determinism |
+| Test error states and edge cases | Only test happy paths |