Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

Add an investigate-issue skill

Gauthier Piarrettea3d32c821600
diff --git a/.claude/skills/investigate-issue/SKILL.md b/.claude/skills/investigate-issue/SKILL.md
new file mode 100644
index 0000000..fbbb371
--- /dev/null
+++ b/.claude/skills/investigate-issue/SKILL.md
@@ -0,0 +1,92 @@
+---
+name: investigate-issue
+description: Investigate a reported Highball bug end to end - reproduce it locally, verify the cause, fix it at the right layer, prove the fix, then reply. Use when looking into a GitHub issue, a user's install or crash report, or unexplained bottle, engine, or recipe behaviour.
+---
+
+# Investigate a reported bug
+
+Work the gates in order. Each exists because skipping it once produced a wrong fix or a
+false claim to a user. Skip a gate only deliberately, and say so.
+
+Environment paths, commands, and known traps: [reference.md](reference.md)
+
+## 1. Read the whole thread first
+
+Read every comment, including your own earlier replies, before forming a theory. Check
+whether the lead you are about to raise was already tried and ruled out in that thread.
+
+## 2. Find the decisive evidence
+
+Identify the one line that separates working from broken. Quote it.
+
+If the report's log cannot distinguish success from failure, that is finding #1: fix the
+diagnostics before chasing the bug. Wine logs end with `# exit=N (…) after Ns`; a log
+without that line predates the fix and cannot tell you the outcome.
+
+## 3. Reproduce locally before theorising
+
+Reproduce the failure on this machine, then confirm the reproduction matches the report
+line for line. A reproduction you cannot match is a different bug.
+
+If it will not reproduce, that is data: name the variable that differs (macOS build, chip,
+engine id, bottle state) and verify it rather than assuming it. Compare exact versions, not
+labels - a CI runner labelled for a major version may be several point releases behind.
+
+## 4. Verify the load-bearing claim yourself
+
+Every fix rests on one factual claim. Test that claim directly before building on it:
+
+- exit codes: run the failing command and read the number, do not infer it
+- env vars and flags: grep the actual shipped binary for the string
+- file contents: hash them against a known-good copy
+
+Research and agents are leads, not evidence. Confirm the claim in this repo, on this engine.
+
+## 5. Try to refute your own hypothesis
+
+Actively look for the datapoint that kills it. Check whether CI, another machine, or
+another user contradicts the pattern. Two datapoints are a coincidence.
+
+State the hypothesis you killed. A dead theory reported early is cheaper than a wrong fix
+shipped late.
+
+## 6. Fix at the right layer
+
+- App and Kit: general mechanisms only - step types, classifiers, gates, diagnostics.
+- highball-db: everything specific to one game, launcher, or vendor.
+
+If the fix needs a game's name in Swift, it is in the wrong layer. Keep a hardcoded
+fallback only when removing it would regress users who cannot reach the new path, and
+write down the condition for removing it later.
+
+## 7. Prove it end to end
+
+Reproduce the broken state, apply the fix, show the failure gone, and show the user's
+actual goal working (the install completes, the game launches). Run the full test suite.
+
+Also test what does *not* work, so the fix ships without folklore attached.
+
+## 8. Report two numbers, never one
+
+These are different questions and often have very different answers:
+
+1. Is the diagnosis correct?
+2. Can the user use the app again after this ships?
+
+Detection is not a cure. A change that turns a silent failure into a clear message is
+worth shipping and still leaves the user stuck. Say so plainly, then go build the cure.
+
+## 9. Ship before saying it is fixed
+
+Release first, so the reply says "update and try" rather than promising a future version.
+
+In the reply: name the cause in plain words, say it is our bug when it is, give the exact
+action to take, and ask for one specific thing if confirmation is still needed. No
+overclaiming - if you have not proven it fixes *their* case, say that.
+
+Leave the issue open until the reporter confirms.
+
+## Writing to users
+
+Plain, human, few dashes, no filler. Short sentences. Say what happened and what to do.
+Skip praise, apologies, and marketing.
diff --git a/.claude/skills/investigate-issue/reference.md b/.claude/skills/investigate-issue/reference.md
new file mode 100644
index 0000000..336e7ed
--- /dev/null
+++ b/.claude/skills/investigate-issue/reference.md
@@ -0,0 +1,78 @@
+# Environment reference
+
+Paths, commands, and traps for investigating a Highball bug.
+
+## Where things live
+
+| What | Path |
+|---|---|
+| App data root | `~/Library/Application Support/Highball/` |
+| Bottles (Wine prefixes) | `.../Highball/bottles/<name>/` |
+| Engines | `.../Highball/engines/<engine-id>/` |
+| Run logs | `.../Highball/logs/<stamp>-<bottle>-<program>.log` |
+| Recipes and game database | sibling checkout `../highball-db/` |
+
+Every run log starts with two `#` lines (engine, bottle, renderer, full argv) and ends with
+`# exit=N (…) after Ns`. Read the last line first.
+
+## Commands
+
+```bash
+swift build && swift test # from the repo root
+.build/debug/highball bottle list
+.build/debug/highball run <bottle> 'C:\path\to\app.exe' --verbose -- <args>
+.build/debug/highball recipe apply <bottle> ../highball-db/recipes/<kind>/<id>.json
+.build/debug/highball bottle kill <bottle> # stop the wineserver before poking a prefix
+```
+
+`highball run` always exits 0. Assert on its output, never on `$?`.
+
+## Smoke tests
+
+Prove a capability in seconds instead of installing something large.
+
+```bash
+# 32-bit Windows support (most installers are 32-bit; fails when syswow64 is unpopulated)
+.build/debug/highball run <bottle> 'C:\windows\syswow64\cmd.exe' --verbose -- /c ver
+
+# 64-bit counterpart, to isolate which half is broken
+.build/debug/highball run <bottle> 'C:\windows\system32\cmd.exe' --verbose -- /c ver
+
+# prefix halves: a healthy win64 prefix has hundreds of files in both
+ls "$B/drive_c/windows/system32" | wc -l
+ls "$B/drive_c/windows/syswow64" | wc -l
+```
+
+Source games accept console commands through Steam, which makes them scriptable:
+`-applaunch <appid> -novid +map <mapname>`.
+
+## Traps
+
+**Stale builds.** After changing a struct in HighballKit, run `swift package clean`. Stale
+incremental builds produce phantom test failures against the old memory layout. A debug
+print that does not appear is the tell.
+
+**msync mismatch.** A bottle whose wineserver was started by the Steam UI pin runs with
+`WINEMSYNC=0`. Any later wine command built from the bottle's normal environment joins that
+server and dies at `msync_init`, silently. Run `bottle kill` first.
+
+**Windows paths in `ps`.** Steam-spawned processes appear with backslash paths. Grep for
+both forms, and exclude your own watcher (`grep -v` the shell) or it matches itself.
+
+**Screenshots.** `screencapture` returns a black frame when the display is locked. Check
+luminance before trusting an image. Capture a single window with `screencapture -o -l <id>`
+rather than the whole screen. Never run two bottle GUI tests at once - windows from every
+bottle share the same `wine` process name.
+
+**Long runs.** Hold the machine awake with `caffeinate -dims` for anything over a few
+minutes; sleep kills background agents and wine sessions mid-test.
+
+**Uninterruptible wine processes.** A wine process wedged in a kernel wait (`UE` in `ps`)
+ignores SIGKILL and clears on its own. It belongs to a dead session and blocks nothing.
+
+## CI
+
+Nightly E2E runs on the two newest hosted macOS images and prints the real product and
+build version it tested (`tested on macOS X (BUILD)`). Read that line before claiming a
+macOS version is covered: image labels lag the point release users are on, and there is no
+hosted runner for the newest macOS. For that window, user reports are the only signal.