zPhysics: 90.0% - zPhysicsBehaviors: 91.1%

.agents/skills/code_style

@@ -0,0 +1 @@
+../../.github/skills/code_style

.agents/skills/execute

@@ -0,0 +1 @@
+../../.github/skills/execute

.agents/skills/ghidra

@@ -0,0 +1 @@
+../../.github/skills/ghidra

.agents/skills/implement

@@ -0,0 +1 @@
+../../.github/skills/implement

.agents/skills/line_lookup

@@ -0,0 +1 @@
+../../.github/skills/line_lookup

.agents/skills/lookup

@@ -0,0 +1 @@
+../../.github/skills/lookup

.agents/skills/refiner

@@ -0,0 +1 @@
+../../.github/skills/refiner

.agents/skills/scaffold

@@ -0,0 +1 @@
+../../.github/skills/scaffold

.claude

@@ -0,0 +1 @@
+.agents

.github/skills/execute/SKILL.md

@@ -11,6 +11,9 @@ the produced C++ compiles to byte-identical object code against the original ret
 
 For each function, "done" means both objdiff and normalized DWARF are exact.
 
+Human review is not a substitute for running `dwarf compare`. Each function should hit
+its own `verify` gate before you treat it as ready to hand off, commit, or move past.
+
 ## Overview
 
 This workflow combines several smaller workflows:
@@ -88,6 +91,10 @@ definition does not yet exist in the project, follow the scaffold workflow in
 `.github/skills/scaffold/SKILL.md` to create the needed header/source definitions
 before moving on.
 
+Treat recovered types here as copied reference data, not as hand-designed headers. Copy
+the GC DWARF type body into the canonical owner header first and preserve its declaration
+order unless PS2 or existing repo-header evidence proves a specific correction.
+
 ## Phase 3: Implement Functions
 
 ### 3a. Get the updated function list
@@ -113,6 +120,9 @@ For each missing or nonmatching function, follow the implementation workflow in
 - **One at a time.** Keep the tree in a coherent state as you work through the list.
 - **Balance new vs fixing.** Don't get stuck on one stubborn function — sometimes
   implementing the next function reveals patterns that make the previous one click.
+- **Recovered types are not freeform.** If a function forces you to add or fix a type,
+  copy the DWARF layout into the owner header first. Do not sketch structs/classes from
+  use sites or reorder declarations just to make the header look nicer.
 - **Mismatch triage:**
   - `@stringBase0` offset mismatches often resolve as more string literals are added
     - If you need to inspect the original string or rodata at a virtual address, use `python tools/elf_lookup.py 0xADDR`
@@ -152,6 +162,10 @@ python tools/decomp-workflow.py verify -u main/Path/To/TU -f FunctionName
 If it fails, follow up with `decomp-workflow.py diff` and `decomp-workflow.py dwarf`
 until both checks pass.
 
+Do not queue up several "probably done" functions and leave the DWARF check for later.
+Close the `verify` gate per function before moving on whenever feasible; otherwise the
+reviewer ends up doing avoidable DWARF triage.
+
 ### 3g. Periodic reassessment
 
 After every few functions, re-run the full status check:
@@ -189,6 +203,8 @@ For any remaining nonmatching functions, make one final pass using the implement
 or refiner workflow with all context accumulated during the session.
 
 Do not report a function as complete unless its per-function `verify` check also passes.
+Do not hand a function to review as "done except maybe DWARF" — either resolve the DWARF
+failure yourself or explicitly call out the blocker and why it remains.
 
 ## Phase 5: Report
 

.github/skills/implement/SKILL.md

@@ -9,6 +9,11 @@ Your goal is to decompile a specific function: writing C++ source that compiles
 
 A function is not done until it is exact in both objdiff and normalized DWARF.
 
+Reviewers should not be spending their time rediscovering DWARF mismatches. Before you
+report progress, ask for review, hand the function off, or switch to another target, you
+must run the per-function verification gate yourself and treat any DWARF failure as your
+next task, not as review debt.
+
 ## Phase 1: Gather Context
 
 Collect data from **all** of these sources in parallel where possible.
@@ -85,6 +90,8 @@ Reference the skill for the usage. It gives info based on the virtual address of
 - If a repo header already exists for the type, include that header instead of introducing a local forward declaration.
 - Preserve the original `class` vs `struct` kind. If the existing header is missing or incomplete, verify the type kind from GC Dwarf and PS2 info before writing a local declaration.
 - Preserve real member names and field types too. Do not introduce `pad`, `unk`, or `field_XXXX` members as placeholders for guessed layout; verify the member list from GC Dwarf / PS2 data and leave a TODO when something is still uncertain.
+- When a type is missing or incomplete, dump the full class/struct body from GC DWARF and paste that as the starting point. Do not reconstruct the layout from one function's field accesses or from guessed semantics.
+- Preserve the dumped declaration order as well as the member order. Do not re-sort methods, group fields by guessed meaning, or otherwise "clean up" the layout unless an existing repo header or PS2 evidence proves a specific correction.
 
 ### 1e. Assembly reference
 
@@ -125,6 +132,8 @@ and assembly:
 
 Utilize the dwarf information that you get from the lookup skill heavily.
 
+For any recovered type you touch while implementing the function, treat the DWARF body as source material to copy, not prose to paraphrase. Start from the dumped layout in the canonical owner header, then make only the minimal verified fixes.
+
 Don't add explanatory comments during implementation unless you need to document a remaining DWARF mismatch.
 
 Don't use any temporary local variables that don't exist in the dwarf.
@@ -156,6 +165,16 @@ python tools/decomp-workflow.py verify -u main/Path/To/TU -f FunctionName
 
 If the build fails, fix compilation errors first.
 
+As soon as you have a compiling draft, run the combined verification gate immediately:
+
+```sh
+python tools/decomp-workflow.py verify -u main/Path/To/TU -f FunctionName
+```
+
+Do this before you spend a long time polishing late instruction mismatches. If `verify`
+already shows a DWARF failure, fix that first so you are not polishing code the reviewer
+will bounce anyway.
+
 ### Check the diff
 
 ```sh
@@ -203,6 +222,17 @@ debug-line owner files for each DWARF `// Range:` block, which makes it much eas
 spot inlines that are coming from the wrong header or owner file. Exact line-number
 agreement is a useful secondary hint, but file ownership is the first thing to check.
 
+Use this as the default loop when the function compiles but `verify` is still failing:
+
+1. Run `verify`.
+2. If DWARF fails, run `dwarf`.
+3. Fix the structural issue the DWARF diff is pointing at first: missing/extra locals,
+   wrong qualifiers or parameter types, wrong inline ownership, wrong helper/header owner,
+   or a source shape that outlined something that should be inlined.
+4. Rebuild and rerun `verify`.
+5. Only return to instruction-by-instruction cleanup once the remaining failures are no
+   longer obvious DWARF-compare issues.
+
 Manual fallback:
 
 After writing your code, you can also run the dwarf dump on the compiled output and then query your output dump with lookup.py to compare your decompiled functions against the originals. Since the address of the function you're working on can keep changing
@@ -233,6 +263,9 @@ Every mismatched instruction is a signal — don't settle for "close enough".
 Reaching 100% instruction matching status is not enough. Stay in the loop until `verify`
 passes, which means the DWARF of the function also matches after normalization.
 
+Do not leave a function in a "review-ready" or "good enough for now" state with a known
+DWARF failure unless you are explicitly blocked and you document that blocker clearly.
+
 ## Phase 5: Report
 
 Summarize:

.github/skills/refiner/SKILL.md

@@ -15,9 +15,25 @@ approaches that were tried before — instead, apply systematic lateral analysis
 - A diff is available (`decomp-diff.py -u <TU> -d <func>`).
 - The "obvious" translation from Ghidra has been attempted.
 - You have been given the current source code and the diff.
+- You have already run the per-function `verify` gate and know whether the remaining work
+  is still structural DWARF cleanup or true late-stage instruction cleanup.
+
+Refiner is not the place to dump unresolved DWARF debt on a reviewer. If `verify` or
+`dwarf` is still showing obvious structural mismatches (missing locals, wrong types,
+wrong inline ownership, wrong helper/header owner), fix those first or drop back to the
+implementer workflow before doing late instruction polish.
 
 ## Phase 1: Read the full diff without collapsing
 
+Before you start a refiner pass, confirm the gate status:
+
+```sh
+python tools/decomp-workflow.py verify -u main/Path/To/TU -f FunctionName
+```
+
+If the combined gate is failing for reasons that are still clearly visible in the DWARF
+diff, address those first instead of treating them as reviewer follow-up.
+
 Preferred shortcut:
 
 ```sh
@@ -151,6 +167,9 @@ DWARF mismatches to watch for:
 - Wrong return type
 - Missing inlined function records (means an inline call was outlined)
 
+If these mismatches are still present, you are not in pure refiner territory yet. Resolve
+them before you ask a reviewer to spend time on the function.
+
 ## Phase 4: Report
 
 Summarize:

.github/skills/scaffold/SKILL.md

@@ -29,7 +29,14 @@ Collect data from **all** of these sources in parallel where possible:
 
 ## Phase 2: Setup class
 
-Copy and cleanup the header that you got from running the `lookup` skill using the `symbols/Dwarf` folder. Fix visibility, function order and vtable related things based on using `lookup` on the PS2 types.
+Copy the header/type body that you got from running the `lookup` skill using the
+`symbols/Dwarf` folder into the canonical owner header first. Do not retype or
+reconstruct the layout from memory, from scattered callsites, or from guessed
+semantics.
+
+Then do the minimum cleanup backed by evidence: fix visibility, function order and
+vtable related things based on using `lookup` on the PS2 types, and clean up duplicated
+inline copies when the DWARF emitted both versions.
 
 For formatting and local cleanup while writing the header, consult
 `.github/skills/code_style/SKILL.md`. Use it for member-comment alignment, declaration
@@ -39,6 +46,9 @@ Preserve the real `class` / `struct` kind while scaffolding. Check existing head
 then use Dwarf plus PS2 visibility / vtable info to decide the type kind. Even temporary
 forward declarations should match the known original kind.
 
+Keep the header prologue in repo order: header guard, `EA_PRAGMA_ONCE_SUPPORTED` block,
+then includes. Do not drop project includes ahead of `#pragma once`.
+
 If the repo already has a header for a type you need, include that header instead of
 adding a new local forward declaration. Only forward-declare when no canonical repo header
 exists yet and you have verified that the ownership is still unresolved.
@@ -47,11 +57,31 @@ Preserve real member names, types, order, and offset comments while scaffolding.
 fill gaps with invented `pad`, `unk`, or `field_XXXX` members for game types; verify the
 layout from Dwarf / PS2 data and leave a TODO over the type if a field is still uncertain.
 
+Preserve the declaration order from the dumped type body as well, not just the member
+order. Do not regroup methods, fields, enums, or helper declarations for readability
+unless an existing repo header or PS2 evidence proves the original owner header used a
+different order.
+
+Keep the `// total size: 0x...` comment above the recovered type declaration. When the
+recovered type is a `class`, keep explicit access sections and prefer putting methods /
+accessors before the member layout block unless existing repo evidence says otherwise.
+
+When a recovered field width is known, prefer explicit-width aliases such as `uint8` /
+`uint16` over raw `unsigned char` / `unsigned short`. Use plain `char` for string or byte
+buffers and `signed char` when the field is a signed 8-bit counter.
+
+If a recovered type repeatedly walks neighbors, boundaries, or in-object offsets, prefer
+small named helpers such as `GetTop`, `GetBot`, `GetNext`, `GetPrev`, or boundary getters
+instead of repeating raw pointer arithmetic at each call site.
+
+When those helpers operate on addresses or byte offsets, prefer `intptr_t` / `uintptr_t`
+or explicit byte-pointer arithmetic instead of plain `int` address parameters.
+
 Only create headers if it's really necessary (the struct doesn't have inlines so you can't determine in which header file it goes and it's thematically very different from the other structs that use it), otherwise put it into the one you determined to be correct.
 
 The dwarf often has duplicated inlines, clean those up according to the order in the PS2 info.
 
-Write a TODO comment over the struct/class if you aren't 100% sure that it belongs to the correct header.
+Write a TODO comment over the struct/class if you aren't 100% sure that it belongs to the correct header, and say why (ownership uncertainty, circular dependency, dwarf caveat, etc.) instead of leaving a bare marker.
 
 ## Phase 3: Add needed files to jumbo file and compile
 

.gitignore

@@ -2,6 +2,12 @@
 .idea/
 .vs/
 
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+
 # Caches
 __pycache__
 .mypy_cache