From cf8425d7440c8de43b1ec861ad64f88367d49f41 Mon Sep 17 00:00:00 2001 From: Marcel Date: Sun, 22 Mar 2026 19:44:18 +0100 Subject: [PATCH] docs(collab): add user journey and E2E scenario requirements Every feature issue must include a User Journey and E2E Scenarios section before implementation begins. Refs #48 Co-Authored-By: Claude Sonnet 4.6 --- COLLABORATING.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/COLLABORATING.md b/COLLABORATING.md index 771eec9b..04a8c019 100644 --- a/COLLABORATING.md +++ b/COLLABORATING.md @@ -43,6 +43,42 @@ Repeat for each new behavior. - The Refactor step must not change behavior — if a test breaks, the refactor introduced a bug. - If a bug is reported with no test, write the failing test first, then fix it. +## User Journeys & E2E Acceptance Criteria + +Every `feature` issue must include two sections before any implementation begins: + +### 1. User Journey + +A plain-prose description of the steps a user takes to get value from the feature. Written from the user's perspective, not the implementation's: + +> User opens a document, clicks "History", sees a chronological list of changes with editor name and timestamp. Clicking a row expands the old vs. new values. + +This makes the scope concrete and prevents scope creep — anything not in the journey is out of scope for the issue. + +### 2. E2E Scenarios + +One or more acceptance criteria written as Playwright-ready scenarios. These become the outermost Red test in the TDD cycle — no feature is considered done until all its E2E scenarios pass: + +``` +Scenario: View edit history of a document + Given I am on a document detail page + When I click the "History" tab + Then I see at least one revision entry + And each entry shows the editor's name and a timestamp +``` + +Use this format consistently. It maps directly to `test.describe` / `test` blocks in the Playwright spec. + +### Where this fits in the workflow + +``` +Issue (Journey + Scenarios) → Red E2E test → Implementation → Green +``` + +The scenarios in the issue are the contract. Write them before planning, treat them as failing tests from day one. + +--- + ## Issue Tracking (Gitea) All work is tracked in **Gitea** at `http://192.168.178.71:3005` (repo `marcel/familienarchiv`). Never use todo files or CLAUDE.md notes as a substitute.