ifbars/blender-agent-studio/blender-iterative-refinement

Blender Iterative Refinement

Read the shared execution guidance once per task for autonomous decisions, evidence cadence, and long-task continuity.

Start from a complete candidate produced by the relevant creation workflows. Do not replace their normal construction stages. This skill adds a bounded critic, source repair, identical recheck, and rollback decision.

Freeze the candidate

1. Turn the user-visible request into critical requirements, other visible

requirements, technical gates, and explicit exclusions.

1. Record invariants the repair must preserve: scale, aggregate world bounds,

orientation, names, hierarchy, animation range, materials, approved forms, editable systems, and export behavior.

1. Preserve the candidate source, authored artifact, fresh export import,

metrics, hero view, fixed multiview contact sheet, and required animation or deformation frames. Never overwrite the only copy of the candidate.

Run a separate critic pass

Separate critique from editing: freeze the candidate and judge its evidence before choosing a repair. This can be a distinct self-review pass; it does not require a second agent unless the user or benchmark protocol asks for one.

Open the preserved images with an image-viewing tool. Before editing, write a pass, fail, or unclear ledger for every critical requirement and cite the view or frame that proves the judgment. Names, source code, hierarchy, and metrics cannot make an absent, occluded, or unreadable subject a visual pass.

Treat transmissive enclosures and emissive subjects as a coupled visibility problem. Inspect the actual target render engine and exposure: a valid shader graph is not enough when glass becomes opaque or emission blooms into a white blob. The enclosed subject must retain a traceable silhouette and local color contrast in every required view and animation sample.

Prioritize in this order:

1. missing or unreadable primary subject, required operation, or critical

relationship;

1. failed deterministic gate or aggregate task limit;
2. severe geometry, deformation, contact, material, lighting, or export defect;
3. secondary polish.

For a visible mechanism, trace the whole causal chain across critical frames: driver, connector, attachment, pivot or guide, moving part, and final state. Thin, occluded, or low-contrast connections are unclear, even when numerical endpoint residuals pass.

When available, retain blender_quality_report output for candidate and repair using identical selection and explicit constraints. Then call blender_compare_scenes with the preserved candidate as baseline. Declare required parts and invariants from the frozen contract; use invariantObjects when the repaired part is intentionally allowed to move or change dimensions. Its errors cover the full selected assembly even if object results are paginated. Keep numeric findings and factual diffs separate from the visual ledger: review_required is not a pass, and bounds overlap alone cannot prove a mesh intersection. Compare actual evidence before retaining a repair; no aesthetic score or automatic checkpoint tool is implied.

For character repairs, keep separate ledger rows for hand/thumb construction, shoe footprint/profile, shoulder/underarm continuity, joint deformation, and clothing/accessory attachment. A single connected body or exported action cannot pass these rows. Preserve intended cartoon proportions and simplified hands. Use blender_inspect_attachments for explicit deforming surface pairs where supported. Preserve selectors when topology is unchanged; after topology changes, rebind and visually verify the new patches before rechecking. Keep thresholds and frames fixed, and report that changed bindings require review rather than claiming an identical numerical comparison. Review the worst frame and surrounding views after the weight/geometry repair; a passing centroid distance can still conceal penetration or a visibly detached shoulder.

Repair durable source

For humanoid motion, use the animation workflow's motion review record. Keep contact accuracy, naturalness, first-person framing and third-person readability in separate rows. Preserve the requested action when repairing robotic motion: removing steps and returning to a stiff swivel is not a fix. Compare the same full-speed sequence, contact intervals and blend boundaries; reject a visually worse revision even when its contact residuals improve.

For reference-based character revisions, use the character workflow's likeness refinement protocol. Preserve calibrated body views and head-only snapshots before changing shape. The validation skill's scripts/review_likeness.py rejects changed comparison conditions and reports per-view landmark/proportion deltas; its numerical targets never replace the visual ledger or authorize retaining a regression.

Identify the smallest source-level cause that can address the highest-priority failure. Make one targeted repair, or one tightly coupled repair group, in the durable Python or editable Blender source. Regenerate the authored and exported artifacts; do not hand-patch derived files.

If the primary subject or causal layout is wrong, a narrow cosmetic edit is not sufficient. Rebuild that primary portion before spending effort on polish.

Recheck and decide

Repeat the exact Blender executable, inspector, cameras, frames, render settings, export/import path, and task gates. Compare candidate and repair side by side. Retain the repair only when:

• the targeted failure improves or passes;
• every critical visible requirement passes in actual final evidence;
• no previous hard gate, task limit, or critical requirement regresses;
• aggregate scene.bounds.dimensions, not only the largest mesh, satisfies any

global size limit;

• any deliberate tradeoff was accepted by the user.

Otherwise restore the preserved candidate and report why the repair was rejected. A second pass is valuable only when evidence shows that the retained result is better.

Record the iteration

Write iteration_review.json with the contract, candidate evidence paths, requirement ledger, selected defect, source cause, repair, invariant results, final evidence paths, and decision of retain_repair, retain_candidate, or blocked. Keep creator self-review separate from benchmark judging: do not expose hidden thresholds, condition labels, competing submissions, or judge feedback to the creator.