Teaching GameFrame what we learned

2026-10-23, a side session in GameFrame's own repository, written up the next morning.

Halfway through the fight with Wine, the user asked a question about GameFrame itself: was it suggesting anything while we worked? When the work turned to Windows 95, DirectDraw, Watcom or Wine, did anything point to what was already known about them?

The honest answer was no. GameFrame's racing rules had reached this project once, copied into AGENTS.md at setup. Nothing reacted while the work moved through a new era of hardware and a new set of errors. Every wall we hit, we had to find by hand, even where the cause was a classic of its kind.

The user's idea was a know-how layer. It is a taxonomy of failure modes, each tied to the tools that find it and to what was tried. An agent that hits an error asks whether it has been seen before. Either there is a fix, or there is a recorded dead end: "this was tried; here is what was tried; try something new if you have an idea". The user put it as an expert system, or a choose-your-own-adventure in which some paths end, and that is fine.

What was built

A separate session built it in GameFrame's repository while this one carried on with POD:

• Entries, one file each in GameFrame's docs/knowhow/, every one with symptoms, cause, evidence, a status (solved, workaround, dead end, open, or context) and links to the tools, skills and documents that bear on it.
• ./gameframe advise, which finds entries by an error's text, a log piped into it, or a topic. Asked about "nested exception on signal stack", it answers with our open Rosetta entry and all seven attempts.
• A hook, which runs after every failed shell command and names any entry whose signature matches the output. An agent no longer has to think to ask.
• Context entries, which fire on what the work touches rather than on an error: Windows 95 and DirectDraw games, Wine on Apple silicon, Watcom programs, games with a build per 3D card, DOS games, 16-bit Windows.
• In a second round: the hook for Codex, Gemini CLI, Cursor and Copilot as well as Claude Code, an MCP server (./gameframe serve), and winput, GameFrame's version of our Wine input tool.

21 entries came from this project, the session's own notes in docs/gameframe-lessons.md. They run from the Cyrix port probe and the overflowing mode table to the single-instance mutex that made every new run exit at once.

Why it matters for POD

The next agent that runs a 1997 Windows game will get the walls of this one as advice, not as surprises. The know-how also gives each POD session a place to put what it learns. The wrapper, mod and race sessions that ran overnight added their own pitfalls to the lessons file as they went.

How it is known

The layer's tests run in GameFrame (280 pass, the hook's formats for each agent included). It has not yet been tried inside Codex, Gemini CLI, Cursor or Copilot, and winput has not yet run under Wine; both are next.