bit-refactor

What I do

Define the full assess-patch-evaluate work loop for making changes to boardgame_insert_toolkit_lib.3.scad. This skill is loaded at the start of every refactor session and governs the methodology.

When to use me

Load this skill when:

• •Starting a refactor work session on the BIT library
• •Resuming work after a break (context may be stale)
• •Uncertain about the correct workflow for a change

The Work Loop

Every change to the library follows this exact loop. No shortcuts.

ASSESS -> PATCH -> EVALUATE -> UPDATE DOCS -> repeat

Step 1: ASSESS (use @bit-assessor)

Invoke the bit-assessor agent. It will:

1. •Read CLEANUP_PLAN.md to find the next pending task
2. •Read the relevant section of the library source
3. •Produce a patch specification:
   • •Exact task ID from the plan
   • •What to change (old code -> new code, or description of structural change)
   • •Which test files to use for verification
   • •Which render views are relevant
   • •What to look for in the before/after comparison
   • •Risk level (low/medium/high)

The assessor does NOT make changes. It only produces the spec.

Step 2: PATCH (use @bit-patcher)

Invoke the bit-patcher agent with the patch spec from step 1. It will:

1. •Render BEFORE baselines using render_eval.sh
2. •Make the exact code change specified
3. •Run a fast CSG compile check (run_tests.sh --csg-only)
4. •If CSG fails: fix the issue, re-check, document what went wrong
5. •Report what was changed and whether CSG passed

The patcher makes ONE logical change. Never batches multiple tasks.

Step 3: EVALUATE (use @bit-evaluator)

Invoke the bit-evaluator agent. It will:

1. •Render AFTER views matching the BEFORE baselines
2. •Read both before and after PNGs and compare them
3. •For refactors: verify geometry is IDENTICAL (no visible differences)
4. •For bugfixes: verify intended change is present AND nothing else changed
5. •Run broader regression if needed (2-3 key tests across feature areas)
6. •Report: PASS (proceed to commit), FAIL (describe what's wrong), or WARN (needs human review)

If FAIL: the patcher is re-invoked to fix the issue. The evaluator re-runs. If PASS: proceed to step 4.

Step 4: UPDATE DOCS

After every successful change, update ALL of these:

1. •CLEANUP_PLAN.md: Mark task done, update line numbers, add discoveries
2. •AGENTS.md: If the change affects architecture, parameters, or module layout
3. •Agent/skill files: If the workflow itself needs adjustment based on what was learned

This step is NOT optional. A stale plan is worse than no plan.

Step 5: COMMIT

Create a git commit with:

• •One logical change per commit
• •Message format: refactor: <what> or fix: <what> or cleanup: <what>
• •Never mix refactors and bugfixes in one commit

Then return to Step 1 for the next task.

Key Project Paths

Render Commands Quick Reference

# Fast compile check (all tests, ~15s)
./tests/run_tests.sh --csg-only

# Single test with all 7 views
./tests/run_tests.sh test_box_minimal

# Targeted evaluation with before/after naming
./tests/render_eval.sh tests/test_box_minimal.scad --views iso,top --name before
./tests/render_eval.sh tests/test_box_minimal.scad --views iso,top --name after

# Cross-section for internal geometry
./tests/render_eval.sh tests/test_box_minimal.scad --cross-section z,7

# Inline test (no file needed)
./tests/render_eval.sh --inline 'include <boardgame_insert_toolkit_lib.3.scad>;
  data=[["t",[[BOX_SIZE_XYZ,[50,50,20]],
    [BOX_COMPONENT,[[CMP_COMPARTMENT_SIZE_XYZ,[46,46,18]]]]]]];
  MakeAll();'

Evaluation Criteria by Change Type

Anti-Patterns (DO NOT)

• •Do NOT batch multiple tasks into one change
• •Do NOT skip the BEFORE render baseline
• •Do NOT skip updating CLEANUP_PLAN.md
• •Do NOT mix refactors with bugfixes in one commit
• •Do NOT assume a change is safe without rendering
• •Do NOT update line numbers in the plan without verifying them
• •Do NOT skip CSG regression even for "trivial" changes