fix-at-the-boundary

# Fix at the Boundary ## Activation guard Use this skill when a reported bug's root cause is a **pattern** — a function shape, a write sequence, a device/permission check, a duplicated literal, a copy-pasted helper — rather than a fact unique to the one file named in the report. If the bug is genuinely local (a typo, a value that only makes sense for that one app, a one-time data fix), say so explicitly — "this is local to `<file>`, no sweep needed" — and skip the rest of this skill. Don't sweep as theater. ### Do NOT skip the sweep in these situations - "The report only names one file, I'll patch that and move on." A stale-diff write race, a mic-device resolution order, a missing scoped-access check — these are usually copy-pasted everywhere the same operation is implemented. - "I found 3 callers and fixed those, that's probably all." Enumerate every hit from the search *before* editing anything — stopping at the first few you notice is how instances 4–9 survive. - "Grepping the whole repo will take too long." A few `rg` calls take seconds; rediscovering the same fix across four more user reports doesn't. - "This looks like the same bug in an area I don't own, but that's not what I was asked to fix." Still enumerate it — just don't edit it (see below). - "I fixed the shared helper, callers will pick it up automatically." Only true if every sibling actually calls it — confirm with the same search. ## Workflow 1. **Derive the fingerprint from the symptom**, not the file: the exact function/hook name, the anti-pattern shape (read stale state → write without re-checking), a literal string, or an import path. 2. **Search before editing:** ```bash # exact call/hook, whole repo rg -n "computeDiffBase\(|stashLocalDiffBase\(" --type ts -g '!**/node_modules/**' # duplicated literal (device id, action name, config key) rg -n "'design-native-asset'" -g '*.ts' -g '*.tsx' # same shape copy-pasted across template apps rg -n "getUserMedia" templates/*/app templates/*/src 2>/dev/null ``` Widen the pattern (drop args, add `-C 3`, try a sibling term like `diffBase` vs `diff_base`) until confident no caller phrases it slightly differently. 3. **Enumerate every hit before touching any file** — write the list in your response so step 5 is checkable. 4. **Decide where the fix lives.** A shared helper some callers bypass → fix the helper and point bypassers at it. No shared helper and N ≥ 3 duplicate sites → consider extracting one instead of pasting a 4th time. 5. **Apply the fix to every in-scope hit.** ### Ownership boundaries Enumerating isn't editing. A hit inside a path this task's `DO NOT TOUCH` list assigns to another agent gets listed as found-but-out-of-scope and flagged via `spawn_task` or a direct note — never silently edited or silently dropped. See **concurrent-agents**. ## Reporting the sweep Report the full blast radius, not just what you changed: ``` Fixed the stale-diff-base race in: - insert-design-native-asset.ts (as reported) - insert-asset.ts, apply-a11y-fix.ts, generate-design.ts (same pattern) Found but out of scope (owned by another agent this task): apply-visual-edit.ts in templates/design/** — flagged via spawn_task. No other callers of computeDiffBase(). ``` ## Why this exists - "apply-visual-edit.ts has the same stale-diff-base write-race bug that was just fixed in insert-design-native-asset.ts, insert-asset.ts, apply-a11y-fix.ts ... and generate-design.ts" — one defect, 9 files, fixed one report at a time instead of once. - Mic-device resolution was independently fixed in four different Clips surfaces (`useMediaDevices.ts`, `media-capture-constraints.ts`, `offscreen.ts`, `recorder-engine.ts`). - "i want to make sure universally cmd+click works ... can we do a quick sweep of other apps" — the user had to ask for a sweep across 4 templates that should have happened proactively. - "remember - if any other apps like in our core repo templates/ does this wrong, fix that too" — exists only because the first fix didn't already answer it. ## Related Skills - **concurrent-agents** — why an out-of-scope sibling gets flagged, not edited. - **adding-a-feature** — the four-area checklist a proper fix should satisfy.