---
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
- runtime status updated only by re-running readiness or evidence skill

## 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 brainstorming or brief writer
- divergence at plan stage → fix is in scene/composition/lighting/material planner
- divergence at execution stage → fix is in runtime readiness or path setup
- divergence at output stage → fix is in render-export-evidence or GLB handoff
- divergence at response stage → fix is in non-blender-user-response-writer

## Playbooks

- Playbook A: "Render is black / blown out" — narrow to lighting plan or render settings
- Playbook B: "GLB is empty / mis-scaled" — narrow to export plan or GLB handoff
- Playbook C: "Final response uses jargon" — narrow to response writer
- Playbook D: "Recipe blocked despite smoke pass" — narrow to runtime path conflict (route 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

### Runtime-ready mode

- diagnostic plus optional re-run via the relevant runtime skill
- this skill itself never re-runs; it hands off

### Blocked runtime mode

- diagnose what's possible from existing evidence
- mark phases blocked when evidence is missing

## 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 → relevant planner skill
- If divergence at execution → `official-runtime-readiness-checker` or `runtime-bridge-conflict-resolver`
- If divergence at output → `render-export-evidence` or `glb-web-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