debugging-linux-games

# Debugging Linux Games (Research-First) ## Overview Steam-on-Linux problems almost always have a documented community fix. The documented fix is usually a game launch option, an env var, a config tweak, or a known proton-ge / proton-cachyos release with a workaround baked in — NOT a patch to dxvk-nvapi or vkd3d-proton. Diving into shim code without checking first is how 10 hours get spent producing patches that the actual fix renders unnecessary. **Core principle:** Community research first. Code second. Always. **Iron Law:** NO patches, forks, overlays, postFixup drops, or any code changes to the Wine/Proton/DXVK/vkd3d/gamescope stack until the six-source research checklist below has been completed within a 30-minute time-box. If a launch option, env var, config flag, or proton-ge build already solves the problem, that's the answer — even if reading the source feels more satisfying. No exceptions. **Announce at start:** "I'm using debugging-linux-games to research before touching code." ## Rigidity Level LOW FREEDOM — The research phase is mandatory. The 30-minute time-box is mandatory. The "no shims until research is done" gate is mandatory. ## The Six-Source Checklist Time-box: 30 minutes. Stop earlier if a documented fix matches the symptom. | # | Source | What you're looking for | |---|--------|-------------------------| | 1 | **ProtonDB** (`protondb.com/app/<id>`) | Working launch options, known issues, Proton version that works | | 2 | **Steam Community discussions** for the app, Linux/Wine/Proton tags | Fix threads from devs or users — this is where `/WineDetectionEnabled:False` for PRAGMATA was found | | 3 | **Game-specific subreddits + r/linux_gaming** | Recent threads naming the title | | 4 | **GitHub issues** across `ValveSoftware/Proton`, `HansKristian-Work/vkd3d-proton`, `doitsujin/dxvk`, `jp7677/dxvk-nvapi`, `ValveSoftware/gamescope` | Engine-specific bugs and merged workarounds; check both open AND closed | | 5 | **GE-Proton + proton-cachyos release notes** | Per-release "added fix for X" entries with env vars | | 6 | **PCGamingWiki Linux section** for the title | Engine-level fixes, "Wayland-broken" / "needs DXVK_CONFIG" notes | For RE Engine / Capcom titles specifically: check whether `/WineDetectionEnabled:False` is documented as a launch option — Capcom's RE Engine games (MH Wilds, PRAGMATA, RE4R, DD2) gate RT/PT/DLSS-RR behind an internal Wine detection check. ## The Process ### Phase 1: Identify Game + Engine + Stack Before searching, gather: - **Game title + Steam app ID** (the app ID makes ProtonDB / Steam community search precise) - **Engine** (RE Engine, Unreal 4/5, Unity, Source 2, etc.) — engines tend to share fixes - **Stack** (proton version, GPU vendor + arch, compositor, gamescope yes/no, kernel) - **Exact symptom** (full error text or screenshot, not paraphrased) - **What the user already tried** For NixOS + proton-cachyos + Blackwell + niri specifically: most "X is broken in gamescope" reports translate to "use `PROTON_USE_WAYLAND=1` and skip gamescope, then check the title-specific fix." ### Phase 2: Six-Source Research (30 min, time-boxed) Dispatch parallel research: ``` Agent (general-purpose, parallel × 2) description: "ProtonDB + Steam community search for <title>" prompt: | Find the working Linux/Proton configuration for <title> (Steam app ID <id>). Check: - protondb.com/app/<id> — top reports, recommended proton version, launch options listed - steamcommunity.com/app/<id>/discussions — filter for Linux/Wine/Proton - r/linux_gaming and the game's subreddit Report: (a) launch options that consistently work, (b) known issues list with workarounds, (c) any "do not use gamescope" or "use proton-ge X.Y" notes. Under 300 words. Agent (general-purpose, parallel × 2) description: "GitHub issues + PCGamingWiki for <title>/<engine>" prompt: | Search: - github.com/ValveSoftware/Proton issues (open + closed) for "<title>" and "<engine>" - HansKristian-Work/vkd3d-proton, doitsujin/dxvk, jp7677/dxvk-nvapi issues for the same - ValveSoftware/gamescope for engine-specific compat issues - GE-Proton release notes for added fixes naming the game - PCGamingWiki <title> page, Linux section Report: (a) issue numbers + status, (b) any env var or VKD3D_CONFIG/DXVK_HUD workaround, (c) which proton version landed a fix. Under 300 words. ``` While agents run, optionally inspect the local proton log (`PROTON_LOG=1` writes to `~/steam-<id>.log`) for OBVIOUS errors. **Don't form a theory yet** — the research output reframes log lines. ### Phase 3: Apply the Documented Fix If research found a fix: 1. Apply it (launch option in Steam, env var in launch options, etc.) 2. Test it 3. If it works: DONE. Stop. Do not also "fix" the underlying shim. 4. If the fix is wired through nix-config (e.g., add it to `pkgs/proton-gamescope/run.sh` as a default), make the minimal change and commit with a comment citing the source thread / issue. ### Phase 4: Only If Research Is Empty — Then Diagnose Only after all six sources have been checked AND no documented fix exists, escalate to code-level diagnosis: 1. Reproduce with `PROTON_LOG=1` 2. Bisect the stack: try `PROTON_USE_WAYLAND=0/1`, `gamescope on/off`, different proton builds (proton-cachyos vs GE-Proton vs experimental) 3. Form a hypothesis WITH EVIDENCE from logs 4. Verify the hypothesis in the source before patching If you reach this phase, hand off to `gambit:brainstorming` with the bug report and research notes attached. Its research step dispatches the scout for the reproduction command and root cause. ## Critical Rules ### Rules That Have No Exceptions 1. **No shim patches before research** — Research takes 30 minutes; patches take days. 2. **The user wanting "the technical answer" is not permission to skip research** — Confident technical briefs about NVAPI IDs / vkd3d swapchain races / NGX queries are exactly the trap this skill exists to prevent. 3. **If the fix is `/some-cli-flag` or `PROTON_FOO=1`, that's the fix** — Don't also patch the underlying behavior. Game ships with a launch option for a reason. 4. **A "confident technical brief" is evidence of a trap, not evidence of correctness** — When training data confidently names internal function IDs, structure fields, or closed-source behavior, treat that as a flag to check community sources HARDER, not as a green light to start patching. 5. **30-minute research time-box is a floor, not a ceiling** — If 30 minutes turns up nothing, that's signal this might genuinely be a new bug; document and proceed to Phase 4. But don't shortcut research because "I bet it's the swapchain." ### Common Excuses All mean: **STOP. Do the research first.** | Excuse | Reality | |--------|---------| | "I can see from the log it's a vkd3d swapchain race" | Logs after research land differently than logs before research | | "ProtonDB users don't have this specific Blackwell setup" | Issues from any GPU often share a fix; check anyway | | "The fix is obvious — let me just patch the shim" | "Obvious" is exactly the bias this skill exists to counter | | "We already have a fork — just bump it" | If the fork was unnecessary in the first place, bumping it perpetuates the mistake | | "Community research is slow for niche games" | 30 minutes upper bound. If it's truly niche, you'll know fast | | "The user is technical and wants the deep answer" | The deep answer is often "the game ships with a CLI flag for this" | ## Reference: PRAGMATA Anti-Pattern This skill exists because PRAGMATA (Steam app 3357650) was debugged for ~10 hours and produced 4 fork patches: - `dxvk-nvapi-josh`: 5 Blackwell/Streamline NVAPI ID stubs + CUDA SM fix - `vkd3d-proton-josh`: 0×0 ResizeBuffers refusal + maxImageExtent bail-out - `gamescope-patches/win-is-useless-respect-content-override` - `gamescope-patches/scale-by-buffer-when-x11-geom-smaller` Every patch addressed a real bug — but none of them gated the user's goal (RT/PT/DLSS-RR enablement). The actual fix was: - `PROTON_USE_WAYLAND=1` (skip the X11 path that motivated the gamescope patches) - `PROTON_DLSS_UPGRADE=1` + don't hide NVIDIA GPU - `/WineDetectionEnabled:False` as a game launch option All three were findable in 15 minutes via this skill's checklist. None were inventable from first principles. The forks were removed in `nix-config` commit 6251c4c. The branches are preserved on GitHub for historical reference. Do not repeat this pattern. ## Verification Checklist Before reporting a "fix" or making any code change to the Wine/Proton stack: - [ ] Game title + Steam app ID identified - [ ] Engine identified - [ ] All six sources checked (or time-box elapsed) - [ ] Documented fix from community: APPLIED + VERIFIED, or NONE FOUND - [ ] If applying a documented fix: minimal change, commit references the source - [ ] If no documented fix: handed off to `gambit:brainstorming` with the bug report and research notes attached, for its research step to dispatch the scout for the reproduction command and root cause **Can't check all boxes?** Return to Phase 2. ## Integration **This skill calls:** - Two parallel `general-purpose` research agents (Phase 2) - `gambit:brainstorming` (Phase 4, only if research is empty; pass the bug report and research notes so its research step can dispatch the scout for the reproduction command and root cause) **Called by:** - User reports a Steam game on Linux broken - Before any commit that touches a Wine/Proton stack package - Before opening a fork of any Wine/Proton/DXVK/vkd3d/gamescope project