blender-troubleshooting

Purpose

Run a structured 4-phase root-cause analysis when a Blender output (render, export, GLB, preview, or final response) does not match the confirmed intent. Surface the actual cause before proposing any fix. Inspired by the /systematic-debugging skill in Anthropic Superpowers, adapted for Blender / non-Blender-user domain.

This skill does not run Blender. It guides the operator through a disciplined diagnostic procedure that preserves evidence and avoids speculative fixes.

Quick start

• collect the symptom statement, expected outcome, and observed outcome
• run the 4 phases: reproduce → narrow → identify root cause → propose fix
• gate every conclusion on observable evidence
• hand off the fix proposal to the relevant planner / readiness / evidence skill

When to use

• a render came out black, blown out, missing assets, or just "wrong"
• a GLB export is empty, mis-scaled, or fails validation
• the non-Blender-user response sounds wrong (jargon-heavy, contradicted by evidence)
• the runtime smoke test passed but the recipe failed
• intent was clear but result diverges in a specific, reproducible way

When not to use

• the user has not yet stated a clear expected outcome (run intent-to-3d-brief-writer first) → use ../intent-to-3d-brief-writer/SKILL.md (run intent-to-3d-brief-writer first)
• runtime has never been attempted (run runtime-readiness first) → use ../runtime-readiness/SKILL.md (run runtime-readiness first)
• the request is creative iteration ("can we make it more dramatic"), not debugging → use ../blender-brainstorming/SKILL.md (Delegates out-of-scope requests to blender-brainstorming)
• the user wants a one-shot fix without diagnostic discipline → use ../intent-to-3d-brief-writer/SKILL.md (Delegates out-of-scope requests to intent-to-3d-brief-writer)

Trigger phrases

• "the render looks wrong"
• "the GLB doesn't open / looks empty / is wrong scale"
• "the output doesn't match what I asked for"
• "why did it produce X instead of Y?"
• "debug this Blender output"

Prerequisites / readiness

• expected outcome is documented (from intent brief or planner)
• observed outcome has explicit evidence (file path, screenshot, error message, response text)
• ability to ask the operator for evidence; no Blender execution required from this skill

Input schema

Required inputs

• expected outcome (from prior brief or planner)
• observed outcome (file path, screenshot, log, or response text)
• runtime path used (Path 1 host a/b, Path 2, CLI fallback, or text-only)
• last successful step in the workflow (where did it stop matching intent?)

Optional inputs

• prior runtime evidence record (docs/evals/path-X-...md)
• Blender version, MCP host product, add-on identity (helps narrow)
• prior fix attempts that did not work

Assumptions to confirm

• expected outcome is real (not user re-imagining mid-debug)
• observed outcome is reproducible (not transient)
• the operator can pause and gather evidence before any new action

Output schema

Primary output

• root cause statement (one sentence)
• proposed fix with explicit pass criteria

Secondary output

• 4-phase diagnostic record (reproduce / narrow / identify / propose)
• alternative root causes considered and rejected with evidence

Evidence / caveat output

• list of evidence collected per phase
• explicit cannot determine if a phase blocked
• truth state discipline: Runtime (Not Run | Attempted | Produced | Verified | Failed); Artifacts (Not Run | Not Produced | Produced | Verified | Failed, default Not Produced)
• downgrade-only, never upgrade; diagnosis never alters truth states itself (status updates require re-running runtime-readiness or render-export-evidence)

Required laws

• ../../laws/evidence-before-done.md
• ../../laws/non-blender-user-language.md
• ../../laws/no-arbitrary-python-interface.md
• ../../laws/official-runtime-only.md

Official runtime boundary

This skill does not install Blender, run Blender, mutate scenes, render, export, or claim artifacts. It guides diagnosis. Any actual re-run goes through the relevant runtime skill (runtime-readiness, render-export-evidence).

Operating procedure

Phase 1 — Reproduce

1. Confirm the symptom is reproducible. Ask: "if you re-run the same prompt with the same Blender file, does the same wrong output appear?"
2. If yes: lock the inputs (prompt, scene file, Blender version, MCP host, add-on commit).
3. If no (transient): record as "intermittent — needs ≥2 reproductions before continuing".

Phase 2 — Narrow

1. Identify the smallest input set that still reproduces the symptom.
2. Strip away non-essential parts of the prompt or scene.
3. Record what was removed and whether the symptom persisted.

Phase 3 — Identify root cause

1. Compare expected vs. observed at each workflow stage (intent → brief → plan → execution → output → response).
2. Find the first stage where they diverge. That stage is the root-cause boundary.
3. Within that stage, list 2-3 candidate root causes ranked by evidence weight.
4. Pick the highest-evidence candidate. Mark others as "considered, rejected because <reason>".

Phase 4 — Propose fix

1. Write a one-sentence proposed fix targeting the identified root cause.
2. Define explicit pass criteria for the fix (what would prove it worked).
3. Hand off the proposed fix to the relevant skill: planner, readiness checker, evidence skill, or response writer.

Decision tree

• symptom not reproducible → mark intermittent, do not propose fix
• divergence at intent / brief stage → fix is upstream; route to blender-brainstorming or intent-to-3d-brief-writer
• divergence at plan stage → fix is in planning; route to relevant planner (product-hero-scene-planner, camera-composition, lighting-material-plan, character-portrait, environment-shot, interior-scene, or product-grid-scene-planner)
• divergence at execution stage → fix is in runtime setup; route to runtime-readiness, bridge-conflicts, or runtime-path-picker
• divergence at output stage → fix is in export/evidence; route to render-export-evidence, glb-web-handoff, or glb-animation-handoff
• divergence at response stage → fix is in communication/wording; route to plain-language-response

Playbooks

• Playbook A: "Render is black / blown out" — narrow to lighting, materials, or render engine choice; hand off fix to lighting-material-plan or cycles-vs-eevee-decision
• Playbook B: "GLB is empty / mis-scaled" — narrow to scene hierarchy, transforms, or export parameters; hand off fix to glb-web-handoff, mobile-glb-budget, or render-export-evidence
• Playbook C: "Final response uses jargon" — narrow to user-facing wording and tone; hand off fix to plain-language-response
• Playbook D: "Recipe blocked despite smoke pass" — narrow to runtime environment or bridge path conflict; hand off fix to bridge-conflicts

Mode handling

Text-only mode

• diagnostic conversation only, no runtime calls
• runtime status: unchanged from input
• artifact status: unchanged from input
• truth state rule: diagnosis never changes truth states

Runtime-ready mode

• diagnostic analysis only; this skill never re-runs Blender, renders, or mutates scenes
• re-runs must be explicitly handed off to runtime-readiness or render-export-evidence
• truth state rule: diagnosis never upgrades truth states (runtime: Not Run | Attempted | Produced | Verified | Failed; artifacts: Not Run | Not Produced | Produced | Verified | Failed, default Not Produced); downgrade-only if evidence disproves prior state

Blocked runtime mode

• diagnose what is observable from existing evidence
• mark phases blocked when evidence is missing
• truth state rule: truth states remain unchanged or downgrade-only; hand off to runtime-readiness

Validation checklist

• expected outcome documented
• observed outcome documented with evidence
• all 4 phases completed or explicitly marked blocked
• root cause statement is one sentence
• alternative causes considered and rejected with reasons
• proposed fix has explicit pass criteria
• handoff target named
• no Blender execution claimed by this skill
• no jargon in the user-facing summary

Pass / Warn / Fail rubric

Failure handling

• evidence missing: mark phase blocked, do not invent
• two equally plausible causes: rank by evidence weight, mark second as "alternative pending more evidence"
• operator wants to skip phases: explicitly note skipped phases in the diagnostic record

Troubleshooting

• if Phase 1 keeps failing (symptom not reproducible), suggest a fresh runtime smoke test first
• if Phase 3 finds the divergence is at intent / brief, route upstream and stop
• if all 4 phases blocked by missing evidence, hand off to readiness checker before continuing

Best practices

• evidence-first; do not propose fixes without observable evidence
• one root cause statement, not a list
• always name the handoff skill

Good examples

• "Render came out black. Phase 1: reproducible (3/3). Phase 2: narrowed to 'no key light in lighting plan'. Phase 3: root cause = lighting plan missing required key light placement. Phase 4: fix = update lighting plan via lighting-material-plan. Pass criteria: re-render shows visible key-light contribution."

Bad examples

• "Render is black, probably needs more lights and maybe HDRI and also check the camera." (multiple speculative causes, no narrowing, no pass criteria)

User-facing response template

• What you expected
• What we observed (evidence)
• What I tried to reproduce (Phase 1)
• What I narrowed to (Phase 2)
• Most likely cause (Phase 3)
• Proposed fix (Phase 4) — with pass criteria
• Next skill to run

Anti-patterns

• listing many possible causes without ranking by evidence
• proposing fixes before completing Phase 3
• claiming runtime success or failure from this skill (it diagnoses, it doesn't execute)
• using Blender jargon in the operator-facing summary

Cross-skill handoff

• [upstream_reference] If divergence at intent (blender-brainstorming) → ../blender-brainstorming/SKILL.md
• [upstream_reference] If divergence at intent (intent-to-3d-brief-writer) → ../intent-to-3d-brief-writer/SKILL.md
• [conditional] If divergence at planning (camera-composition) → ../camera-composition/SKILL.md
• [conditional] If divergence at planning (lighting-material-plan) → ../lighting-material-plan/SKILL.md
• [alternative] If divergence at planning (character-portrait) → ../character-portrait/SKILL.md
• [alternative] If divergence at planning (environment-shot) → ../environment-shot/SKILL.md
• [alternative] If divergence at planning (interior-scene) → ../interior-scene/SKILL.md
• [alternative] If divergence at planning (product-grid-scene-planner) → ../product-grid-scene-planner/SKILL.md
• [alternative] If divergence at planning (product-hero-scene-planner) → ../product-hero-scene-planner/SKILL.md
• [upstream_reference] If divergence at execution (runtime-readiness) → ../runtime-readiness/SKILL.md
• [fallback] If divergence at execution (bridge-conflicts) → ../bridge-conflicts/SKILL.md
• [upstream_reference] If divergence at execution (runtime-path-picker) → ../runtime-path-picker/SKILL.md
• [conditional] If divergence at output (glb-animation-handoff) → ../glb-animation-handoff/SKILL.md
• [conditional] If divergence at output (glb-web-handoff) → ../glb-web-handoff/SKILL.md
• [conditional] If divergence at output (render-export-evidence) → ../render-export-evidence/SKILL.md
• [conditional] If divergence at response → ../plain-language-response/SKILL.md

Non-goals

• running Blender
• writing fix code
• guessing without evidence
• replacing the runtime evidence skill

References

• Inspired by Anthropic Superpowers /systematic-debugging skill (https://github.com/anthropics/skills)
• BlendOps law: ../../laws/evidence-before-done.md
• BlendOps law: ../../laws/non-blender-user-language.md
• Skill system: ../../docs/skill-system.md