claude-mcp-workflow 0.1.7 → 0.1.9

package/templates/skills/architecture/SKILL.md

@@ -21,7 +21,7 @@ Three questions (if you can't answer all three concretely, suggest the simpler o
 **GOTCHA:** Single implementation behind interface is ceremony, not architecture
 **EXCEPTION:** Public library APIs only
 
-Sonnet defaults to "interfaces for testing are fine" — this skill corrects that.
+Models often default to "interfaces for testing are fine" — this skill corrects that.
 
 ## Response Template
 
@@ -107,6 +107,17 @@ When moving filtering logic from a caller into a shared state manager (allocator
 
 **Rule:** A generic `isX()` that returns the same answer for semantically different states is a lossy abstraction. Before using it, check: does the original code care *why* the state is set, not just *that* it's set?
 
+## Deleting a Mechanism for ONE Rejected Job — Enumerate ALL Its Jobs First
+
+When you remove a function/call because one of its responsibilities is rejected or obsolete, list **every** side effect it has before deleting it. A mechanism named for one concern often quietly carries a second, still-needed concern — and the name masks it, so wholesale deletion silently disables the second.
+
+**DON'T:** See "this does the rejected X" → delete the whole call/function.
+**DO:** Trace every effect (what it sets, reveals, schedules, gates). Keep the still-needed effects; remove only the rejected one — often by splitting the dual-purpose function.
+
+**Tell:** the deleted thing was a per-frame/lifecycle hook whose name describes only one job (`dodge`, `sync`, `refresh`); the regression appears in an *adjacent* concern (visibility, enablement, layout), not the one you were targeting — and surfaces late (doc/visual pass), not in the correctness check.
+
+**Concrete example (illustrative):** A per-frame `noteActorPosition` did TWO things via one alpha lane — faded decorative props IN (made the field *visible*) and faded them OUT near the moving actor (the *proximity dodge*). The user rejected the dodge (alpha-hiding the path). Deleting the whole call removed the dodge **and** the field's visibility → the entire decorative prop field went invisible (`alpha=0` forever). Fix: split — keep a one-time fade-IN (reveal) gated by a `fadeIn` flag, drop only the per-frame fade-OUT. The reveal and the dodge had been fused in one function; the name ("dodge") hid the reveal.
+
 ## Refactoring Scope: Don't Escalate Lifecycle
 
 When refactoring an inline operation into a two-phase approach (set intent + execute), match the original operation's lifecycle scope.
@@ -118,6 +129,23 @@ When refactoring an inline operation into a two-phase approach (set intent + exe
 
 **Rule:** Before adding lifecycle management to a refactored operation, check: did the original operation need it? If the original worked within existing infrastructure (setters, listeners), the refactored version should too.
 
+## Signature Change → Grep All Callsites
+
+When changing a method's return type, parameter list, or visibility, grep ALL callsites BEFORE finalizing the change.
+
+A signature change compiles fine in the modified file but silently breaks callers that ignore the new return type. Example: `clearData(): void` → `clearData(): ITask` — callers that fired-and-forgot still compile; the returned ITask is constructed and discarded; the async work never starts. No compile error, no exception — the cleanup pipeline is a no-op.
+
+**Symptom**: behavior silently regresses in code paths nobody runs during initial smoke test. Caught later by code reviewers, integration tests, or production bugs.
+
+**DON'T:** Change a signature, run the obvious test, declare done.
+**DO:** Change a signature, grep `<methodName>\b` across the whole project, audit each callsite. Trust "find references" only if the IDE has full project indexing.
+
+**Adding a member to an interface/abstract type is also a signature change.** Every implementor must gain the member — including hand-written test doubles / fakes / in-memory stubs, not just production classes.
+
+**Tooling gotcha:** test runners that strip types via esbuild/swc (vitest, ts-jest `isolatedModules`, bun test) do NOT typecheck. A test double missing a newly-added interface method compiles fine and fails at RUNTIME as `TypeError: x.method is not a function` — often in unrelated tests that happen to reach the missing call. `tsc --noEmit` catches it; the test run alone does not.
+
+**DO:** after adding an interface member, grep for `implements <Interface>` and for the type used as a field/param type, and update every implementor (prod + test) in the same change; run `tsc` (not just the test suite) before declaring done.
+
 ## New Canonical Path → Ask About Legacy Parallels
 
 When you add a new canonical input/output mechanism that does the same thing as existing legacy paths (e.g. UI buttons that replicate keyboard shortcuts, a typed API replacing an untyped one, a structured event replacing a string topic), the default urge is to keep the legacy paths "for compatibility" and build a coexistence shim. Don't.
@@ -130,3 +158,105 @@ When you add a new canonical input/output mechanism that does the same thing as
 **Symptom of violation:** you find yourself adding gating logic (coordinate checks, `if (ev.target === ...)` filters, `inflight` flags) just to make two input paths coexist when one is meant to subsume the other.
 
 **Rule:** A new canonical mechanism is an opportunity to remove the old one, not to add a referee between them. If the user didn't explicitly ask to keep both, ask before keeping both.
+
+## Accumulation/Leak Bugs: Fix the Lifecycle, Not a Sweep
+
+When something grows unbounded (state files, DB rows, temp dirs, handles, cache entries), the artifact has a creation event but no deletion event tied to its owner's lifecycle.
+
+**DON'T:** Add a periodic retention/TTL/prune sweep ("delete things older than N days"). It leaves the leak in place, adds a tunable nobody sets correctly, and needs a guard against its own edge cases (NaN window deleting everything).
+**DO:** Tie the artifact's lifetime to its owner. Delete it at the terminal transition (session ends → its file is removed; process dies → its records go). The owner that creates it owns destroying it.
+
+**Tell:** if your fix introduces a `RETENTION_DAYS`/`maxAge`/cleanup-cron, ask "why does this outlive its owner at all?" A retention sweep is a legitimate *policy* for audit data deliberately kept; it is the wrong tool for a missing teardown.
+
+**Before designing the fix:** check sibling/related projects for an already-shipped fix of the same bug class (same author/org repos especially) and mirror its approach instead of inventing a parallel one.
+
+## Repeated Same Symptom After 2+ Fixes = Wrong Subsystem Target
+
+When the user reports the same perceived symptom after two or more rounds of plausible fixes, stop patching that surface. A symptom that survives multiple reasonable fixes is almost always at the **seam between two decoupled subsystems** — a baked/precomputed path vs. a live event; a cached value vs. its source; a predicted position vs. an independently-simulated actor.
+
+**DON'T:** Keep refining one side each iteration — curve shape, easing, constants, thresholds — to match the user's latest wording.
+
+**DO:** By the 2nd repeat, trace BOTH subsystems end-to-end and ask: "why do these two representations exist, and must they?" The fix is to make them **coincide** — re-derive one from the other at the authoritative moment — not to tune one side.
+
+**Tell:** Every "fix" addresses the user's latest description verbatim, yet the user keeps saying "same thing / didn't help." You find yourself adjusting geometry or timing constants repeatedly with no lasting effect.
+
+**GOTCHA:** The seam is invisible when you look at only one subsystem. You must trace both from their shared input to their diverging output paths to see the gap.
+
+**Concrete example:** A game ball flew a fixed pre-baked bézier to a predicted endpoint; the actual hit fired from a per-frame overlap test against a separately-simulated moving sprite. Four curve-shape fixes (overshoot, speed, bulge, straight-line) all failed because the real defect was the timing seam between the two decoupled systems. Resolution: re-derive the sprite's velocity at the true flight start so ball and sprite converge at one shared point. Cost: 5 user round-trips before the architecture was traced.
+
+## Regressing Feature? Find the Principled Algorithm the Codebase Already Has
+
+When a feature keeps regressing across many patch cycles — tuning constants, reshaping curves, adjusting thresholds — stop inventing ad-hoc logic. Ask: **"what does correct behavior fundamentally require, and does this codebase already compute that for some other case?"**
+
+**DON'T:** Keep hand-rolling case-specific geometry or heuristics to chase the latest symptom. Each variant is "more specific" than the last and never converges.
+
+**DO:** Grep for the concept (clearance, retry, normalization, lift…). If a general implementation exists, find why the failing case is excluded from it — an early `return`, a zone guard, a capability flag. That exclusion is the smoking gun: someone already solved it generally, then deliberately opted out the hard case. Mirror or apply that proven algorithm to the excluded case, using its same constants and sampling strategy for parity. Ask the "do we already do it elsewhere?" question by the **2nd** regression, not the 6th.
+
+**Tell:** You're writing the Nth variant of the same code path and each fix is narrower than the last. A sibling module has a richer version of the same routine that the failing path doesn't call.
+
+**GOTCHA:** The exclusion guard often looks load-bearing (e.g., "air shots have no terrain"). Verify it with the principled algorithm before assuming it's correct — it may just be an early simplification that was never revisited.
+
+**Concrete example (illustrative):** An air-launched projectile kept clipping terrain through ~6 patch iterations (overshoot tweaks, speed adjustments, straight-line approximations). The math package already had a `raiseArcOverTerrain` routine — raises a bézier peak until it clears terrain minus a margin — but it explicitly `return`ed early for `zone === 'air'`. Fix: mirror that exact algorithm renderer-side for the excluded zone. No amount of curve reshaping could have matched it because the principled clearance math was simply never reached.
+
+## Changing a Value Invalidates State Sized From Its OLD Value — Not Just Live Readers
+
+When you change a parameter X, the instinct is to update code that **reads** X. But state that was **computed/staged earlier** from X's old value (a precomputed position, a cached offset, a buffer size, a timeout deadline) doesn't "read" anything — it silently encodes the stale quantity. Those frozen values contradict the new X, often by the full ratio of old/new.
+
+**DON'T:** Change X, fix the obvious live consumers, ship. The stale-derived state then fires with pre-change geometry/timing intact.
+
+**DO:** When changing X, enumerate not just "who reads X now" but "what was sized/positioned/scheduled FROM X (possibly long before X changed)." Re-derive those from the new X, or trigger their recompute at the moment X takes effect.
+
+**Tell:** a downstream actor moves/scales ~the ratio of old:new too far/fast (e.g. ~10×); a thing that used to line up now overshoots by a suspiciously clean multiple; bug magnitude ≈ `oldValue / newValue`.
+
+**GOTCHA:** The stale computation may happen at a different time (launch, init, precompute pass) than the code you just changed (tick, render, callback). Grep for every site that captures a derived value from X into a local variable, struct field, or closure — those are the freeze points.
+
+**Concrete example:** A projectile's flight duration was shortened ~6×. The flight-playback code was updated. But an interceptor's ENTRY POSITION had been staged at launch as `start + speed · OLD_duration` (far away, sized for the long flight); the resync only re-solved its velocity over that stale far position → it streaked in ~10× too fast. Fix: re-STAGE the entry from the new duration (`position + velocity · newDuration`), not just re-solve velocity. The corrected duration must drive every derived value — including positions frozen before the change — from a single source.
+
+## "Impossible in the Limit" ≠ "Cheap Lever Fails the Actual Case"
+
+When a global constant's effect scales with a per-case input, no single value can satisfy ALL inputs — that proof is correct. But it does NOT establish that the constant fails the specific case in front of you.
+
+**DON'T:** Write an elegant impossibility argument for the general case and propose a per-case solver/refactor without having run the simple fix once.
+**DO:** Try the cheapest knob empirically first — adjust the constant, widen the relevant tolerance, measure the real target. Reserve the heavy solution for when the simple lever is *measured* to fail, not when it's only *proven* imperfect in the limit.
+
+**Principle:** "Can't be perfect for all" ≠ "doesn't work for this." Empirical failure on the actual target is required evidence; theoretical failure on adversarial inputs is not.
+
+**Tell:** You're composing a sound argument for why a simple fix "structurally cannot work" and proposing architecture instead — without having run the simple fix once. That's the signal to stop, try the knob, and measure.
+
+## A Claimed-Negative Tradeoff Needs the Same Evidence as a Claimed-Impossible Fix
+
+The mirror of "Impossible in the Limit ≠ Cheap Lever Fails": just as you must not call a simple fix impossible without running it, do not tell the user a change makes things WORSE without deriving the actual result. A negative framing extrapolated from a stale note, a prior decision, or an intuitive "it'll scatter / fragment / break" mental model is not evidence.
+
+**DON'T:** Warn "this will be markedly worse" / "destroys the existing structure" from memory or intuition, then ask the user whether to proceed.
+**DO:** Run the concrete analysis that confirms or refutes the claim FIRST — then present the measured result, and only flag a downside that survives the measurement.
+
+**Tell:** You're about to present a tradeoff as a downside, and your reason is a remembered decision ("we left this alone before") or a shape you pictured ("members will scatter"), not something you computed on the actual artifact.
+
+**Concrete example:** Asked to apply an automated member-reorder to a 12k-line god-file, the agent told the user it would be "markedly worse" — destroying intentional locality, exploding one guard block into scattered fragments — citing a stale "leave this file alone" note. The user pushed back: "why worse? I expect better." The analysis the agent should have done first: a sorted line-multiset diff (proved the reorder was a pure permutation — zero content changed) and an index-contiguity + identical-condition-dedup check (proved the guarded cluster stayed one contiguous block). The real change was mild and arguably cleaner. The unmeasured negative cost a user round-trip.
+
+**Principle:** "I think this is worse" is a hypothesis, not a finding. Before it reaches the user as a reason to hesitate, derive it on the real input — the cost of measuring is usually one command; the cost of a wrong negative is a wasted round-trip and a user who now distrusts your tradeoff calls.
+
+## "How Did It Work Before?" = Revert Signal
+
+When the user asks "how did the old way work?", "why not keep it simple / slightly different?", or "did you even try the original approach?" — that is not a request to polish the new mechanism. It is evidence the new direction is wrong.
+
+**DON'T:** Defend the new design across multiple fix→verify cycles, trading one symptom for another, while the user keeps invoking prior behavior.
+**DO:** By the 2nd such pushback, diff against the pre-change baseline. Articulate honestly what the original did and why it was adequate. Offer to revert before sinking more cycles.
+
+**Tell:** You are on the 3rd+ iteration fixing your own new mechanism; each fix introduces a new symptom; the user's questions consistently reference what it used to do. The thrash itself is the signal — the baseline was right.
+
+**Principle:** Repeated pushback that references prior/simpler behavior is not polish feedback — it is a direction correction. Reverting to a known-good baseline is a first-class fix, not a failure.
+
+## The User's Named Beat IS the Acceptance Criterion
+
+When the requirement names a concrete observable event — a strike, a bounce, a wobble, a specific sequence — that beat is not a flourish. It is the spec. Reproducing the surrounding motion while omitting the named beat is a wrong implementation, not a simpler one.
+
+**Observed failure:** User asks for "X hits a corner and visibly bounces, then branches." Agent repeatedly delivers a fast ease-to-stop or a smooth pass-through — dropping the bounce — and declares it done. Each simplification felt cleaner or more physically plausible. User rejected it each time: "there is no bounce, this is identical to the plain case." Required explicit re-statement of the task before the beat was built.
+
+**Tell:** You're choosing a motion because it's easier to implement or "reads cleaner," and the specific event the user named is no longer distinctly visible in the result. Or: the user says the new thing "looks the same as the old/plain one."
+
+**DON'T:** Trade away a named beat for implementation simplicity or "physical plausibility" concerns without surfacing the trade-off.
+**DO:**
+1. Enumerate every named beat from the request.
+2. For each, define how it will be **distinctly observable** (numerically or visually) and assert it before claiming done.
+3. If you're about to drop a beat because it's hard or feels unphysical, surface that trade-off explicitly — don't silently omit it.

package/templates/skills/aws-lambda/SKILL.md

@@ -7,30 +7,30 @@ description: AWS Lambda .NET deployment gotchas
 
 ## VPC Networking
 
-- **Subnet IP exhaustion on scale-up.** Each ENI consumes an IP from subnet. ENI account limit = 350 default. New instances silently fail to start when exhausted.
-- **ENI creation lag: up to 90s** when function is created or VPC config changes. Invocations during this window get unpredictable cold starts.
+- **ENIs are shared since the Hyperplane rework (2019)** — one ENI per subnet + security-group combo, created when the function is created or its VPC config changes, NOT per concurrent execution. Scale-up does not consume a subnet IP per instance, so subnet IP exhaustion from Lambda scaling is largely a pre-2019 concern.
+- **ENI provisioning takes up to ~90s** at function create / VPC-config change; the function reports `LastUpdateStatus: InProgress` until done. (The old per-invoke ENI cold-start penalty is gone.)
 - **S3/Secrets Manager calls timeout silently (not connection refused)** when Lambda is in VPC without NAT/VPC Endpoint. Easy to misdiagnose as SDK bug.
 
 ## Logging
 
-- **`Console.Error.WriteLine()` does NOT appear in CloudWatch.** Use `ILambdaContext.Logger.LogLine()` in handler code or `ILogger` in ASP.NET pipeline.
+- **`Console.Error.WriteLine()` IS captured by CloudWatch on the managed .NET runtime** (Lambda redirects the process's stdout/stderr) — but entries lack the request-id prefix and multi-line output splits into separate events. Output genuinely disappears only in narrower cases: writes during a crashed INIT (process torn down before flush) or a custom-runtime bootstrap that doesn't forward stderr. Prefer `ILambdaContext.Logger.LogLine()` in handler code or `ILogger` in the ASP.NET pipeline.
 - **Missing `logs:CreateLogGroup` permission = logs silently lost.** Log group created lazily on first invoke. No permission = no log group = nowhere to write = no error visible anywhere.
 
 ## ASP.NET Core in Lambda
 
-- **`UseHttpsRedirection()` hangs Lambda.** No Kestrel HTTPS port. Middleware hangs trying to discover one (aws-lambda-dotnet #1543). Only enable in Development.
-- **Response > 6MB crashes INIT phase, not 413.** `APIGatewayHttpApiV2ProxyFunction` throws exception in Lambda runtime client during initialization, taking down the entire ASP.NET Core app instead of returning HTTP error.
+- **`UseHttpsRedirection()` hangs Lambda.** No Kestrel HTTPS port. Middleware hangs trying to discover one (aws-lambda-dotnet #1543; discussion #1424 reports the same shape — handler completes but the response never reaches the runtime — as warm-invoke middleware timeouts on a custom runtime). Only enable in Development.
+- **Response > 6MB fails the invoke — no clean HTTP 413.** 6MB is the synchronous INVOKE-phase request/response payload limit (nothing to do with INIT). `APIGatewayHttpApiV2ProxyFunction` surfaces it as a runtime-client error for that invocation, so the caller sees a generic 500-style failure instead of a 413.
 
 ## S3 from Lambda
 
 - **SDK default timeout = infinite, retry = 4 with exponential backoff.** Total wait 30-60s can exceed Lambda timeout. Always set `Timeout` and `MaxErrorRetry` on `AmazonS3Config`.
-- **`AmazonS3Client` without explicit region defaults to `us-east-1`.** Cross-region requests are slower. No error if IAM allows it — silent performance degradation.
-- **IMDS credential error is cached.** If Instance Metadata Service is transiently unavailable during first init, SDK caches the error. All subsequent requests fail until container restart.
+- **Region fallback to `us-east-1` is a local-dev gotcha, not a Lambda one.** Inside Lambda the SDK resolves the region from the `AWS_REGION` env var the service injects. `new AmazonS3Client()` without explicit region silently targets `us-east-1` only when no env/profile region is configured — e.g. local integration tests — causing slow cross-region requests with no error.
+- **IMDS does not exist inside Lambda.** Credentials come from env vars (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_SESSION_TOKEN`) injected from the execution role. Any "IMDS credential error is cached until restart" advice applies to EC2/ECS, not Lambda.
 
 ## .NET Cold Start
 
-- **ReadyToRun (R2R) compiled on macOS/Windows is ignored in Lambda (Amazon Linux 2).** Must publish with `--runtime linux-x64`. R2R flag silently has no effect cross-platform.
-- **Container deploy: INIT phase is billed. ZIP deploy: INIT phase is free.** For .NET with heavy startup, significant cost difference.
+- **ReadyToRun (R2R) output is RID-specific — publish with `--runtime linux-x64` (or `linux-arm64`).** Since .NET 6, crossgen2 supports cross-OS compilation, so building ON macOS/Windows is fine as long as the target RID matches the Lambda runtime (dotnet8 runs on Amazon Linux 2023). R2R for the wrong RID silently has no effect.
+- **INIT-phase billing was standardized 2025-08: INIT is billed for ALL runtimes and packaging types.** Previously ZIP-deployed managed runtimes got the INIT phase free (container images were always billed). Heavy .NET startup now costs money either way — trim startup work or use SnapStart.
 - **EF Core `Database.Migrate()` default command timeout = 30s.** Heavy migrations fail with EF timeout, not Lambda timeout. Set `CommandTimeout` explicitly.
 
 ## Function URL

package/templates/skills/browser-verify/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: browser-verify
+description: Browser-automation verification gotchas — stale captures, caches, headless limits
+---
+
+## Browser-Automation Verification Gotchas
+
+Traps when verifying web/canvas apps through Playwright or a browser MCP.
+Common theme: **the automated browser is not the user's browser** — its
+pixels, caches, and performance all lie in specific, repeatable ways.
+
+### 1. Headless screenshot / `canvas.drawImage()` can return stale frames for a WebGL canvas
+
+Animated content driven by per-frame GPU updates (custom shader uniforms, skeletal animations, shader-displaced vertices) may show **zero pixel diff** between headless screenshots taken 100s of ms apart, even when JS-side instrumentation confirms the state is updating each frame (RAF firing, uniform buffers advancing, ticker handlers incrementing). Sampling the canvas through `tmp.getContext('2d').drawImage(canvas, ...)` returns the same byte-for-byte image across samples — the whole canvas is affected, not just one animation.
+
+Likely cause: with `preserveDrawingBuffer: false` (the default in most WebGL frameworks, incl. Pixi), the headless compositor reads from a cached present frame rather than the live WebGL back buffer.
+
+- Don't rely on headless pixel-diff to verify GPU-driven animation works.
+- Verify in a real browser tab (the user's running Chrome, not an automated instance).
+- For automated verification, prefer JS-side state assertions: a uniform buffer value advancing across samples is sufficient proof the upload pipeline is alive; visual verification needs human eyes or a non-headless captured video.
+
+### 2. Headed screenshots can ALSO be stale — a tab that was never frontmost composites its last presented frame
+
+The same failure occurs HEADED whenever the target tab/window is occluded or was created behind another tab: `page.screenshot()` returns the last frame the browser's compositor ever presented for that tab. Observed: the screenshot showed a boot preloader frozen at "96%" while JS-side numeric sampling in the SAME page proved the app was live (object positions advancing every 100 ms, game logs firing). DOM inspection confirmed the preloader element was long gone — the "96%" pixels existed only in the stale compositor frame.
+
+A second page created with `ctx.newPage()` and driven while another tab holds focus reproduces this; a page brought to front BEFORE its WebGL content started presenting captures real frames fine.
+
+- Wrong: `ctx.newPage()` for a background capture tab, drive it, screenshot it while another tab stays focused — canvas pixels freeze at whatever was on screen when it lost focus (or never had it).
+- Right:
+  - Reuse the context's initial tab (`ctx.pages()[0]`) rather than stacking `newPage()`s for capture work.
+  - Call `page.bringToFront()` immediately after `goto`, BEFORE the canvas first presents — not right before the screenshot.
+  - Treat JS-side numeric sampling (positions, probe state) as ground truth — it stays correct even when pixels are stale.
+  - For A/B visual comparisons, run each variant in its own sequential frontmost tab, never two tabs alternating.
+
+### 3. Playwright MCP browser reuses a PERSISTENT cache across sessions — it can serve STALE js modules / outdated app logic
+
+The Playwright MCP browser keeps a persistent profile + HTTP cache between conversations (`~/Library/Caches/ms-playwright-mcp/...` on macOS). A plain `browser_navigate` does NOT clear it, so when verifying app behavior against a dev server (e.g. Vite), the MCP browser can run **stale js modules** (a previous session's app-logic module) while the server already serves current code. The same seed/input then produces a DIFFERENT outcome in the MCP browser vs the user's real browser — and you'll confidently report the wrong result.
+
+- Symptom: same dev server, same input, **different console result logs** in your browser vs the user's; your "verified" outcome contradicts what the user sees on screen.
+- Red herring: a differing console source-LINE for the same log (e.g. playwright reports `logic.ts:103`, user's DevTools shows `:297`) is NOT a version mismatch — playwright reports the *transformed-module* line, DevTools the *sourcemapped source* line. Same code.
+- Ground truth = the LIVE console log of the actual run in a FRESH browser, AND the user's real browser. NEVER a scanner-only prediction: a scanner's dynamic `import()` can be cached independently of the static import the live app uses, so the two disagree.
+- Fix when your result conflicts with the user's: suspect YOUR cache first. `browser_close` then re-navigate relaunches a fresh browser instance — clears in-memory state and stale module instances, often enough against a dev server — but the default persistent mode reuses the same on-disk profile, so the HTTP disk cache/cookies survive. Guaranteed clean: run the MCP server with `--isolated`, point `--user-data-dir` at a throwaway dir, or delete the profile dir (`~/Library/Caches/ms-playwright-mcp/mcp-<channel>-<hash>` on macOS).
+- `tsc`/`vitest` run via node against DISK code, so they stay valid for code correctness; only the BROWSER render/logic can be cache-stale. Re-verify any live finding in a freshly-cleared browser before claiming it.
+- Cost when ignored: ~6 user round-trips insisting an input produced X while the user kept seeing Y — the user was right; the automated browser was stale.
+
+### 4. Headless WebKit/Chromium on a desktop machine is NOT GPU-bound — useless for measuring MOBILE GPU perf deltas
+
+When optimizing a WebGL scene for mobile/Safari GPU cost (resolution cap, MSAA, blend-mode overdraw, fill-rate), driving it with Playwright headless WebKit (or Chromium) on a desktop gives a **flat ~60 fps regardless of the renderer settings** — the desktop GPU absorbs pixel counts a phone can't. Observed: identical frame-time distribution (mean ~16.7 ms, p50 17, p99 18, 0 frames >33 ms) across BOTH `resolution=2` + MSAA on AND `resolution=1.5` + MSAA off, in the same scene. A headless FPS A/B between renderer configs shows **~0 delta by construction** and tells you nothing about the on-device win.
+
+- Don't conclude "the optimization didn't help" from a headless FPS A/B — the bottleneck isn't reproduced.
+- Measure the mobile GPU win **analytically** instead: device-pixel math (`resolution` 2.0→1.5 ⇒ `(1.5/2)² = 0.5625` ⇒ ~44% fewer fragment-shader invocations/frame), plus draw-call / additive-blend (overdraw) counting.
+- Verify **correctness** directly: confirm the mobile code path APPLIED — e.g. read effective resolution as `canvas.width / parseFloat(canvas.style.width)` and expect the cap (1.5), not the raw `devicePixelRatio` (3) — and assert gating/visibility logic toggles via state, not via a screenshot pixel-diff.
+- Trigger a mobile context so device-detection fires: `browser.newContext({ ...devices['iPhone 13'] })` gives iPhone UA + touch + DPR 3 + isMobile — but the ENGINE stays whatever you launched (the descriptor's `defaultBrowserType: 'webkit'` is honored only by the Playwright Test runner); launch `webkit` yourself to actually test WebKit.
+- Ground truth for absolute on-device FPS is a physical phone, which Playwright cannot drive.
+
+### Framework-specific siblings
+
+Rendering-framework-specific verification recipes (freezing a scene's tickers for a deterministic screenshot, sampling motion on the render ticker instead of your own rAF) live in the domain skills — e.g. `domain-pixi` for Pixi.js.

package/templates/skills/build-cmake/SKILL.md

@@ -7,24 +7,37 @@ description: CMake build system gotchas
 
 ## find_package Search Order
 
-**No mode specified = tries MODULE first, then CONFIG** (Sonnet reverses this!):
+**No mode specified = tries MODULE first, then CONFIG** (commonly reversed!):
 - First looks for `FindFoo.cmake` in CMAKE_MODULE_PATH (MODULE)
 - Then falls back to `FooConfig.cmake` (CONFIG)
 - `find_package(Foo)` might find wrong file — always specify CONFIG or MODULE explicitly
 
 ```cmake
-set(CMAKE_PREFIX_PATH "/opt/mylib")  # Finds FooConfig.cmake
-set(CMAKE_MODULE_PATH "/opt/mylib")  # Finds FindFoo.cmake — NOT the same!
+# CONFIG: CMAKE_PREFIX_PATH entries are PREFIXES — CMake searches
+# <prefix>/lib/cmake/Foo/, <prefix>/share/cmake/Foo/, etc.
+# for FooConfig.cmake or foo-config.cmake (not the prefix dir itself)
+set(CMAKE_PREFIX_PATH "/opt/mylib")
+
+# CONFIG: Foo_DIR points at the EXACT dir containing FooConfig.cmake
+set(Foo_DIR "/opt/mylib/lib/cmake/Foo")
+
+# MODULE: CMAKE_MODULE_PATH dirs are searched DIRECTLY for FindFoo.cmake — NOT the same!
+set(CMAKE_MODULE_PATH "/opt/cmake-modules")
 ```
 
-## CMP0077: Normal Variables Override Options
+## CMP0077: Normal Variables Override Options (add_subdirectory)
 
 ```cmake
-option(FOO_ENABLE_TESTS "..." OFF)
-set(FOO_ENABLE_TESTS ON)  # Pre-3.13: ignored! 3.13+ with CMP0077 NEW: overrides option
-cmake_policy(SET CMP0077 NEW)  # Let NORMAL variables (not cache) override options
+# Parent project configures a vendored subproject:
+set(FOO_ENABLE_TESTS OFF)   # normal variable — must be set BEFORE the option() executes
+add_subdirectory(foo)       # foo's CMakeLists.txt contains: option(FOO_ENABLE_TESTS "..." ON)
 ```
 
+- CMP0077 **OLD**: `option()` discards the pre-set normal variable and creates the cache entry → the parent's `OFF` is lost.
+- CMP0077 **NEW**: `option()` becomes a no-op when a normal variable of that name exists → the parent's `OFF` wins.
+
+The policy is controlled by the **subproject**: `cmake_minimum_required(VERSION 3.13...)` there, or `cmake_policy(SET CMP0077 NEW)` before its `option()` calls. The parent can force it for all subprojects with `set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)` before `add_subdirectory`.
+
 Key: this is about **normal** variables overriding `option()` cache entries — not cache-to-cache override.
 
 ## Ubuntu apt catch2 = v2, NOT v3
@@ -54,5 +67,8 @@ endif()
 FetchContent_Declare(Foo GIT_REPOSITORY https://github.com/org/foo.git GIT_TAG v1.0)
 
 # GOOD (no git needed):
-FetchContent_Declare(Foo URL https://github.com/org/foo/archive/refs/tags/v1.0.tar.gz)
+FetchContent_Declare(Foo
+    URL      https://github.com/org/foo/archive/refs/tags/v1.0.tar.gz
+    URL_HASH SHA256=<tarball-sha256>  # pin integrity — without it the download is unverified
+)
 ```

package/templates/skills/ci-github-actions/SKILL.md

@@ -18,14 +18,14 @@ description: GitHub Actions workflow gotchas
 The action resolves the most recent tag **reachable from the current commit** via git history. With the default `fetch-depth: 1`, no tags are reachable — the action returns empty or stale results.
 
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v7
   with:
     fetch-depth: 0  # required for tag resolution
 ```
 
 Same applies to `git describe`, `git log --follow`, `gitversion`, and any changelog generator that walks commit history.
 
-## `actions/checkout@v4` Default Fetches Only 1 Commit
+## `actions/checkout` Default Fetches Only 1 Commit (v4+)
 
 Unless `fetch-depth: 0` (full history) or `fetch-depth: N` is set, you get a shallow clone with depth 1. Breaks: tag lookup, `git log`-based changelogs, `git blame`, branch comparison diffs.
 
@@ -53,10 +53,12 @@ deploy:
 # RIGHT — run regardless, check status explicitly
 deploy:
   needs: [build]
-  if: always() && needs.build.result == 'success'
+  if: ${{ !cancelled() && needs.build.result == 'success' }}
   steps: ...
 ```
 
+Prefer `!cancelled()` over `always()`: `always()` forces the job to run even when the workflow run is being cancelled; `!cancelled()` lifts the "dependency failed/skipped" gate but still respects cancellation. (The `${{ }}` is required here — a bare `if:` starting with `!` is invalid YAML.)
+
 ## `$GITHUB_ENV` Changes Are Not Visible in the Same Step
 
 `echo "X=value" >> $GITHUB_ENV` exports `X` for all **subsequent** steps. The current step cannot read it.
@@ -99,46 +101,60 @@ jobs:
   test:
     continue-on-error: true   # whole matrix ignores failures
 
-# Matrix-level — only the flagged cell continues, others still gate the job
-strategy:
-  matrix:
-    os: [ubuntu, windows]
-  fail-fast: false
+# Cell-level — only the flagged cell continues, others still gate the job
 jobs:
   test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu, windows]
     continue-on-error: ${{ matrix.os == 'windows' }}  # only windows cell is optional
 ```
 
+Note `strategy:` lives under `jobs.<job>` — it is not a top-level workflow key.
+
 `fail-fast: false` (strategy level) keeps sibling cells running after one fails. `continue-on-error: true` (job level) prevents the job from being marked failed. They're orthogonal.
 
-## Artifact Names Must Be Unique Within a Run (actions/upload-artifact@v4)
+## Artifact Names Must Be Unique Within a Run (actions/upload-artifact v4+)
 
-v4 dropped the `overwrite` default — uploading two artifacts with the same name in one workflow run is an error, not a silent overwrite.
+v4 made artifacts immutable — uploading two artifacts with the same name in one workflow run is an error (v3 silently merged files into one artifact). Since v4.4 an explicit `overwrite: true` input deletes and replaces the existing artifact; the default is still an error.
 
 ```yaml
 # WRONG — both matrix cells upload "test-results", second one errors
-- uses: actions/upload-artifact@v4
+- uses: actions/upload-artifact@v7
   with:
     name: test-results
 
 # RIGHT — include matrix dimension in the name
-- uses: actions/upload-artifact@v4
+- uses: actions/upload-artifact@v7
   with:
     name: test-results-${{ matrix.os }}
 ```
 
-## `if:` Expressions Use `==` Not `===`, and Strings Are Case-Sensitive
+## `if:` Expressions: Single Quotes Only, Comparison Is Case-INsensitive
 
 ```yaml
-# WRONG — this never matches
-if: github.event_name == "Push"
+# WRONG — double quotes are a validation error in expressions
+if: github.event_name == "push"
 
 # RIGHT
 if: github.event_name == 'push'
 ```
 
-`if:` expressions do NOT require `${{ }}` wrapping (they're evaluated as expressions already). Adding `${{ }}` works but is redundant.
+String literals in expressions must use single quotes — double quotes fail workflow validation. String comparison with `==` ignores case (`'Push' == 'push'` is true). The operator is `==`; there is no `===`.
+
+`if:` expressions do NOT require `${{ }}` wrapping (they're evaluated as expressions already). Adding `${{ }}` works but is redundant — except when the expression starts with `!` (reserved in YAML), e.g. `if: ${{ !cancelled() }}`.
+
+## `env:` Does Not Propagate Into Reusable Workflow Calls (`jobs.<job>.uses`)
+
+A reusable workflow is called at the JOB level (`jobs.<job>.uses`), not as a step. Environment variables set at workflow or job level are available to `run:` steps but are NOT passed into the called reusable workflow. Pass values explicitly via `with:` inputs or `secrets:` instead.
+
+## Default Community Health Files (FUNDING.yml, CODEOWNERS, ISSUE_TEMPLATE) Load ONLY From a Repo Named `.github`
+
+Account-wide defaults for community health files come **only** from a public repo named literally `.github` (e.g. `owner/.github`), in its root or a `.github`/`docs` folder. A repo's own file overrides the default.
+
+**Wrong:** Putting `FUNDING.yml` in the username/profile repo (`owner/owner`, the one with the profile README) expecting it to apply org-wide — it does NOT. It only affects that single repo.
 
-## `env:` at Job Level Is Not Inherited by `uses:` (Reusable Workflow) Steps
+**Right:** Create `owner/.github` (must be public) → its `FUNDING.yml` gives every repo without its own a Sponsor button.
 
-Environment variables set at job level are available to `run:` steps but NOT passed into called reusable workflows (`jobs.<job>.uses`). Pass them explicitly via `with:` inputs or `secrets:` instead.
+`FUNDING.yml` keys are platform-specific usernames, not URLs: `buy_me_a_coffee: <user>`, `patreon: <user>`. There is **no** `paypal:` key — PayPal goes under `custom: ['https://paypal.me/<user>']`.

package/templates/skills/claude-code-config/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: claude-code-config
+description: Claude Code configuration gotchas — permission rule syntax and evaluation order, settings hierarchy, plugin install scopes, hook behavior
 ---
 
 # Claude Code Configuration Gotchas
@@ -14,9 +15,11 @@ name: claude-code-config
 **Common mistake**: Writing `Read(/tmp/**)` when you mean absolute path. Correct: `Read(//tmp/**)`.
 
 **Pattern format must match tool signature**:
-- Correct: `Read(//tmp/**)`, `Bash(npm run *)`
+- Correct: `Read(//tmp/**)`, `Bash(npm run:*)`
 - Wrong: `Read(file_path://tmp/**)` — tool name only, no parameter labels
 
+**Bash rules use `:*` for prefix matching**: `Bash(npm run:*)` matches any command starting with `npm run `. `Bash(npm run *)` (space-star) is NOT the prefix syntax and matches unreliably.
+
 ## Wildcard Matching
 
 **Recursive vs Single Level**:
@@ -29,8 +32,8 @@ name: claude-code-config
 
 **Deny always wins**:
 1. Deny rules checked first (block regardless of anything else)
-2. Allow rules checked second (permit if matched)
-3. Ask rules checked last (prompt user)
+2. Ask rules checked second (prompt user if matched)
+3. Allow rules checked last (permit if matched)
 
 **First match wins** within each category.
 
@@ -48,12 +51,8 @@ name: claude-code-config
 
 ## Known Bugs (as of 2026)
 
-**Deny rules not enforced**: Multiple reported issues (GH #13785, #6631, #4467, #6699) where deny patterns in settings.json are ignored. Tool still gets access despite explicit deny.
-
 **Allow rules ignored**: Issue #18160 reports global allow permissions being ignored, requiring manual approval despite being in allowlist.
 
-**Wildcard pattern bugs**: `Bash(command *)` patterns may fail to match commands with flags or tilde expansion.
-
 ## Domain-Specific Rules
 
 **WebFetch requires domain syntax**:
@@ -64,9 +63,7 @@ name: claude-code-config
 
 **Overly broad wildcards**: Starting with `Bash(*)` or `Read(**)` creates security holes. Be specific.
 
-**Forgetting .gitignore**: By default, Claude respects `.gitignore`. If files missing from suggestions, check ignore rules or set `respectGitignore: false`.
-
-**Environment variables in Bash**: Don't persist between commands. Use `CLAUDE_ENV_FILE` or hooks instead.
+**Environment variables in Bash**: Don't persist between commands. Use the `env` map in settings.json or hooks instead.
 
 **Testing permissions**: Use Shift+Tab to switch permission modes mid-session without editing files.
 
@@ -76,16 +73,16 @@ name: claude-code-config
 {
   "permissions": {
     "allow": [
-      "Read(./.env)",              // relative: .env in settings file dir
+      "Read(./config.json)",       // relative: config.json in settings file dir
       "Read(//tmp/**)",            // absolute: all files in /tmp
       "Read(~/.config/**)",        // home: all files in ~/.config
-      "Read(**/.env)",             // recursive: .env anywhere in subtree
-      "Bash(npm run *)",           // command prefix matching
+      "Read(**/config.json)",      // recursive: config.json anywhere in subtree
+      "Bash(npm run:*)",           // command prefix matching (:* suffix)
       "WebFetch(domain:docs.anthropic.com)"  // domain-specific
     ],
     "deny": [
       "Read(**/secrets/**)",       // block entire directory tree
-      "Bash(rm *)"                 // block dangerous commands
+      "Bash(rm:*)"                 // block dangerous commands
     ]
   }
 }
@@ -94,14 +91,14 @@ name: claude-code-config
 ## Debugging Permission Issues
 
 1. Check hierarchy: local > project > user > enterprise
-2. Check deny rules first (they always win)
+2. Check rule order: deny → ask → allow (deny always wins)
 3. Test pattern manually: Does it match the exact tool signature shown in prompt?
-4. Check for known bugs (deny rules may be ignored)
+4. Check for known bugs (allow rules may be ignored — #18160)
 5. Use `claude mcp list` to verify MCP server status if permission involves MCP tool
 
 ## Plugin Install Scope
 
-`claude plugins install <pkg>@<marketplace>` takes `-s, --scope <user|project|local>` (default: `user`).
+`claude plugin install <pkg>@<marketplace>` (singular `plugin`, not `plugins`) takes `-s, --scope <user|project|local>` (default: `user`).
 
 - `user` — global, ~/.claude/plugins/installed_plugins.json with `"scope": "user"`
 - `project` — must run from within the target project dir; registry entry gets `"scope": "project"` + `"projectPath": "<cwd>"`. Plugin activates only when Claude Code runs inside that dir
@@ -109,14 +106,39 @@ name: claude-code-config
 
 Swap scope = uninstall + reinstall (no in-place conversion):
 ```bash
-claude plugins uninstall <pkg>@<mkt> --scope user
-cd /path/to/project && claude plugins install <pkg>@<mkt> --scope project
+claude plugin uninstall <pkg>@<mkt> --scope user
+cd /path/to/project && claude plugin install <pkg>@<mkt> --scope project
 ```
 
 All scopes share the same `~/.claude/plugins/cache/` payload — only the registry entry differs.
 
+## Stop Hook Fires Per Turn, Not on Process Exit
+
+**Wrong assumption**: `Stop` hook = "CLI process is shutting down / session ending".
+**Correct**: `Stop` fires **each time the main agent finishes responding** (end of every turn). One CLI process lifetime can trigger it dozens of times. Docs: *"when Claude finishes responding"* — [docs.claude.com/en/docs/claude-code/hooks](https://docs.claude.com/en/docs/claude-code/hooks).
+
+`SubagentStop` fires when a subagent (Task tool) finishes — separate from the main agent's Stop.
+
+**Practical implication**: Any state registered on `UserPromptSubmit` and released on `Stop` churns every turn. For per-process state (e.g. a background daemon, a lock file, an IPC socket) key by **CLI PID** — `session_id` is wrong because it also changes on `/clear`, `/compact`, or resume within the same process.
+
+```
+UserPromptSubmit → fires before each user turn
+Stop             → fires after each assistant response (not at exit)
+SubagentStop     → fires when a Task-tool subagent completes
+PostToolUse      → fires after each individual tool call within a turn
+```
+
 ## npx Argument Re-parsing Under PreToolUse Hooks
 
 PreToolUse Bash hooks that rewrite commands can mis-parse `npx -y <pkg>@latest <subcmd>`, with `<pkg>@latest` landing as an **npm** subcommand, producing `Unknown command: "<pkg>@latest"`.
 
 Workaround: invoke through a wrapper that bypasses the rewriter (e.g. an explicit `proxy` subcommand of the hook tool, or call the binary directly without `npx -y`). The same `npx` call may succeed via workflow-engine exec while failing via Bash tool — the difference is whether the hook intercepts.
+
+## Multiple Hook Entries for the Same Event Run in Parallel
+
+**Wrong assumption**: Two `PreToolUse` entries in `hooks.json` run in declaration order — first entry first, second entry second.
+**Correct**: All entries for the same event fire **simultaneously**. Declaration order is not execution order.
+
+**Race-condition trap**: If entry A writes a marker file and entry B deletes it, the outcome depends on timing, not position. A fast B (~0 ms) completes before a slow A (~30–50 ms), so A's delete wins even when B is declared last. Symptom: your write appears to have no effect.
+
+**Fix**: One hook entry per event. Inspect stdin JSON inside that single script/command and branch on `tool_name` or other fields to dispatch logic. This guarantees deterministic ordering because it's a single process.