---
name: blender-troubleshooting
description: Structured 4-phase root-cause analysis when Blender output looks wrong. Use when render, export, scene, or handoff doesn't match intent and you need disciplined debug, not guesses.
---

# 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)
- runtime has never been attempted (run `official-runtime-readiness-checker` first)
- the request is creative iteration ("can we make it more dramatic"), not debugging
- the user wants a one-shot fix without diagnostic discipline

## 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 `official-runtime-readiness-checker` 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 (`official-runtime-readiness-checker`, `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`, `blender-composition-camera-planner`, `blender-lighting-material-planner`, `character-portrait-scene-planner`, `environment-establishing-shot-planner`, `interior-architectural-scene-planner`, or `product-grid-scene-planner`)
- divergence at execution stage → fix is in runtime setup; route to `official-runtime-readiness-checker`, `runtime-bridge-conflict-resolver`, 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 `non-blender-user-response-writer`

## Playbooks

- Playbook A: "Render is black / blown out" — narrow to lighting, materials, or render engine choice; hand off fix to `blender-lighting-material-planner` 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`, `glb-mobile-performance-budget`, or `render-export-evidence`
- Playbook C: "Final response uses jargon" — narrow to user-facing wording and tone; hand off fix to `non-blender-user-response-writer`
- Playbook D: "Recipe blocked despite smoke pass" — narrow to runtime environment or bridge path conflict; hand off fix to `runtime-bridge-conflict-resolver`

## 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 `official-runtime-readiness-checker` 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 `official-runtime-readiness-checker`

## 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

| Category | Pass | Warn | Fail |
|---|---|---|---|
| Reproduce phase | Symptom locked or marked intermittent | Reproducibility unclear, still proposed fix | Skipped reproduction |
| Narrow phase | Minimum reproducing input found | Partial narrowing | No narrowing attempted |
| Root cause | One-sentence cause + 1-2 rejected alternatives | Cause stated without rejected alternatives | Multiple causes claimed simultaneously |
| Fix proposal | Targeted, with pass criteria + handoff | Targeted, no pass criteria | Speculative, no handoff |

## 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 `blender-lighting-material-planner`. 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

- If divergence at intent → `blender-brainstorming` or `intent-to-3d-brief-writer`
- If divergence at planning → hand off to the relevant planner (`product-hero-scene-planner`, `blender-composition-camera-planner`, `blender-lighting-material-planner`, `character-portrait-scene-planner`, `environment-establishing-shot-planner`, `interior-architectural-scene-planner`, or `product-grid-scene-planner`)
- If divergence at execution → `official-runtime-readiness-checker`, `runtime-bridge-conflict-resolver`, or `runtime-path-picker`
- If divergence at output → `render-export-evidence`, `glb-web-handoff`, or `glb-animation-handoff`
- If divergence at response → `non-blender-user-response-writer`

## 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