How this port is developed

Most of this port’s work is not writing code; it is diagnosis: figuring out which N64 hardware or ABI behavior a piece of unmodified game code is silently relying on, and satisfying it in the port/ layer without touching the game’s logic. A lot of that diagnosis is done with LLM coding agents, and the workflow below is what makes that productive rather than chaotic.

For the project context (the two-model split, the timeline, and an honest assessment of what did and did not work), see dev/agentic-development.md.

It is adapted from Chris Lewis’s write-up “Decompiling a Nintendo 64 Game in 84 Days” (Snowboard Kids, 2026), an AI-assisted decompilation that ran several times faster than its predecessor. That project bit-matches compiler output; this one matches runtime behavior, so the mechanics differ; but the project-structure lessons carry over directly.

Diagnosis is unrestricted; only the fix is constrained

AGENTS.md non-negotiable #2 restricts changing src/game behavior. It has never restricted investigating it. An agent that stops short of naming the exact src/game struct, field, or logic responsible for a bug — because touching that file “feels” off-limits — is doing worse diagnosis than the rules require, not better compliance with them. Several of this port’s hardest, highest-impact bugs (D209, D210, D255) were exactly this shape: a src/game state variable reading wrong, root-caused only by tracing fully into the game file that owned it.

Every investigation should end able to say which of three buckets applies:

Bucket (c) is rare by design — most bugs that look like (c) turn out to be (a) or (b) in disguise — but ruling it in or out requires actually tracing the state to its source, not stopping at the file boundary. “This state lives in src/game” is a reason to keep tracing, not a reason to stop.

1. Every investigation task gets a visible budget

An open-ended tool; for them the permuter, for us “rebuild and run the game and stare at a frame dump”; wrecks throughput when an agent will grind it indefinitely. Giving the agent a deadline it can see lets it trade tool-time against thinking and decide when to give up.

So every investigation brief states:

The budget scales with the project’s maturity. Early bugs are cheap (one-line truncations, off-by-ones) and get a tight cap; once those are gone the survivors are structural (matrix handedness, serialization formats) and get more room.

2. A shared, append-only learnings file

Lewis’s agents recorded generalisable IDO quirks in a learnings file; later agents read it and did better. Our equivalent is porting-notes.md; the recurring N64→PC bug classes, each entry a terse index into the full dev/findings.md log. Every investigation brief links it, and every investigation ends by appending any new generalisable quirk.

The classes it currently tracks:

Two process lessons from the sibling GEVR VR port (same decomp lineage, reference-only survey in scratchpad/GEVR-TRIAGE.md item D — their corpus hit both repeatedly enough to name them): (1) a grep standing in for a read — a site list built by grepping one helper name or spelling misses siblings spelled differently or living in an adjacent file (their own missed-smoke-scissor-site example); treat a grep-built site list as a draft, not a census, until it’s been read against. (2) write the falsifier before the run — state up front what result would kill the hypothesis (“if X survives, hypothesis Y is dead”), not just what would confirm it; this fits the existing budget/findings discipline directly and costs one sentence per brief.

3. Parallelise by file, consolidate often

Lewis ran multiple git worktrees and found the real cost was synchronisation. For parallel investigation agents the same rule applies:

4. Spend the cheap automated pass before spending agent time

Before dispatching an investigation agent:

Then hand the agent the findings, not just the problem.

5. What does not transfer from the decomp workflow

6. Keep PR/git-history noise low

A session produces a lot of small, independently-verifiable units of work; one Dxx row, one docs pass, one mechanical fix. Left unmanaged that turns into a pile of small open PRs that’s harder to review than the work justifies. Rules:

7. The rule-2 sign-off procedure (genuine src/game behavior changes)

Use this only for bucket (c) from the diagnosis framing above — never for the ABI/layout exception (§A1-class fixes need no sign-off, only documentation) and never for anything expressible in port/.

To request sign-off, the write-up must state:

  1. The exact src/game file:line and the specific behavior being proposed for change.
  2. Proof of divergence. Given verified-correct inputs — i.e. every upstream ABI/layout suspect (§A1) and every port-layer suspect has been checked and ruled out, with the ruling-out cited — the byte-identical decomp code still produces behavior that differs from real N64 reference behavior. Name the reference (a capture, documented prior N64 behavior, a cited external source). “It looks wrong” is not proof; “it disagrees with <reference>, verified by <method>” is.
  3. Why the fix cannot be expressed in port/, and why it does not qualify under the ABI/layout exception — the two questions that must be answered “no” before this procedure applies at all.
  4. The proposed fix, scoped as tightly as possible to the one named behavior, plus a same-engine precedent if one exists — the Perfect Dark port is the standing reference; cite the analogous PD change the way docs/dev/WIDESCREEN-FOV-PLAN.md’s “Rule #2 exception framing” section did.

Granting. The user reviews the above and replies with an explicit go-ahead in-thread. There is no implicit or inferred sign-off: silence, “seems reasonable,” a prior similar grant, or approval of a different behavior in the same file do not carry over to a new request.

Recording. Every sign-off gets its own docs/dev/findings.md entry (next Dxx label), tagged RULE-2-SIGNOFF in its status line alongside the normal finding classification, and recording: the request as stated above, the grant (quoted or summarized, with date), and the resulting diff. Add the label to findings-index.csv like any other row, so tools_pc/gen_findings_index.py keeps it discoverable — chat history is not the record of approval; the finding entry is.

Constraints that still apply after approval:

This generalizes the ad hoc precedent in docs/dev/WIDESCREEN-FOV-PLAN.md’s “Rule #2 exception framing” section (a real, already-granted case, kept as historical record) into a reusable process; new requests cite this section rather than re-deriving the case for a process each time.

Investigation-brief template

TASK: <one bug, one subsystem>.
READ FIRST: docs/porting-notes.md; docs/dev/findings.md <specific Dxx entries>.
FILES YOU MAY TOUCH: <disjoint from any other in-flight work>.
KNOWN-GOOD / RULED OUT: <list; do not re-investigate>.
PRE-FLIGHT ATTACHED: <probe output, baseline capture, PD-port pointer>.
BUDGET: <N build->run cycles / ~M min>. On expiry: revert probes, write up with confidence.
CONSTRAINTS: diagnosis may trace as deep into src/game state as the evidence
  needs — name the exact struct/field/logic responsible before concluding
  which bucket applies (see "Diagnosis is unrestricted" above). The FIX is
  still constrained: no src/game behavior changes unless (a) it's an
  ABI/layout-class struct-layout or pointer-width misread — check
  docs/porting-notes.md §A1 first; #ifdef PORT; documented in the finding
  log under §F/D3x — or (b) it's fixable entirely in port/ (no src/game
  touch). A genuine game-logic behavior difference (bucket c) is NOT
  authorized by this brief — stop and write up a rule-2 sign-off request
  per docs/dev-process.md §7 instead of applying it.
VERIFY: <the exact tools_pc/verify.sh (or probe) invocation that proves this done; or, if runtime verification is impossible in this environment, say so and name what a human must run>.
REPORT: (a) root cause + file:line evidence  (b) fix diff, or why not
        (c) probes left in tree  (d) confidence.
        Append any generalisable quirk to docs/porting-notes.md.