Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Clarify visual verification requirements based on change type

Maximilian Roos0c7eb9266fe0
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index a9a602128..47ab11627 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -34,24 +34,24 @@ cd docs && zola serve
If the server isn't already running, start it as a background process or in a separate terminal session before completing work. The user should be able to immediately see rendered changes without needing to manually start the server.
-### Visual review requirement
+### Verifying changes
-**Always verify changes visually before returning to the user.** Use Playwright MCP (or similar browser automation) to:
+**Text-only changes** (prose edits, content rewrites, documentation fixes): Run pre-commit and provide the dev server link. Playwright verification is not required — the user can review rendered content directly.
-1. Navigate to the affected page(s)
-2. Take a snapshot or screenshot to verify the rendered output
-3. Check that changes meet the stated goal
-4. Iterate if the result doesn't match expectations
+**Visual changes** (CSS, layout, templates, responsive breakpoints): Use Playwright MCP to verify before returning. Visual bugs often hide in CSS specificity, template inheritance, and responsive behavior that aren't apparent from reading code.
-This is non-negotiable for visual work. Code that "looks correct" often renders incorrectly due to CSS specificity, template inheritance, or responsive breakpoints. The feedback loop is: edit → view → assess → repeat until satisfied.
+Playwright workflow for visual changes:
+1. Navigate to affected page(s)
+2. Take a snapshot to verify rendered output
+3. Iterate if the result doesn't match expectations
-Common issues to check:
-- Text actually appears where expected
-- Spacing and alignment look correct
-- No visual regressions on nearby elements
-- Responsive behavior at different viewport sizes (use `browser_resize`)
+Common visual issues to check:
+- Text positioning and visibility
+- Spacing and alignment
+- Regressions on nearby elements
+- Responsive behavior (use `browser_resize`)
-**Always include the dev server link in your response** when returning to the user after making doc changes:
+**Always include the dev server link** when returning after doc changes:
```
View changes: http://127.0.0.1:1111