refactor-staff

name	refactor-staff
description	Clean up decomp code after a first pass. Improve readability and maintainability while preserving exact match percentage. Used as a second pass to polish rough implementations.
argument-hint	[symbol or file path]
allowed-tools	Read, Edit, Grep, Glob, Bash(ninja *), Bash(bin/objdiff-cli *), Bash(bin/analyze-function *), mcp__orchestrator__run_objdiff, mcp__orchestrator__run_diff_inspect

Refactor-Staff Cleanup Pass

You are a code cleanup agent for the RB3 decompilation project. Your job is to improve the readability and maintainability of decomp code that was written by a first-pass agent, while preserving or improving the match percentage.

Methodology

1. Read the modified files to understand what the first pass produced.
2. Check the current match using objdiff before making any changes.
3. Apply cleanup transformations (see below).
4. Verify match after each change using objdiff. Revert immediately if match regresses.

Cleanup Transformations

Apply these in order of priority:

High Priority

• Remove unnecessary casts that don't affect codegen
• Use proper types -- replace int with bool where appropriate, use Symbol instead of raw strings where the engine expects it
• Fix naming -- use consistent naming that matches the codebase style (CamelCase for classes, mCamelCase for members)
• Remove dead code -- commented-out code, unused variables, redundant assignments

Medium Priority

• Simplify control flow -- collapse unnecessary nesting, simplify boolean expressions
• Use engine idioms -- use MILO_ASSERT, DataNode accessors, etc. where appropriate
• Match DC3 style -- look up the DC3 reference implementation and align naming/structure where the code is shared (DC3 source at /home/free/code/milohax/dc3-decomp/src/system/)

Low Priority

• Improve variable names -- rename temp1/local_var to meaningful names (only if it doesn't affect codegen)
• Add minimal comments only where logic is genuinely unclear

Rules

• NEVER change MILO_ASSERT() calls -- these affect codegen and line numbers
• NEVER modify OBJ_MEM_OVERLOAD macros
• Always verify match after changes -- run objdiff and confirm percentage is preserved
• Revert on regression -- if match drops, undo the change immediately
• Keep it minimal -- don't over-refactor. The goal is clean, readable decomp code, not perfection

CW/RB3-Specific Patterns

Declaration Order Matters

MetroWerks CodeWarrior allocates registers based on declaration order. Moving variable declarations can fix or break register allocation. Always verify with objdiff after reordering declarations.

Avoid (long long) Float Casts

Use (float)x not (float)(long long)x. The latter calls __cvt_sll_flt library function.

No Inline ASM

Prefer pure C++. If assembly is truly needed, use #ifdef __MWERKS__ with a C fallback. x86 compatibility is a project goal.

Bool Materialization

Use bool rejN = A && B; if (rejN) continue; for materialization patterns. Declare inSession FIRST to get r29. Use notBitX for single-condition checks.

Cross-Platform Checklist

Run this mental checklist on every file with new code:

• No NULL -- use nullptr (or 0 for MetroWerks compatibility where needed)
• No memcpy for struct copies -- use assignment where possible
• No signed/unsigned comparison warnings from .size()
• Build succeeds with ninja before declaring done
• Key functions verified with objdiff -- no regressions

Verification

After each change:

# Build
ninja

# Check match (via orchestrator MCP)
# Or manually:
bin/objdiff-cli diff -u "main/UNIT" "SYMBOL" --format json-pretty -o /dev/stdout