@alwaysmeticulous/debug-workspace 2.261.0

package/dist/templates/templates/settings.json

@@ -0,0 +1,82 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Edit",
+      "Write",
+      "Task",
+      "Bash(find *)",
+      "Bash(grep *)",
+      "Bash(ls *)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git show *)",
+      "Bash(git status)",
+      "Bash(git rev-parse *)",
+      "Bash(git blame *)",
+      "Bash(git grep *)",
+      "Bash(diff *)",
+      "Bash(wc *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(sort *)",
+      "Bash(uniq *)",
+      "Bash(jq *)",
+      "Bash(cat *)"
+    ],
+    "ask": ["WebFetch", "WebSearch"],
+    "deny": [
+      "Edit(debug-data/**)",
+      "Write(debug-data/**)",
+      "mcp__*",
+      "ToolSearch",
+      "ListMcpResourcesTool",
+      "ReadMcpResourceTool"
+    ],
+    "defaultMode": "default"
+  },
+  "spinnerVerbs": {
+    "mode": "replace",
+    "verbs": [
+      "Analyzing",
+      "Investigating",
+      "Comparing",
+      "Searching",
+      "Processing",
+      "Squinting at screenshots",
+      "Traversing tangled timelines",
+      "Fighting fickle flakes",
+      "Diagnosing dubious diffs",
+      "Reconciling replays",
+      "Deciphering devious divergences",
+      "Debugging flakes",
+      "Patching network sessions",
+      "Determining nondeterminism"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/load-context.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/check-file-size.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/templates/templates/skills/debugging-diffs/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: debugging-diffs
+description: Investigate unexpected visual differences between head and base replays. Use when screenshot diffs are flagged or visual regressions are reported.
+---
+
+# Debugging Screenshot Diffs
+
+Use this guide when investigating unexpected visual differences between head and base replays.
+
+## Investigation Steps
+
+### 1. Understand the Diffs
+
+- Read the replay diff JSON in `debug-data/diffs/<id>.json`.
+- Check `screenshotDiffResults` for which screenshots differ.
+- Note the diff percentage and pixel count for each screenshot.
+
+### 2. Correlate with Code Changes
+
+- Check `commitSha` in `context.json` to identify the code changes.
+- If `project-repo/` is available, use `git log` and `git diff` to see what changed.
+- Focus on CSS changes, component rendering logic, and layout modifications.
+
+### 3. Compare Logs at Screenshot Time
+
+- Find the screenshot timestamps in `timeline.json`.
+- Compare what events occurred before each screenshot in head vs base.
+- Look for missing or extra events that could cause visual differences.
+
+### 4. Check for Expected vs Unexpected Diffs
+
+- **Expected**: Code changes that intentionally modify the UI (new features, style updates).
+- **Unexpected**: Same code producing different visual output, or unrelated areas changing.
+- Check if the diff is in a dynamic content area (timestamps, counters, user-specific data).
+
+### 5. Examine Snapshotted Assets
+
+- If `debug-data/replays/{head,base}/<replayId>/snapshotted-assets/` exists, compare JS/CSS between head and base.
+- Look for changes in CSS that could cause layout shifts.
+- Check for new or modified JavaScript that affects rendering.
+
+### 6. Review Screenshot Assertions Config
+
+- Check `screenshotAssertionsOptions` in the diff JSON for threshold settings.
+- Some diffs may be within acceptable tolerance but still flagged.
+
+### 7. Known Meticulous Replay Behaviors (Safe to Approve)
+
+The following patterns are caused by Meticulous replay engine behavior, not by your code changes. When these are the root cause of a diff, the diff is safe to approve.
+
+**Animation flakes**: Continuous animations (Lottie, CSS `@keyframes`, `requestAnimationFrame` loops) can cause screenshots to land at slightly different animation states between base and head, even with no code changes. Meticulous's DOM stability detection triggers extra animation frames trying to reach a stable state, but continuous animations never fully stabilize. **How to confirm**: check `replayComparison` in `context.json` for differing `totalAnimationFrames`; check log diffs for different animation frame counts; search the codebase for `lottie`, `requestAnimationFrame`, CSS `animation`, `@keyframes`, `<canvas>`, `<video>`. If the only visual difference is an animation in a different frame, this diff is safe to approve.
+
+**Network timing differences**: When multiple network responses complete at the same virtual time, slight ordering differences can cause minor rendering variations (e.g. a list rendering in a different order before settling). **How to confirm**: log diffs show network requests completing in a different order at the same virtual time, but the final rendered state is the same or nearly identical. If no code change caused the reordering, this diff is safe to approve.
+
+**Extra DOM stability frames**: The head replay may show more timeline events before a screenshot than the base, caused by DOM stability detection running additional animation frames. If the extra events are all animation-frame-related and the visual diff is minor, this diff is safe to approve.
+
+When any of these patterns is the root cause, tell the user: "This diff is caused by a known Meticulous replay behavior, not by your code changes. It is safe to approve."

package/dist/templates/templates/skills/debugging-flakes/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: debugging-flakes
+description: Investigate flaky or non-deterministic replay behavior. Use when replays produce different results across runs of the same session against the same code.
+---
+
+# Debugging Flaky Replays
+
+A flaky replay is one that produces different results (screenshots, logs, behavior) across
+multiple runs of the same session against the same code. Use this guide when investigating
+non-deterministic behavior.
+
+## Investigation Steps
+
+### 1. Compare Deterministic Logs
+
+- Diff `logs.deterministic.txt` between the head and base replays.
+- Look for the first point of divergence -- this is usually where the flake originates.
+- Pay attention to event execution order differences.
+
+### 2. Check Timeline for Timing Issues
+
+- Read `timeline.json` and look for events with significantly different virtual timestamps.
+- Look for race conditions: events that depend on network responses or animations completing.
+- Check for `setTimeout`/`setInterval` patterns that may resolve differently.
+
+### 3. Analyze Accuracy Data
+
+- Read `accuracyData.json` for the replay's self-assessment of accuracy.
+- Low accuracy scores often correlate with flakiness.
+- Check which specific checks failed.
+
+### 4. Look for Common Flake Patterns
+
+- **Animation timing**: CSS transitions or JS animations that haven't completed when screenshot is taken.
+- **Network race conditions**: API responses arriving in different order.
+- **Date/time dependencies**: Code that uses `Date.now()` or renders timestamps.
+- **Random values**: Code using `Math.random()` that wasn't properly seeded.
+- **Lazy loading**: Content loaded on intersection observer timing.
+- **Font loading**: Web fonts loading at different times causing layout shifts.
+
+When any of these patterns is identified as the root cause and no user code change is involved, the resulting diff is caused by non-determinism in the replay environment, not the user's code. Advise the user that these diffs are **safe to approve**.
+
+### 5. Check Replay Parameters
+
+- Compare `launchBrowserAndReplayParams.json` between runs.
+- Verify viewport size, user agent, and other environment settings match.
+- Check if network stubbing configuration is consistent.
+
+### 6. Examine Stack Traces
+
+- Read `stackTraces.json` for any errors thrown during replay.
+- Errors that occur in some runs but not others are strong flake indicators.

package/dist/templates/templates/skills/debugging-network/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: debugging-network
+description: Investigate network-related replay failures and divergences. Use when replays fail due to network errors, stubbing issues, or request ordering problems.
+---
+
+# Debugging Network Issues
+
+Use this guide when replays fail or diverge due to network request problems.
+
+## Investigation Steps
+
+### 1. Check Logs for Network Errors
+
+- Search `logs.concise.txt` for "network", "fetch", "xhr", "request", "response", "timeout".
+- Look for failed requests, unexpected status codes, or missing responses.
+- Check for CORS errors or SSL issues.
+
+### 2. Compare Network Activity in Timeline
+
+- In `timeline.json`, look for network-related events.
+- Compare the sequence and timing of network requests between head and base.
+- Look for requests in one replay that are missing in the other.
+
+### 3. Examine Session Data
+
+- Read session data in `debug-data/sessions/<id>/data.json`.
+- Check `recordedRequests` for the original HAR entries captured during recording.
+- Compare recorded requests with what was replayed.
+
+### 4. Look for Stubbing Issues
+
+- Network requests are stubbed during replay using recorded data.
+- Check if new API endpoints were added that don't have recorded responses.
+- Look for requests with dynamic parameters (timestamps, tokens) that may not match stubs.
+
+### 5. Check for Request Ordering Dependencies
+
+- Some applications depend on requests completing in a specific order.
+- Look for race conditions where parallel requests resolve differently.
+- Check for waterfall dependencies (request B depends on response from request A).
+
+### 6. Verify API Compatibility
+
+- If the API was changed, recorded responses may no longer be valid.
+- Check for schema changes, new required fields, or renamed endpoints.

package/dist/templates/templates/skills/debugging-sessions/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: debugging-sessions
+description: Investigate problems with recorded session data. Use when session recordings appear incomplete, corrupted, or contain unexpected data.
+---
+
+# Debugging Session Data Issues
+
+Use this guide when investigating problems with the recorded session data itself.
+
+## Investigation Steps
+
+### 1. Examine Session Structure
+
+- Read `debug-data/sessions/<id>/data.json` (this can be very large, use grep/search).
+- Key fields: `rrwebEvents`, `userEvents`, `recordedRequests`, `applicationStorage`, `webSockets`.
+
+### 2. Check User Events
+
+- `userEvents` contains the sequence of user interactions that will be replayed.
+- Verify events are in chronological order.
+- Check for truncated or incomplete event sequences.
+- Look for unusually rapid event sequences that may indicate automated behavior.
+
+### 3. Verify Network Recordings
+
+- `recordedRequests` contains HAR-format entries of network activity.
+- Check for missing responses (the request was recorded but the response wasn't).
+- Look for very large responses that might have been truncated.
+- Verify content types and encoding are preserved correctly.
+
+### 4. Check Application Storage
+
+- `applicationStorage` captures localStorage, sessionStorage, and cookies.
+- Verify that authentication state is properly captured.
+- Look for expired tokens or sessions that may cause different behavior during replay.
+
+### 5. Look for Session Quality Issues
+
+- Very short sessions (few events) may not provide meaningful coverage.
+- Sessions with `abandoned: true` were not completed normally.
+- Check `numberUserEvents` and `numberBytes` for unusually small or large values.
+
+### 6. Verify Recording Environment
+
+- Check session metadata for the recording environment (hostname, URL).
+- Ensure the session was recorded against a compatible version of the application.
+- Look for environment-specific behavior (staging vs production data).

package/dist/templates/templates/skills/debugging-timelines/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: debugging-timelines
+description: Investigate timeline divergence between head and base replays. Use when event sequences, ordering, or timing differ unexpectedly.
+---
+
+# Debugging Timeline Divergence
+
+Use this guide when replay timelines differ unexpectedly between head and base runs.
+
+## Investigation Steps
+
+### 1. Load and Compare Timelines
+
+- Read `timeline.json` from both head and base replay directories.
+- The timeline is an array of events with timestamps, types, and data.
+- Look for the first event where the timelines diverge.
+
+### 2. Understand Event Types
+
+Key timeline event types:
+
+- **user-event**: User interactions (click, type, scroll, hover).
+- **network-request**: API calls and responses.
+- **screenshot**: Screenshot capture points.
+- **mutation**: DOM mutations observed during replay.
+- **navigation**: Page navigation events.
+- **error**: JavaScript errors.
+- **console**: Console log messages.
+
+### 3. Identify Divergence Patterns
+
+- **Missing events**: Events in base that don't appear in head (or vice versa).
+- **Reordered events**: Same events but in different sequence.
+- **Timing shifts**: Events at significantly different virtual timestamps.
+- **Extra events**: New events not present in the baseline.
+
+### 4. Check Timeline Stats
+
+- Read `timeline-stats.json` for aggregated statistics.
+- Compare event counts, durations, and error counts between replays.
+
+### 5. Trace Back to Root Cause
+
+- Once you find the divergence point, look at what happened immediately before.
+- Check if a user event triggered different behavior.
+- Look for conditional logic in the application that might execute differently.
+
+### 6. Cross-Reference with Logs
+
+- Use timestamps from the timeline divergence to find corresponding log entries.
+- Check `logs.deterministic.txt` at the same virtual time for additional context.

package/dist/templates/templates/skills/pr-analysis/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: pr-analysis
+description: Analyze PR source code changes and correlate with screenshot diffs. Use when pr-diff.txt is present and you need to understand which code changes caused visual differences.
+---
+
+# PR Analysis
+
+When `debug-data/pr-diff.txt` is present in the workspace, analyze the source code changes and correlate
+them with the screenshot diffs.
+
+1. Read `debug-data/pr-diff.txt` to understand what code changed
+2. Read the diff summaries in `debug-data/diffs/*.summary.json` to see which screenshots differ
+3. For each screenshot that differs, identify which code changes are most likely responsible
+
+Provide a structured analysis:
+
+- Which files were modified and what the key changes are
+- Which code changes are most likely to affect visual output (CSS, layout, component rendering)
+- For each differing screenshot, the most likely code change that caused it
+- Whether the visual changes appear intentional (matching the code intent) or unintentional

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@alwaysmeticulous/debug-workspace",
+  "version": "2.261.0",
+  "description": "Shared debug workspace pipeline for investigating Meticulous diffs and replays",
+  "license": "ISC",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "@alwaysmeticulous/client": "2.261.0",
+    "@alwaysmeticulous/common": "2.260.2",
+    "@alwaysmeticulous/downloading-helpers": "2.261.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.17"
+  },
+  "author": {
+    "name": "The Meticulous Team",
+    "email": "eng@meticulous.ai",
+    "url": "https://meticulous.ai"
+  },
+  "engines": {
+    "node": ">= 12"
+  },
+  "homepage": "https://github.com/alwaysmeticulous/meticulous-sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alwaysmeticulous/meticulous-sdk.git",
+    "directory": "packages/debug-workspace"
+  },
+  "bugs": {
+    "url": "https://github.com/alwaysmeticulous/meticulous-sdk/issues"
+  },
+  "scripts": {
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "build": "tsc --build tsconfig.json",
+    "postbuild": "cp -r src/templates dist/templates",
+    "dev": "tsc --build tsconfig.json --watch",
+    "format": "prettier --write src",
+    "lint": "eslint \"src/**/*.{js,ts,tsx}\"  --cache",
+    "lint:commit": "eslint --cache $(git diff --relative --name-only --diff-filter=ACMRTUXB master | grep  -E \"(.js$|.ts$|.tsx$)\")",
+    "lint:fix": "eslint \"src/**/*.{js,ts,tsx}\"  --cache --fix",
+    "depcheck": "depcheck --ignore-patterns=dist",
+    "test": "vitest run --passWithNoTests"
+  }
+}