From 11f8731d32d9f5ce5d62320ef963f2c47c64bb5f Mon Sep 17 00:00:00 2001 From: Test Date: Sun, 8 Mar 2026 20:54:44 +0100 Subject: [PATCH] docs: strengthen Phase 1 QA requirements in CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Require Claude Code to write a new task-specific Playwright test for every task (not just run existing smoke tests) - Test must fail before fix and pass after — proves coverage - Clarify that Phase 1 is Claude Code's quality gate, not Brian's - Brian's Phase 2 is a reinforcement check; if he finds a bug that Phase 1 should have caught, that is a Phase 1 failure Lesson from ai-chat-empty-body: 5 QA cycles happened because Phase 1 never verified that the AI actually received note content end-to-end. --- CLAUDE.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 151a8a03..2b1334e3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,13 +36,19 @@ BASE_URL="http://localhost:" pnpm playwright:smoke kill $DEV_PID ``` -**What to test in Playwright:** -- Every command palette entry from the spec → open `Cmd+K`, type the command name, verify it appears and executes +**You must write a new Playwright test for this task** in `tests/smoke/.spec.ts` that covers every acceptance criterion. Do not rely only on existing smoke tests — they test the app in general, not your specific feature. + +**What to cover in your Playwright test:** +- Every acceptance criterion from the task spec → one `test()` block per criterion +- Every command palette entry → open `Cmd+K`, type the command name, verify it appears and executes - Every keyboard shortcut → send keydown events, verify UI state changes - Every UI element described in the spec → verify it renders, is focusable, responds to Tab - Edge cases: empty state, long text, rapid keypresses +- **The happy path end-to-end**: simulate exactly what a user would do to use this feature -**Playwright is non-negotiable even if tests pass.** Unit tests verify code; Playwright verifies the user experience in the real browser. Both are required. +**The test must fail before your fix and pass after.** If you can't write a test that demonstrates the bug is fixed, your test doesn't cover the right thing. + +**Playwright is non-negotiable even if unit tests pass.** Unit tests verify code; Playwright verifies the user experience in the real browser. Both are required. > **⚠️ Browser dev server limits**: the dev server uses mock Tauri handlers (`src/mock-tauri.ts`) — file system operations, git commands, and native dialogs are mocked. Test those via `pnpm tauri dev` in Phase 2 if the task touches them. @@ -64,6 +70,9 @@ Brian installs the release build and runs keyboard-only QA on the native app. Yo - Every QA comment must include: the exact keyboard/command palette steps used, what was visible before and after, and any edge case tested. - If you cannot test a feature using keyboard only (osascript shortcuts + command palette), the feature is not keyboard-first → QA fails. +**⚠️ Phase 1 is YOUR quality gate, not a formality.** +Brian's Phase 2 QA is a *reinforcement* check, not the primary gate. If Brian finds a bug in Phase 2 that you could have caught in Phase 1, that is a Phase 1 failure — not a Phase 2 discovery. Before firing the done signal, ask yourself: "Did I actually verify, in Playwright, that the feature works end-to-end exactly as the spec describes?" If the answer is "I ran the smoke tests and they passed", that is not enough. You must run your task-specific test and verify the acceptance criteria one by one. + **⚠️ Test in a clean environment when the feature depends on state.** If a feature involves indexing, fresh installs, first-time setup, or anything that only runs once: - **Do not test in the existing dev vault** — it already has the state you're trying to test.