Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.
Swift apple-silicond3dmetaldxmtdxvkfexgame-porting-toolkitgamingmac-gamingmacosmetalmoltenvksteamswiftuivkd3d-protonwhisky-alternativewindows-gameswinewine-wrapper
Add an investigate-issue skill
Gauthier Piarrettea3d32c821600
diff --git a/.claude/skills/investigate-issue/SKILL.md b/.claude/skills/investigate-issue/SKILL.mdnew file mode 100644index 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.mdnew file mode 100644index 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.