blendops 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (485) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/LICENSE +21 -0
  3. package/README.md +208 -2
  4. package/bin/blendops.mjs +4 -0
  5. package/bundles/claude-desktop-manual/BLENDOPS_SINGLE_FILE.md +78 -0
  6. package/bundles/claude-desktop-manual/IMPORT_STEPS.md +43 -0
  7. package/bundles/claude-desktop-manual/INSTALL_REPORT_TEMPLATE.md +13 -0
  8. package/bundles/claude-desktop-manual/README.md +70 -0
  9. package/bundles/claude-desktop-manual/SKILL.md +62 -0
  10. package/bundles/claude-desktop-manual/manifest.json +278 -0
  11. package/bundles/claude-desktop-manual/references/evidence-rules.md +13 -0
  12. package/bundles/claude-desktop-manual/references/install-boundary.md +13 -0
  13. package/bundles/claude-desktop-manual/references/laws/evidence-before-done.md +14 -0
  14. package/bundles/claude-desktop-manual/references/laws/no-arbitrary-python-interface.md +12 -0
  15. package/bundles/claude-desktop-manual/references/laws/non-blender-user-language.md +13 -0
  16. package/bundles/claude-desktop-manual/references/laws/official-runtime-only.md +20 -0
  17. package/bundles/claude-desktop-manual/references/packs/product-hero-v0.md +30 -0
  18. package/bundles/claude-desktop-manual/references/runtime-stacks.md +13 -0
  19. package/bundles/claude-desktop-manual/references/skill-map.md +36 -0
  20. package/bundles/claude-desktop-manual/references/skills/acceptance-criteria-builder.md +69 -0
  21. package/bundles/claude-desktop-manual/references/skills/asset-discovery.md +73 -0
  22. package/bundles/claude-desktop-manual/references/skills/asset-fallback-strategy.md +66 -0
  23. package/bundles/claude-desktop-manual/references/skills/asset-library-plan.md +69 -0
  24. package/bundles/claude-desktop-manual/references/skills/asset-license-checker.md +69 -0
  25. package/bundles/claude-desktop-manual/references/skills/asset-style-check.md +69 -0
  26. package/bundles/claude-desktop-manual/references/skills/blender-brainstorming.md +62 -0
  27. package/bundles/claude-desktop-manual/references/skills/blender-recipe-decomposer.md +66 -0
  28. package/bundles/claude-desktop-manual/references/skills/blender-troubleshooting.md +78 -0
  29. package/bundles/claude-desktop-manual/references/skills/blendops-help.md +82 -0
  30. package/bundles/claude-desktop-manual/references/skills/bridge-conflicts.md +68 -0
  31. package/bundles/claude-desktop-manual/references/skills/camera-composition.md +65 -0
  32. package/bundles/claude-desktop-manual/references/skills/character-portrait.md +68 -0
  33. package/bundles/claude-desktop-manual/references/skills/cli-appendix-job-outline.md +62 -0
  34. package/bundles/claude-desktop-manual/references/skills/color-management-decision.md +68 -0
  35. package/bundles/claude-desktop-manual/references/skills/composition-quality-checker.md +71 -0
  36. package/bundles/claude-desktop-manual/references/skills/cycles-vs-eevee-decision.md +65 -0
  37. package/bundles/claude-desktop-manual/references/skills/done-criteria.md +70 -0
  38. package/bundles/claude-desktop-manual/references/skills/environment-shot.md +65 -0
  39. package/bundles/claude-desktop-manual/references/skills/glb-animation-handoff.md +69 -0
  40. package/bundles/claude-desktop-manual/references/skills/glb-web-handoff.md +68 -0
  41. package/bundles/claude-desktop-manual/references/skills/intent-to-3d-brief-writer.md +68 -0
  42. package/bundles/claude-desktop-manual/references/skills/interior-scene.md +73 -0
  43. package/bundles/claude-desktop-manual/references/skills/lighting-material-plan.md +65 -0
  44. package/bundles/claude-desktop-manual/references/skills/lighting-quality-checker.md +70 -0
  45. package/bundles/claude-desktop-manual/references/skills/material-quality-checker.md +71 -0
  46. package/bundles/claude-desktop-manual/references/skills/mobile-glb-budget.md +73 -0
  47. package/bundles/claude-desktop-manual/references/skills/output-format-decision.md +63 -0
  48. package/bundles/claude-desktop-manual/references/skills/pack-prerequisite-checker.md +74 -0
  49. package/bundles/claude-desktop-manual/references/skills/path-one-host-outline.md +66 -0
  50. package/bundles/claude-desktop-manual/references/skills/plain-language-response.md +70 -0
  51. package/bundles/claude-desktop-manual/references/skills/polycount-budget-checker.md +71 -0
  52. package/bundles/claude-desktop-manual/references/skills/pre-handoff-verification.md +76 -0
  53. package/bundles/claude-desktop-manual/references/skills/preview-report.md +62 -0
  54. package/bundles/claude-desktop-manual/references/skills/product-grid-scene-planner.md +72 -0
  55. package/bundles/claude-desktop-manual/references/skills/product-hero-scene-planner.md +68 -0
  56. package/bundles/claude-desktop-manual/references/skills/r3f-component-plan.md +66 -0
  57. package/bundles/claude-desktop-manual/references/skills/recipe-fit-assessor.md +75 -0
  58. package/bundles/claude-desktop-manual/references/skills/render-export-evidence.md +70 -0
  59. package/bundles/claude-desktop-manual/references/skills/resolution-aspect-decision.md +65 -0
  60. package/bundles/claude-desktop-manual/references/skills/runtime-attempt-report.md +67 -0
  61. package/bundles/claude-desktop-manual/references/skills/runtime-path-picker.md +67 -0
  62. package/bundles/claude-desktop-manual/references/skills/runtime-readiness.md +63 -0
  63. package/bundles/claude-desktop-manual/references/skills/runtime-setup.md +63 -0
  64. package/bundles/claude-desktop-manual/references/skills/scene-readiness.md +65 -0
  65. package/bundles/claude-desktop-manual/references/skills/scope-guard.md +62 -0
  66. package/bundles/claude-desktop-manual/references/skills/stage-gates.md +91 -0
  67. package/bundles/claude-desktop-manual/references/skills/workflow-stage-router.md +67 -0
  68. package/bundles/generic-project-local/BLENDOPS.md +71 -0
  69. package/bundles/generic-project-local/INSTALL_REPORT_TEMPLATE.md +52 -0
  70. package/bundles/generic-project-local/README.md +73 -0
  71. package/bundles/generic-project-local/ROLLBACK.md +66 -0
  72. package/bundles/generic-project-local/manifest.json +66 -0
  73. package/bundles/skill-package/README.md +54 -0
  74. package/bundles/skill-package/blendops/LICENSE.txt +21 -0
  75. package/bundles/skill-package/blendops/SKILL.md +50 -0
  76. package/bundles/skill-package/blendops/agents/README.md +61 -0
  77. package/bundles/skill-package/blendops/agents/openai.yaml +4 -0
  78. package/bundles/skill-package/blendops/references/evidence-rules.md +17 -0
  79. package/bundles/skill-package/blendops/references/install-boundary.md +13 -0
  80. package/bundles/skill-package/blendops/references/law-evidence-before-done.md +12 -0
  81. package/bundles/skill-package/blendops/references/law-no-arbitrary-python-interface.md +7 -0
  82. package/bundles/skill-package/blendops/references/law-non-blender-user-language.md +8 -0
  83. package/bundles/skill-package/blendops/references/law-official-runtime-only.md +9 -0
  84. package/bundles/skill-package/blendops/references/pack-product-hero-v0.md +21 -0
  85. package/bundles/skill-package/blendops/references/runtime-stacks.md +13 -0
  86. package/bundles/skill-package/blendops/references/skill-acceptance-criteria-builder.md +51 -0
  87. package/bundles/skill-package/blendops/references/skill-asset-discovery.md +54 -0
  88. package/bundles/skill-package/blendops/references/skill-asset-fallback-strategy.md +48 -0
  89. package/bundles/skill-package/blendops/references/skill-asset-library-plan.md +51 -0
  90. package/bundles/skill-package/blendops/references/skill-asset-license-checker.md +51 -0
  91. package/bundles/skill-package/blendops/references/skill-asset-style-check.md +52 -0
  92. package/bundles/skill-package/blendops/references/skill-blender-brainstorming.md +43 -0
  93. package/bundles/skill-package/blendops/references/skill-blender-recipe-decomposer.md +48 -0
  94. package/bundles/skill-package/blendops/references/skill-blender-troubleshooting.md +59 -0
  95. package/bundles/skill-package/blendops/references/skill-blendops-help.md +62 -0
  96. package/bundles/skill-package/blendops/references/skill-bridge-conflicts.md +48 -0
  97. package/bundles/skill-package/blendops/references/skill-camera-composition.md +48 -0
  98. package/bundles/skill-package/blendops/references/skill-character-portrait.md +50 -0
  99. package/bundles/skill-package/blendops/references/skill-cli-appendix-job-outline.md +44 -0
  100. package/bundles/skill-package/blendops/references/skill-color-management-decision.md +50 -0
  101. package/bundles/skill-package/blendops/references/skill-composition-quality-checker.md +53 -0
  102. package/bundles/skill-package/blendops/references/skill-cycles-vs-eevee-decision.md +47 -0
  103. package/bundles/skill-package/blendops/references/skill-done-criteria.md +53 -0
  104. package/bundles/skill-package/blendops/references/skill-environment-shot.md +47 -0
  105. package/bundles/skill-package/blendops/references/skill-glb-animation-handoff.md +51 -0
  106. package/bundles/skill-package/blendops/references/skill-glb-web-handoff.md +51 -0
  107. package/bundles/skill-package/blendops/references/skill-intent-to-3d-brief-writer.md +50 -0
  108. package/bundles/skill-package/blendops/references/skill-interior-scene.md +54 -0
  109. package/bundles/skill-package/blendops/references/skill-lighting-material-plan.md +48 -0
  110. package/bundles/skill-package/blendops/references/skill-lighting-quality-checker.md +52 -0
  111. package/bundles/skill-package/blendops/references/skill-map.md +32 -0
  112. package/bundles/skill-package/blendops/references/skill-material-quality-checker.md +53 -0
  113. package/bundles/skill-package/blendops/references/skill-mobile-glb-budget.md +55 -0
  114. package/bundles/skill-package/blendops/references/skill-output-format-decision.md +46 -0
  115. package/bundles/skill-package/blendops/references/skill-pack-prerequisite-checker.md +56 -0
  116. package/bundles/skill-package/blendops/references/skill-path-one-host-outline.md +48 -0
  117. package/bundles/skill-package/blendops/references/skill-plain-language-response.md +53 -0
  118. package/bundles/skill-package/blendops/references/skill-polycount-budget-checker.md +53 -0
  119. package/bundles/skill-package/blendops/references/skill-pre-handoff-verification.md +57 -0
  120. package/bundles/skill-package/blendops/references/skill-preview-report.md +45 -0
  121. package/bundles/skill-package/blendops/references/skill-product-grid-scene-planner.md +54 -0
  122. package/bundles/skill-package/blendops/references/skill-product-hero-scene-planner.md +51 -0
  123. package/bundles/skill-package/blendops/references/skill-r3f-component-plan.md +48 -0
  124. package/bundles/skill-package/blendops/references/skill-recipe-fit-assessor.md +57 -0
  125. package/bundles/skill-package/blendops/references/skill-render-export-evidence.md +51 -0
  126. package/bundles/skill-package/blendops/references/skill-resolution-aspect-decision.md +48 -0
  127. package/bundles/skill-package/blendops/references/skill-runtime-attempt-report.md +49 -0
  128. package/bundles/skill-package/blendops/references/skill-runtime-path-picker.md +49 -0
  129. package/bundles/skill-package/blendops/references/skill-runtime-readiness.md +45 -0
  130. package/bundles/skill-package/blendops/references/skill-runtime-setup.md +45 -0
  131. package/bundles/skill-package/blendops/references/skill-scene-readiness.md +48 -0
  132. package/bundles/skill-package/blendops/references/skill-scope-guard.md +44 -0
  133. package/bundles/skill-package/blendops/references/skill-stage-gates.md +73 -0
  134. package/bundles/skill-package/blendops/references/skill-workflow-stage-router.md +49 -0
  135. package/docs/README.md +276 -0
  136. package/docs/examples/glb-web-handoff/README.md +174 -0
  137. package/docs/examples/glb-web-handoff/r3f-glb-viewer.tsx +320 -0
  138. package/docs/examples/glb-web-handoff/threejs-glb-viewer.mjs +709 -0
  139. package/docs/knowledge-and-recipe-catalog.md +236 -0
  140. package/docs/recipes/README.md +27 -0
  141. package/docs/recipes/cyberpunk-shoe-hero.md +97 -0
  142. package/docs/workflows/README.md +14 -0
  143. package/docs/workflows/full-non-blender-user-workflow.md +210 -0
  144. package/docs/workflows/product-hero-workflow.md +92 -0
  145. package/laws/README.md +32 -0
  146. package/laws/evidence-before-done.md +37 -0
  147. package/laws/no-arbitrary-python-interface.md +32 -0
  148. package/laws/non-blender-user-language.md +32 -0
  149. package/laws/official-runtime-only.md +78 -0
  150. package/package.json +103 -4
  151. package/packs/README.md +11 -0
  152. package/packs/product-hero-v0/PACK.md +114 -0
  153. package/registry/catalog-index.json +21344 -0
  154. package/registry/compatibility-matrix.json +533 -0
  155. package/registry/contract-context-fields.json +391 -0
  156. package/registry/knowledge-catalog.json +4648 -0
  157. package/registry/knowledge-sources.json +438 -0
  158. package/registry/recipe-catalog.json +2565 -0
  159. package/registry/runtime-capability-policy.json +525 -0
  160. package/registry/runtime-operations.json +4468 -0
  161. package/registry/skills.json +10231 -0
  162. package/registry/workflow-graph.json +7390 -0
  163. package/schemas/adapter-compatibility-matrix.schema.json +166 -0
  164. package/schemas/contract-context-fields.schema.json +147 -0
  165. package/schemas/execution-plan.schema.json +325 -0
  166. package/schemas/glb-web-handoff-manifest.schema.json +744 -0
  167. package/schemas/knowledge-record.schema.json +460 -0
  168. package/schemas/knowledge-source-registry.schema.json +268 -0
  169. package/schemas/operation-execution-ledger.schema.json +348 -0
  170. package/schemas/recipe-record.schema.json +469 -0
  171. package/schemas/runtime-capability-policy.schema.json +184 -0
  172. package/schemas/runtime-evidence-packet.schema.json +211 -0
  173. package/schemas/runtime-operations.schema.json +535 -0
  174. package/schemas/runtime-qualification-report.schema.json +540 -0
  175. package/schemas/runtime-session.schema.json +350 -0
  176. package/schemas/scene-spec.schema.json +624 -0
  177. package/schemas/skill-contract.schema.json +402 -0
  178. package/schemas/skill-eval.schema.json +509 -0
  179. package/scripts/build-knowledge-catalog.mjs +2376 -0
  180. package/scripts/compile-scene-plan.mjs +1945 -0
  181. package/scripts/export-claude-skills.mjs +634 -0
  182. package/scripts/generate-glb-handoff-report.mjs +2376 -0
  183. package/scripts/inspect-glb.mjs +1627 -0
  184. package/scripts/install-skills.mjs +5443 -0
  185. package/scripts/runtime-orchestrator.mjs +7713 -0
  186. package/scripts/validate-capability-policy.mjs +531 -0
  187. package/scripts/validate-evidence-packet.mjs +256 -0
  188. package/skills/README.md +315 -0
  189. package/skills/_template/SKILL.md +296 -0
  190. package/skills/acceptance-criteria-builder/EVAL.md +25 -0
  191. package/skills/acceptance-criteria-builder/SKILL.md +257 -0
  192. package/skills/acceptance-criteria-builder/contract.json +205 -0
  193. package/skills/acceptance-criteria-builder/references/brief-to-criteria-mapper.md +22 -0
  194. package/skills/acceptance-criteria-builder/references/checklist-patterns.md +22 -0
  195. package/skills/acceptance-criteria-builder/references/evidence-hook-rules.md +19 -0
  196. package/skills/asset-discovery/EVAL.md +81 -0
  197. package/skills/asset-discovery/SKILL.md +252 -0
  198. package/skills/asset-discovery/contract.json +291 -0
  199. package/skills/asset-discovery/references/asset-strategy-decision-tree.md +40 -0
  200. package/skills/asset-discovery/references/budget-reconciliation-patterns.md +54 -0
  201. package/skills/asset-discovery/references/license-confidence-table.md +41 -0
  202. package/skills/asset-fallback-strategy/EVAL.md +34 -0
  203. package/skills/asset-fallback-strategy/SKILL.md +248 -0
  204. package/skills/asset-fallback-strategy/contract.json +190 -0
  205. package/skills/asset-fallback-strategy/references/drop-with-caveat-rules.md +36 -0
  206. package/skills/asset-fallback-strategy/references/fallback-option-types.md +55 -0
  207. package/skills/asset-fallback-strategy/references/scoring-rubric.md +61 -0
  208. package/skills/asset-library-plan/EVAL.md +28 -0
  209. package/skills/asset-library-plan/SKILL.md +263 -0
  210. package/skills/asset-library-plan/contract.json +177 -0
  211. package/skills/asset-library-plan/references/folder-structure-rules.md +63 -0
  212. package/skills/asset-library-plan/references/metadata-schema.md +62 -0
  213. package/skills/asset-library-plan/references/naming-rules.md +51 -0
  214. package/skills/asset-license-checker/EVAL.md +33 -0
  215. package/skills/asset-license-checker/SKILL.md +245 -0
  216. package/skills/asset-license-checker/contract.json +172 -0
  217. package/skills/asset-license-checker/references/attribution-rendering-patterns.md +48 -0
  218. package/skills/asset-license-checker/references/common-license-mapping.md +39 -0
  219. package/skills/asset-license-checker/references/license-source-rules.md +38 -0
  220. package/skills/asset-style-check/EVAL.md +26 -0
  221. package/skills/asset-style-check/SKILL.md +238 -0
  222. package/skills/asset-style-check/contract.json +251 -0
  223. package/skills/asset-style-check/references/drift-classification.md +40 -0
  224. package/skills/asset-style-check/references/intentional-mixed-style.md +39 -0
  225. package/skills/asset-style-check/references/style-axes.md +46 -0
  226. package/skills/blender-brainstorming/EVAL.md +79 -0
  227. package/skills/blender-brainstorming/SKILL.md +228 -0
  228. package/skills/blender-brainstorming/contract.json +115 -0
  229. package/skills/blender-brainstorming/references/alternative-scoping-templates.md +43 -0
  230. package/skills/blender-brainstorming/references/clarification-patterns.md +29 -0
  231. package/skills/blender-brainstorming/references/intent-summary-style-guide.md +25 -0
  232. package/skills/blender-recipe-decomposer/EVAL.md +35 -0
  233. package/skills/blender-recipe-decomposer/SKILL.md +258 -0
  234. package/skills/blender-recipe-decomposer/contract.json +152 -0
  235. package/skills/blender-recipe-decomposer/references/dependency-patterns.md +53 -0
  236. package/skills/blender-recipe-decomposer/references/recipe-grouping-rules.md +58 -0
  237. package/skills/blender-recipe-decomposer/references/recipe-naming-rules.md +44 -0
  238. package/skills/blender-troubleshooting/EVAL.md +78 -0
  239. package/skills/blender-troubleshooting/SKILL.md +263 -0
  240. package/skills/blender-troubleshooting/contract.json +352 -0
  241. package/skills/blender-troubleshooting/references/common-symptom-playbooks.md +51 -0
  242. package/skills/blender-troubleshooting/references/divergence-routing-table.md +23 -0
  243. package/skills/blender-troubleshooting/references/four-phase-template.md +51 -0
  244. package/skills/blendops-help/EVAL.md +67 -0
  245. package/skills/blendops-help/SKILL.md +312 -0
  246. package/skills/blendops-help/contract.json +229 -0
  247. package/skills/blendops-help/references/lifecycle-phases.md +91 -0
  248. package/skills/blendops-help/references/quick-start-prompts.md +65 -0
  249. package/skills/blendops-help/references/routing-decision-tree.md +57 -0
  250. package/skills/bridge-conflicts/EVAL.md +83 -0
  251. package/skills/bridge-conflicts/SKILL.md +246 -0
  252. package/skills/bridge-conflicts/contract.json +145 -0
  253. package/skills/bridge-conflicts/references/bridge-state-matrix-template.md +82 -0
  254. package/skills/bridge-conflicts/references/conflict-playbooks.md +99 -0
  255. package/skills/bridge-conflicts/references/do-not-reminders.md +42 -0
  256. package/skills/camera-composition/EVAL.md +32 -0
  257. package/skills/camera-composition/SKILL.md +196 -0
  258. package/skills/camera-composition/contract.json +180 -0
  259. package/skills/camera-composition/references/camera-presets.md +30 -0
  260. package/skills/camera-composition/references/camera-rubric.md +24 -0
  261. package/skills/camera-composition/references/hero-composition-patterns.md +24 -0
  262. package/skills/camera-composition/references/web-layout-negative-space.md +25 -0
  263. package/skills/character-portrait/EVAL.md +42 -0
  264. package/skills/character-portrait/SKILL.md +245 -0
  265. package/skills/character-portrait/contract.json +205 -0
  266. package/skills/character-portrait/references/portrait-framing-rules.md +39 -0
  267. package/skills/character-portrait/references/portrait-lighting-patterns.md +50 -0
  268. package/skills/character-portrait/references/style-consistency-rules.md +41 -0
  269. package/skills/cli-appendix-job-outline/EVAL.md +26 -0
  270. package/skills/cli-appendix-job-outline/SKILL.md +252 -0
  271. package/skills/cli-appendix-job-outline/contract.json +147 -0
  272. package/skills/cli-appendix-job-outline/references/flag-order-reminders.md +16 -0
  273. package/skills/cli-appendix-job-outline/references/job-type-matrix.md +13 -0
  274. package/skills/cli-appendix-job-outline/references/stateless-limitations.md +12 -0
  275. package/skills/color-management-decision/EVAL.md +28 -0
  276. package/skills/color-management-decision/SKILL.md +254 -0
  277. package/skills/color-management-decision/contract.json +162 -0
  278. package/skills/color-management-decision/references/look-comparison.md +44 -0
  279. package/skills/color-management-decision/references/per-channel-rules.md +49 -0
  280. package/skills/color-management-decision/references/pipeline-mapping.md +47 -0
  281. package/skills/composition-quality-checker/EVAL.md +38 -0
  282. package/skills/composition-quality-checker/SKILL.md +260 -0
  283. package/skills/composition-quality-checker/contract.json +221 -0
  284. package/skills/composition-quality-checker/references/aspect-ratio-rules.md +37 -0
  285. package/skills/composition-quality-checker/references/composition-rules.md +58 -0
  286. package/skills/composition-quality-checker/references/headroom-leadroom-rules.md +46 -0
  287. package/skills/cycles-vs-eevee-decision/EVAL.md +26 -0
  288. package/skills/cycles-vs-eevee-decision/SKILL.md +249 -0
  289. package/skills/cycles-vs-eevee-decision/contract.json +142 -0
  290. package/skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md +39 -0
  291. package/skills/cycles-vs-eevee-decision/references/gpu-device-rules.md +51 -0
  292. package/skills/cycles-vs-eevee-decision/references/samples-by-quality.md +53 -0
  293. package/skills/done-criteria/EVAL.md +33 -0
  294. package/skills/done-criteria/SKILL.md +225 -0
  295. package/skills/done-criteria/contract.json +199 -0
  296. package/skills/done-criteria/references/done-vs-perfect.md +56 -0
  297. package/skills/done-criteria/references/out-of-scope-patterns.md +50 -0
  298. package/skills/done-criteria/references/stop-condition-templates.md +39 -0
  299. package/skills/environment-shot/EVAL.md +44 -0
  300. package/skills/environment-shot/SKILL.md +237 -0
  301. package/skills/environment-shot/contract.json +162 -0
  302. package/skills/environment-shot/references/depth-layering-rules.md +49 -0
  303. package/skills/environment-shot/references/time-and-weather-rules.md +35 -0
  304. package/skills/environment-shot/references/wide-shot-camera-rules.md +51 -0
  305. package/skills/glb-animation-handoff/EVAL.md +39 -0
  306. package/skills/glb-animation-handoff/SKILL.md +271 -0
  307. package/skills/glb-animation-handoff/contract.json +247 -0
  308. package/skills/glb-animation-handoff/references/animation-types.md +36 -0
  309. package/skills/glb-animation-handoff/references/transition-rules.md +55 -0
  310. package/skills/glb-animation-handoff/references/web-stack-caveats.md +40 -0
  311. package/skills/glb-web-handoff/EVAL.md +33 -0
  312. package/skills/glb-web-handoff/SKILL.md +212 -0
  313. package/skills/glb-web-handoff/contract.json +171 -0
  314. package/skills/glb-web-handoff/references/artifact-status-language.md +26 -0
  315. package/skills/glb-web-handoff/references/glb-handoff-checklist.md +30 -0
  316. package/skills/glb-web-handoff/references/performance-caveats.md +26 -0
  317. package/skills/glb-web-handoff/references/threejs-r3f-handoff.md +28 -0
  318. package/skills/intent-to-3d-brief-writer/EVAL.md +82 -0
  319. package/skills/intent-to-3d-brief-writer/SKILL.md +238 -0
  320. package/skills/intent-to-3d-brief-writer/contract.json +195 -0
  321. package/skills/intent-to-3d-brief-writer/references/acceptance-criteria-patterns.md +46 -0
  322. package/skills/intent-to-3d-brief-writer/references/eight-slot-template.md +123 -0
  323. package/skills/intent-to-3d-brief-writer/references/mixed-audience-handling.md +39 -0
  324. package/skills/interior-scene/EVAL.md +44 -0
  325. package/skills/interior-scene/SKILL.md +261 -0
  326. package/skills/interior-scene/contract.json +277 -0
  327. package/skills/interior-scene/references/furniture-layout-rules.md +51 -0
  328. package/skills/interior-scene/references/interior-architecture-rules.md +47 -0
  329. package/skills/interior-scene/references/interior-camera-rules.md +47 -0
  330. package/skills/lighting-material-plan/EVAL.md +32 -0
  331. package/skills/lighting-material-plan/SKILL.md +194 -0
  332. package/skills/lighting-material-plan/contract.json +213 -0
  333. package/skills/lighting-material-plan/references/cyberpunk-lookdev.md +22 -0
  334. package/skills/lighting-material-plan/references/lighting-patterns.md +30 -0
  335. package/skills/lighting-material-plan/references/material-portability.md +25 -0
  336. package/skills/lighting-material-plan/references/reflective-floor-pattern.md +22 -0
  337. package/skills/lighting-material-plan/references/web-material-simplification.md +23 -0
  338. package/skills/lighting-quality-checker/EVAL.md +41 -0
  339. package/skills/lighting-quality-checker/SKILL.md +247 -0
  340. package/skills/lighting-quality-checker/contract.json +187 -0
  341. package/skills/lighting-quality-checker/references/hdri-balance-rules.md +48 -0
  342. package/skills/lighting-quality-checker/references/intensity-ranges.md +73 -0
  343. package/skills/lighting-quality-checker/references/shadow-softness-rules.md +38 -0
  344. package/skills/material-quality-checker/EVAL.md +40 -0
  345. package/skills/material-quality-checker/SKILL.md +261 -0
  346. package/skills/material-quality-checker/contract.json +244 -0
  347. package/skills/material-quality-checker/references/consumer-stack-rules.md +62 -0
  348. package/skills/material-quality-checker/references/pbr-sanity-rules.md +78 -0
  349. package/skills/material-quality-checker/references/texture-budget-rules.md +48 -0
  350. package/skills/mobile-glb-budget/EVAL.md +40 -0
  351. package/skills/mobile-glb-budget/SKILL.md +264 -0
  352. package/skills/mobile-glb-budget/contract.json +309 -0
  353. package/skills/mobile-glb-budget/references/budget-tiers.md +30 -0
  354. package/skills/mobile-glb-budget/references/degradation-plan.md +34 -0
  355. package/skills/mobile-glb-budget/references/violation-rules.md +43 -0
  356. package/skills/output-format-decision/EVAL.md +27 -0
  357. package/skills/output-format-decision/SKILL.md +222 -0
  358. package/skills/output-format-decision/contract.json +179 -0
  359. package/skills/output-format-decision/references/bit-depth-rules.md +56 -0
  360. package/skills/output-format-decision/references/compression-tradeoffs.md +62 -0
  361. package/skills/output-format-decision/references/format-decision-matrix.md +34 -0
  362. package/skills/pack-prerequisite-checker/EVAL.md +26 -0
  363. package/skills/pack-prerequisite-checker/SKILL.md +272 -0
  364. package/skills/pack-prerequisite-checker/contract.json +214 -0
  365. package/skills/pack-prerequisite-checker/references/blocked-start-playbook.md +21 -0
  366. package/skills/pack-prerequisite-checker/references/pack-readiness-template.md +38 -0
  367. package/skills/pack-prerequisite-checker/references/prerequisite-matrix.md +20 -0
  368. package/skills/path-one-host-outline/EVAL.md +26 -0
  369. package/skills/path-one-host-outline/SKILL.md +251 -0
  370. package/skills/path-one-host-outline/contract.json +167 -0
  371. package/skills/path-one-host-outline/references/connector-vs-manual-matrix.md +21 -0
  372. package/skills/path-one-host-outline/references/host-checklist-template.md +35 -0
  373. package/skills/path-one-host-outline/references/lab-addon-reminders.md +12 -0
  374. package/skills/plain-language-response/EVAL.md +33 -0
  375. package/skills/plain-language-response/SKILL.md +194 -0
  376. package/skills/plain-language-response/contract.json +242 -0
  377. package/skills/plain-language-response/references/caveat-language.md +25 -0
  378. package/skills/plain-language-response/references/plain-language-patterns.md +30 -0
  379. package/skills/plain-language-response/references/stakeholder-friendly-examples.md +30 -0
  380. package/skills/plain-language-response/references/status-summary-templates.md +50 -0
  381. package/skills/polycount-budget-checker/EVAL.md +40 -0
  382. package/skills/polycount-budget-checker/SKILL.md +251 -0
  383. package/skills/polycount-budget-checker/contract.json +196 -0
  384. package/skills/polycount-budget-checker/references/instance-counting-rules.md +39 -0
  385. package/skills/polycount-budget-checker/references/per-mesh-rules.md +43 -0
  386. package/skills/polycount-budget-checker/references/topology-hints.md +56 -0
  387. package/skills/pre-handoff-verification/EVAL.md +84 -0
  388. package/skills/pre-handoff-verification/SKILL.md +252 -0
  389. package/skills/pre-handoff-verification/contract.json +295 -0
  390. package/skills/pre-handoff-verification/references/downgrade-rules.md +39 -0
  391. package/skills/pre-handoff-verification/references/seven-point-checklist.md +46 -0
  392. package/skills/pre-handoff-verification/references/text-only-mode-handling.md +36 -0
  393. package/skills/preview-report/EVAL.md +39 -0
  394. package/skills/preview-report/SKILL.md +254 -0
  395. package/skills/preview-report/contract.json +141 -0
  396. package/skills/preview-report/references/handoff-recipients.md +41 -0
  397. package/skills/preview-report/references/report-schema.md +60 -0
  398. package/skills/preview-report/references/truth-label-rules.md +36 -0
  399. package/skills/product-grid-scene-planner/EVAL.md +42 -0
  400. package/skills/product-grid-scene-planner/SKILL.md +246 -0
  401. package/skills/product-grid-scene-planner/contract.json +257 -0
  402. package/skills/product-grid-scene-planner/references/grid-consistency-rules.md +53 -0
  403. package/skills/product-grid-scene-planner/references/grid-layout-rules.md +42 -0
  404. package/skills/product-grid-scene-planner/references/grid-output-naming-rules.md +52 -0
  405. package/skills/product-hero-scene-planner/EVAL.md +33 -0
  406. package/skills/product-hero-scene-planner/SKILL.md +227 -0
  407. package/skills/product-hero-scene-planner/contract.json +228 -0
  408. package/skills/product-hero-scene-planner/references/clarification-patterns.md +24 -0
  409. package/skills/product-hero-scene-planner/references/cyberpunk-shoe-example.md +28 -0
  410. package/skills/product-hero-scene-planner/references/product-hero-playbooks.md +22 -0
  411. package/skills/product-hero-scene-planner/references/scene-plan-schema.md +35 -0
  412. package/skills/r3f-component-plan/EVAL.md +43 -0
  413. package/skills/r3f-component-plan/SKILL.md +290 -0
  414. package/skills/r3f-component-plan/contract.json +171 -0
  415. package/skills/r3f-component-plan/references/component-shape-patterns.md +54 -0
  416. package/skills/r3f-component-plan/references/suspense-placement-rules.md +50 -0
  417. package/skills/r3f-component-plan/references/usegltf-caching-rules.md +53 -0
  418. package/skills/recipe-fit-assessor/EVAL.md +28 -0
  419. package/skills/recipe-fit-assessor/SKILL.md +266 -0
  420. package/skills/recipe-fit-assessor/contract.json +220 -0
  421. package/skills/recipe-fit-assessor/references/recipe-catalog.md +30 -0
  422. package/skills/recipe-fit-assessor/references/scope-gap-rules.md +27 -0
  423. package/skills/recipe-fit-assessor/references/workflow-recommendation-template.md +34 -0
  424. package/skills/render-export-evidence/EVAL.md +86 -0
  425. package/skills/render-export-evidence/SKILL.md +339 -0
  426. package/skills/render-export-evidence/contract.json +206 -0
  427. package/skills/render-export-evidence/references/attempted-vs-failed-rubric.md +75 -0
  428. package/skills/render-export-evidence/references/evidence-record-templates.md +143 -0
  429. package/skills/render-export-evidence/references/truth-label-decision-tree.md +57 -0
  430. package/skills/resolution-aspect-decision/EVAL.md +26 -0
  431. package/skills/resolution-aspect-decision/SKILL.md +246 -0
  432. package/skills/resolution-aspect-decision/contract.json +160 -0
  433. package/skills/resolution-aspect-decision/references/aspect-defaults.md +41 -0
  434. package/skills/resolution-aspect-decision/references/print-vs-screen-rules.md +58 -0
  435. package/skills/resolution-aspect-decision/references/resolution-defaults.md +64 -0
  436. package/skills/runtime-attempt-report/EVAL.md +26 -0
  437. package/skills/runtime-attempt-report/SKILL.md +268 -0
  438. package/skills/runtime-attempt-report/contract.json +176 -0
  439. package/skills/runtime-attempt-report/references/attempt-record-template.md +49 -0
  440. package/skills/runtime-attempt-report/references/triage-next-steps.md +15 -0
  441. package/skills/runtime-attempt-report/references/truth-label-blocks.md +27 -0
  442. package/skills/runtime-path-picker/EVAL.md +26 -0
  443. package/skills/runtime-path-picker/SKILL.md +268 -0
  444. package/skills/runtime-path-picker/contract.json +191 -0
  445. package/skills/runtime-path-picker/references/anti-patterns.md +14 -0
  446. package/skills/runtime-path-picker/references/decision-tree.md +29 -0
  447. package/skills/runtime-path-picker/references/path-constraints-table.md +18 -0
  448. package/skills/runtime-readiness/EVAL.md +33 -0
  449. package/skills/runtime-readiness/SKILL.md +218 -0
  450. package/skills/runtime-readiness/contract.json +190 -0
  451. package/skills/runtime-readiness/references/blocker-report-template.md +28 -0
  452. package/skills/runtime-readiness/references/evidence-examples.md +23 -0
  453. package/skills/runtime-readiness/references/readiness-matrix.md +46 -0
  454. package/skills/runtime-setup/EVAL.md +33 -0
  455. package/skills/runtime-setup/SKILL.md +209 -0
  456. package/skills/runtime-setup/contract.json +171 -0
  457. package/skills/runtime-setup/references/runtime-option-decision-tree.md +28 -0
  458. package/skills/runtime-setup/references/setup-summary-template.md +33 -0
  459. package/skills/runtime-setup/references/source-confidence-labels.md +23 -0
  460. package/skills/scene-readiness/EVAL.md +33 -0
  461. package/skills/scene-readiness/SKILL.md +195 -0
  462. package/skills/scene-readiness/contract.json +198 -0
  463. package/skills/scene-readiness/references/blocker-catalog.md +24 -0
  464. package/skills/scene-readiness/references/not-run-handling.md +22 -0
  465. package/skills/scene-readiness/references/quality-rubric.md +23 -0
  466. package/skills/scene-readiness/references/verdict-language.md +22 -0
  467. package/skills/scope-guard/EVAL.md +33 -0
  468. package/skills/scope-guard/SKILL.md +222 -0
  469. package/skills/scope-guard/contract.json +171 -0
  470. package/skills/scope-guard/references/options-language-template.md +51 -0
  471. package/skills/scope-guard/references/recurring-creep-patterns.md +55 -0
  472. package/skills/scope-guard/references/scope-addition-classification.md +55 -0
  473. package/skills/stage-gates/EVAL.md +40 -0
  474. package/skills/stage-gates/SKILL.md +257 -0
  475. package/skills/stage-gates/contract.json +490 -0
  476. package/skills/stage-gates/references/failed-gate-handling.md +42 -0
  477. package/skills/stage-gates/references/gate-template.md +46 -0
  478. package/skills/stage-gates/references/stage-decomposition-patterns.md +55 -0
  479. package/skills/workflow-stage-router/EVAL.md +25 -0
  480. package/skills/workflow-stage-router/SKILL.md +259 -0
  481. package/skills/workflow-stage-router/contract.json +150 -0
  482. package/skills/workflow-stage-router/references/milestone-model.md +20 -0
  483. package/skills/workflow-stage-router/references/routing-decision-tree.md +32 -0
  484. package/skills/workflow-stage-router/references/stage-handoff-template.md +37 -0
  485. package/skills.sh.json +102 -0
@@ -0,0 +1,263 @@
1
+ ---
2
+ name: blender-troubleshooting
3
+ 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.
4
+ ---
5
+
6
+ # blender-troubleshooting
7
+
8
+ ## Purpose
9
+
10
+ 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.
11
+
12
+ This skill **does not run Blender**. It guides the operator through a disciplined diagnostic procedure that preserves evidence and avoids speculative fixes.
13
+
14
+ ## Quick start
15
+
16
+ - collect the symptom statement, expected outcome, and observed outcome
17
+ - run the 4 phases: reproduce → narrow → identify root cause → propose fix
18
+ - gate every conclusion on observable evidence
19
+ - hand off the fix proposal to the relevant planner / readiness / evidence skill
20
+
21
+ ## When to use
22
+
23
+ - a render came out black, blown out, missing assets, or just "wrong"
24
+ - a GLB export is empty, mis-scaled, or fails validation
25
+ - the non-Blender-user response sounds wrong (jargon-heavy, contradicted by evidence)
26
+ - the runtime smoke test passed but the recipe failed
27
+ - intent was clear but result diverges in a specific, reproducible way
28
+
29
+ ## When not to use
30
+ <!-- blendops:generated:start exclusions -->
31
+ - 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)
32
+ - runtime has never been attempted (run runtime-readiness first) → use `../runtime-readiness/SKILL.md` (run runtime-readiness first)
33
+ - 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)
34
+ - 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)
35
+ <!-- blendops:generated:end exclusions -->
36
+
37
+ ## Trigger phrases
38
+ <!-- blendops:generated:start triggers -->
39
+ - "the render looks wrong"
40
+ - "the GLB doesn't open / looks empty / is wrong scale"
41
+ - "the output doesn't match what I asked for"
42
+ - "why did it produce X instead of Y?"
43
+ - "debug this Blender output"
44
+ <!-- blendops:generated:end triggers -->
45
+
46
+ ## Prerequisites / readiness
47
+
48
+ - expected outcome is documented (from intent brief or planner)
49
+ - observed outcome has explicit evidence (file path, screenshot, error message, response text)
50
+ - ability to ask the operator for evidence; no Blender execution required from this skill
51
+
52
+ ## Input schema
53
+
54
+ ### Required inputs
55
+
56
+ - expected outcome (from prior brief or planner)
57
+ - observed outcome (file path, screenshot, log, or response text)
58
+ - runtime path used (Path 1 host a/b, Path 2, CLI fallback, or text-only)
59
+ - last successful step in the workflow (where did it stop matching intent?)
60
+
61
+ ### Optional inputs
62
+
63
+ - prior runtime evidence record (`docs/evals/path-X-...md`)
64
+ - Blender version, MCP host product, add-on identity (helps narrow)
65
+ - prior fix attempts that did not work
66
+
67
+ ### Assumptions to confirm
68
+
69
+ - expected outcome is real (not user re-imagining mid-debug)
70
+ - observed outcome is reproducible (not transient)
71
+ - the operator can pause and gather evidence before any new action
72
+
73
+ ## Output schema
74
+
75
+ ### Primary output
76
+
77
+ - root cause statement (one sentence)
78
+ - proposed fix with explicit pass criteria
79
+
80
+ ### Secondary output
81
+
82
+ - 4-phase diagnostic record (reproduce / narrow / identify / propose)
83
+ - alternative root causes considered and rejected with evidence
84
+
85
+ ### Evidence / caveat output
86
+
87
+ - list of evidence collected per phase
88
+ - explicit `cannot determine` if a phase blocked
89
+ - truth state discipline: Runtime (`Not Run | Attempted | Produced | Verified | Failed`); Artifacts (`Not Run | Not Produced | Produced | Verified | Failed`, default `Not Produced`)
90
+ - downgrade-only, never upgrade; diagnosis never alters truth states itself (status updates require re-running `runtime-readiness` or `render-export-evidence`)
91
+
92
+ ## Required laws
93
+
94
+ - ../../laws/evidence-before-done.md
95
+ - ../../laws/non-blender-user-language.md
96
+ - ../../laws/no-arbitrary-python-interface.md
97
+ - ../../laws/official-runtime-only.md
98
+
99
+ ## Official runtime boundary
100
+
101
+ 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`).
102
+
103
+ ## Operating procedure
104
+
105
+ ### Phase 1 — Reproduce
106
+
107
+ 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?"
108
+ 2. If yes: lock the inputs (prompt, scene file, Blender version, MCP host, add-on commit).
109
+ 3. If no (transient): record as "intermittent — needs ≥2 reproductions before continuing".
110
+
111
+ ### Phase 2 — Narrow
112
+
113
+ 1. Identify the smallest input set that still reproduces the symptom.
114
+ 2. Strip away non-essential parts of the prompt or scene.
115
+ 3. Record what was removed and whether the symptom persisted.
116
+
117
+ ### Phase 3 — Identify root cause
118
+
119
+ 1. Compare expected vs. observed at each workflow stage (intent → brief → plan → execution → output → response).
120
+ 2. Find the first stage where they diverge. That stage is the root-cause boundary.
121
+ 3. Within that stage, list 2-3 candidate root causes ranked by evidence weight.
122
+ 4. Pick the highest-evidence candidate. Mark others as "considered, rejected because <reason>".
123
+
124
+ ### Phase 4 — Propose fix
125
+
126
+ 1. Write a one-sentence proposed fix targeting the identified root cause.
127
+ 2. Define explicit pass criteria for the fix (what would prove it worked).
128
+ 3. Hand off the proposed fix to the relevant skill: planner, readiness checker, evidence skill, or response writer.
129
+
130
+ ## Decision tree
131
+
132
+ - symptom not reproducible → mark intermittent, do not propose fix
133
+ - divergence at intent / brief stage → fix is upstream; route to `blender-brainstorming` or `intent-to-3d-brief-writer`
134
+ - 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`)
135
+ - divergence at execution stage → fix is in runtime setup; route to `runtime-readiness`, `bridge-conflicts`, or `runtime-path-picker`
136
+ - divergence at output stage → fix is in export/evidence; route to `render-export-evidence`, `glb-web-handoff`, or `glb-animation-handoff`
137
+ - divergence at response stage → fix is in communication/wording; route to `plain-language-response`
138
+
139
+ ## Playbooks
140
+
141
+ - 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`
142
+ - 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`
143
+ - Playbook C: "Final response uses jargon" — narrow to user-facing wording and tone; hand off fix to `plain-language-response`
144
+ - Playbook D: "Recipe blocked despite smoke pass" — narrow to runtime environment or bridge path conflict; hand off fix to `bridge-conflicts`
145
+
146
+ ## Mode handling
147
+
148
+ ### Text-only mode
149
+
150
+ - diagnostic conversation only, no runtime calls
151
+ - runtime status: unchanged from input
152
+ - artifact status: unchanged from input
153
+ - truth state rule: diagnosis never changes truth states
154
+
155
+ ### Runtime-ready mode
156
+
157
+ - diagnostic analysis only; this skill never re-runs Blender, renders, or mutates scenes
158
+ - re-runs must be explicitly handed off to `runtime-readiness` or `render-export-evidence`
159
+ - 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
160
+
161
+ ### Blocked runtime mode
162
+
163
+ - diagnose what is observable from existing evidence
164
+ - mark phases blocked when evidence is missing
165
+ - truth state rule: truth states remain unchanged or downgrade-only; hand off to `runtime-readiness`
166
+
167
+ ## Validation checklist
168
+
169
+ - [ ] expected outcome documented
170
+ - [ ] observed outcome documented with evidence
171
+ - [ ] all 4 phases completed or explicitly marked blocked
172
+ - [ ] root cause statement is one sentence
173
+ - [ ] alternative causes considered and rejected with reasons
174
+ - [ ] proposed fix has explicit pass criteria
175
+ - [ ] handoff target named
176
+ - [ ] no Blender execution claimed by this skill
177
+ - [ ] no jargon in the user-facing summary
178
+
179
+ ## Pass / Warn / Fail rubric
180
+
181
+ | Category | Pass | Warn | Fail |
182
+ |---|---|---|---|
183
+ | Reproduce phase | Symptom locked or marked intermittent | Reproducibility unclear, still proposed fix | Skipped reproduction |
184
+ | Narrow phase | Minimum reproducing input found | Partial narrowing | No narrowing attempted |
185
+ | Root cause | One-sentence cause + 1-2 rejected alternatives | Cause stated without rejected alternatives | Multiple causes claimed simultaneously |
186
+ | Fix proposal | Targeted, with pass criteria + handoff | Targeted, no pass criteria | Speculative, no handoff |
187
+
188
+ ## Failure handling
189
+
190
+ - evidence missing: mark phase blocked, do not invent
191
+ - two equally plausible causes: rank by evidence weight, mark second as "alternative pending more evidence"
192
+ - operator wants to skip phases: explicitly note skipped phases in the diagnostic record
193
+
194
+ ## Troubleshooting
195
+
196
+ - if Phase 1 keeps failing (symptom not reproducible), suggest a fresh runtime smoke test first
197
+ - if Phase 3 finds the divergence is at intent / brief, route upstream and stop
198
+ - if all 4 phases blocked by missing evidence, hand off to readiness checker before continuing
199
+
200
+ ## Best practices
201
+
202
+ - evidence-first; do not propose fixes without observable evidence
203
+ - one root cause statement, not a list
204
+ - always name the handoff skill
205
+
206
+ ## Good examples
207
+
208
+ - "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."
209
+
210
+ ## Bad examples
211
+
212
+ - "Render is black, probably needs more lights and maybe HDRI and also check the camera." (multiple speculative causes, no narrowing, no pass criteria)
213
+
214
+ ## User-facing response template
215
+
216
+ - What you expected
217
+ - What we observed (evidence)
218
+ - What I tried to reproduce (Phase 1)
219
+ - What I narrowed to (Phase 2)
220
+ - Most likely cause (Phase 3)
221
+ - Proposed fix (Phase 4) — with pass criteria
222
+ - Next skill to run
223
+
224
+ ## Anti-patterns
225
+
226
+ - listing many possible causes without ranking by evidence
227
+ - proposing fixes before completing Phase 3
228
+ - claiming runtime success or failure from this skill (it diagnoses, it doesn't execute)
229
+ - using Blender jargon in the operator-facing summary
230
+
231
+ ## Cross-skill handoff
232
+ <!-- blendops:generated:start handoffs -->
233
+ - [upstream_reference] If divergence at intent (blender-brainstorming) → `../blender-brainstorming/SKILL.md`
234
+ - [upstream_reference] If divergence at intent (intent-to-3d-brief-writer) → `../intent-to-3d-brief-writer/SKILL.md`
235
+ - [conditional] If divergence at planning (camera-composition) → `../camera-composition/SKILL.md`
236
+ - [conditional] If divergence at planning (lighting-material-plan) → `../lighting-material-plan/SKILL.md`
237
+ - [alternative] If divergence at planning (character-portrait) → `../character-portrait/SKILL.md`
238
+ - [alternative] If divergence at planning (environment-shot) → `../environment-shot/SKILL.md`
239
+ - [alternative] If divergence at planning (interior-scene) → `../interior-scene/SKILL.md`
240
+ - [alternative] If divergence at planning (product-grid-scene-planner) → `../product-grid-scene-planner/SKILL.md`
241
+ - [alternative] If divergence at planning (product-hero-scene-planner) → `../product-hero-scene-planner/SKILL.md`
242
+ - [upstream_reference] If divergence at execution (runtime-readiness) → `../runtime-readiness/SKILL.md`
243
+ - [fallback] If divergence at execution (bridge-conflicts) → `../bridge-conflicts/SKILL.md`
244
+ - [upstream_reference] If divergence at execution (runtime-path-picker) → `../runtime-path-picker/SKILL.md`
245
+ - [conditional] If divergence at output (glb-animation-handoff) → `../glb-animation-handoff/SKILL.md`
246
+ - [conditional] If divergence at output (glb-web-handoff) → `../glb-web-handoff/SKILL.md`
247
+ - [conditional] If divergence at output (render-export-evidence) → `../render-export-evidence/SKILL.md`
248
+ - [conditional] If divergence at response → `../plain-language-response/SKILL.md`
249
+ <!-- blendops:generated:end handoffs -->
250
+
251
+ ## Non-goals
252
+
253
+ - running Blender
254
+ - writing fix code
255
+ - guessing without evidence
256
+ - replacing the runtime evidence skill
257
+
258
+ ## References
259
+
260
+ - Inspired by Anthropic Superpowers `/systematic-debugging` skill (https://github.com/anthropics/skills)
261
+ - BlendOps law: ../../laws/evidence-before-done.md
262
+ - BlendOps law: ../../laws/non-blender-user-language.md
263
+ - Skill system: ../../docs/skill-system.md
@@ -0,0 +1,352 @@
1
+ {
2
+ "$schema": "../../schemas/skill-contract.schema.json",
3
+ "id": "blender-troubleshooting",
4
+ "version": "1.0.0",
5
+ "category": "runtime-and-execution",
6
+ "role": "scene-and-runtime-failure-diagnostician",
7
+ "purpose": "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.",
8
+ "capabilityTier": "L0",
9
+ "triggers": [
10
+ "the render looks wrong",
11
+ "the GLB doesn't open / looks empty / is wrong scale",
12
+ "the output doesn't match what I asked for",
13
+ "why did it produce X instead of Y?",
14
+ "debug this Blender output"
15
+ ],
16
+ "exclusions": [
17
+ {
18
+ "condition": "the user has not yet stated a clear expected outcome (run intent-to-3d-brief-writer first)",
19
+ "delegateTo": "intent-to-3d-brief-writer",
20
+ "reason": "run intent-to-3d-brief-writer first"
21
+ },
22
+ {
23
+ "condition": "runtime has never been attempted (run runtime-readiness first)",
24
+ "delegateTo": "runtime-readiness",
25
+ "reason": "run runtime-readiness first"
26
+ },
27
+ {
28
+ "condition": "the request is creative iteration (\"can we make it more dramatic\"), not debugging",
29
+ "delegateTo": "blender-brainstorming",
30
+ "reason": "Delegates out-of-scope requests to blender-brainstorming"
31
+ },
32
+ {
33
+ "condition": "the user wants a one-shot fix without diagnostic discipline",
34
+ "delegateTo": "intent-to-3d-brief-writer",
35
+ "reason": "Delegates out-of-scope requests to intent-to-3d-brief-writer"
36
+ }
37
+ ],
38
+ "inputs": {
39
+ "required": [
40
+ {
41
+ "name": "observed_symptom_or_error",
42
+ "type": "string",
43
+ "description": "Observed render defect, broken GLB export, scale mismatch, or MCP execution failure"
44
+ },
45
+ {
46
+ "name": "active_workflow_context",
47
+ "type": "object",
48
+ "description": "Current scene plan, runtime path, and recent actions preceding the failure"
49
+ }
50
+ ],
51
+ "optional": [
52
+ {
53
+ "name": "runtime_attempt_notes",
54
+ "type": "string",
55
+ "description": "Optional error output or attempt timeline from runtime-attempt-report"
56
+ }
57
+ ]
58
+ },
59
+ "outputs": {
60
+ "primary": [
61
+ "root_cause_classification",
62
+ "minimal_remediation_plan",
63
+ "reverification_target_skill"
64
+ ],
65
+ "truthStatePolicy": {
66
+ "runtimeDefault": "Not Run",
67
+ "artifactDefault": "Not Produced",
68
+ "mutationRule": "downgrade_only"
69
+ }
70
+ },
71
+ "handoffs": [
72
+ {
73
+ "target": "blender-brainstorming",
74
+ "type": "upstream_reference",
75
+ "label": "If divergence at intent (blender-brainstorming)",
76
+ "when": {
77
+ "all": [
78
+ {
79
+ "field": "goal.clarity",
80
+ "operator": "equals",
81
+ "value": "ambiguous_or_mixed"
82
+ }
83
+ ]
84
+ }
85
+ },
86
+ {
87
+ "target": "intent-to-3d-brief-writer",
88
+ "type": "upstream_reference",
89
+ "label": "If divergence at intent (intent-to-3d-brief-writer)",
90
+ "when": {
91
+ "all": [
92
+ {
93
+ "field": "goal.clarity",
94
+ "operator": "equals",
95
+ "value": "clear"
96
+ },
97
+ {
98
+ "field": "brief.locked",
99
+ "operator": "equals",
100
+ "value": false
101
+ }
102
+ ]
103
+ }
104
+ },
105
+ {
106
+ "target": "camera-composition",
107
+ "type": "conditional",
108
+ "label": "If divergence at planning (camera-composition)",
109
+ "when": {
110
+ "all": [
111
+ {
112
+ "field": "brief.locked",
113
+ "operator": "equals",
114
+ "value": true
115
+ },
116
+ {
117
+ "field": "stage.current",
118
+ "operator": "equals",
119
+ "value": "camera_planning"
120
+ }
121
+ ]
122
+ }
123
+ },
124
+ {
125
+ "target": "lighting-material-plan",
126
+ "type": "conditional",
127
+ "label": "If divergence at planning (lighting-material-plan)",
128
+ "when": {
129
+ "all": [
130
+ {
131
+ "field": "brief.locked",
132
+ "operator": "equals",
133
+ "value": true
134
+ },
135
+ {
136
+ "field": "stage.current",
137
+ "operator": "equals",
138
+ "value": "lookdev_planning"
139
+ }
140
+ ]
141
+ }
142
+ },
143
+ {
144
+ "target": "character-portrait",
145
+ "type": "alternative",
146
+ "label": "If divergence at planning (character-portrait)",
147
+ "when": {
148
+ "all": [
149
+ {
150
+ "field": "brief.locked",
151
+ "operator": "equals",
152
+ "value": true
153
+ },
154
+ {
155
+ "field": "recipe.domain",
156
+ "operator": "equals",
157
+ "value": "character_portrait"
158
+ }
159
+ ]
160
+ }
161
+ },
162
+ {
163
+ "target": "environment-shot",
164
+ "type": "alternative",
165
+ "label": "If divergence at planning (environment-shot)",
166
+ "when": {
167
+ "all": [
168
+ {
169
+ "field": "brief.locked",
170
+ "operator": "equals",
171
+ "value": true
172
+ },
173
+ {
174
+ "field": "recipe.domain",
175
+ "operator": "equals",
176
+ "value": "environment_shot"
177
+ }
178
+ ]
179
+ }
180
+ },
181
+ {
182
+ "target": "interior-scene",
183
+ "type": "alternative",
184
+ "label": "If divergence at planning (interior-scene)",
185
+ "when": {
186
+ "all": [
187
+ {
188
+ "field": "brief.locked",
189
+ "operator": "equals",
190
+ "value": true
191
+ },
192
+ {
193
+ "field": "recipe.domain",
194
+ "operator": "equals",
195
+ "value": "interior_archviz"
196
+ }
197
+ ]
198
+ }
199
+ },
200
+ {
201
+ "target": "product-grid-scene-planner",
202
+ "type": "alternative",
203
+ "label": "If divergence at planning (product-grid-scene-planner)",
204
+ "when": {
205
+ "all": [
206
+ {
207
+ "field": "brief.locked",
208
+ "operator": "equals",
209
+ "value": true
210
+ },
211
+ {
212
+ "field": "recipe.domain",
213
+ "operator": "equals",
214
+ "value": "product_grid"
215
+ }
216
+ ]
217
+ }
218
+ },
219
+ {
220
+ "target": "product-hero-scene-planner",
221
+ "type": "alternative",
222
+ "label": "If divergence at planning (product-hero-scene-planner)",
223
+ "when": {
224
+ "all": [
225
+ {
226
+ "field": "brief.locked",
227
+ "operator": "equals",
228
+ "value": true
229
+ },
230
+ {
231
+ "field": "recipe.domain",
232
+ "operator": "equals",
233
+ "value": "product_hero"
234
+ }
235
+ ]
236
+ }
237
+ },
238
+ {
239
+ "target": "runtime-readiness",
240
+ "type": "upstream_reference",
241
+ "label": "If divergence at execution (runtime-readiness)",
242
+ "when": {
243
+ "all": [
244
+ {
245
+ "field": "runtime.path",
246
+ "operator": "not_equals",
247
+ "value": "unselected"
248
+ },
249
+ {
250
+ "field": "runtime.verifiedReady",
251
+ "operator": "equals",
252
+ "value": false
253
+ }
254
+ ]
255
+ }
256
+ },
257
+ {
258
+ "target": "bridge-conflicts",
259
+ "type": "fallback",
260
+ "label": "If divergence at execution (bridge-conflicts)",
261
+ "when": {
262
+ "all": [
263
+ {
264
+ "field": "runtime.conflictDetected",
265
+ "operator": "equals",
266
+ "value": true
267
+ }
268
+ ]
269
+ }
270
+ },
271
+ {
272
+ "target": "runtime-path-picker",
273
+ "type": "upstream_reference",
274
+ "label": "If divergence at execution (runtime-path-picker)",
275
+ "when": {
276
+ "all": [
277
+ {
278
+ "field": "runtime.path",
279
+ "operator": "equals",
280
+ "value": "unselected"
281
+ }
282
+ ]
283
+ }
284
+ },
285
+ {
286
+ "target": "glb-animation-handoff",
287
+ "type": "conditional",
288
+ "label": "If divergence at output (glb-animation-handoff)",
289
+ "when": {
290
+ "all": [
291
+ {
292
+ "field": "artifact.hasAnimation",
293
+ "operator": "equals",
294
+ "value": true
295
+ },
296
+ {
297
+ "field": "stage.current",
298
+ "operator": "equals",
299
+ "value": "animation_handoff"
300
+ }
301
+ ]
302
+ }
303
+ },
304
+ {
305
+ "target": "glb-web-handoff",
306
+ "type": "conditional",
307
+ "label": "If divergence at output (glb-web-handoff)",
308
+ "when": {
309
+ "all": [
310
+ {
311
+ "field": "artifact.type",
312
+ "operator": "equals",
313
+ "value": "glb"
314
+ },
315
+ {
316
+ "field": "handoff.consumerStack",
317
+ "operator": "equals",
318
+ "value": "web_glb"
319
+ }
320
+ ]
321
+ }
322
+ },
323
+ {
324
+ "target": "render-export-evidence",
325
+ "type": "conditional",
326
+ "label": "If divergence at output (render-export-evidence)",
327
+ "when": {
328
+ "all": [
329
+ {
330
+ "field": "stage.current",
331
+ "operator": "equals",
332
+ "value": "post_execution_audit"
333
+ }
334
+ ]
335
+ }
336
+ },
337
+ {
338
+ "target": "plain-language-response",
339
+ "type": "conditional",
340
+ "label": "If divergence at response",
341
+ "when": {
342
+ "all": [
343
+ {
344
+ "field": "stage.current",
345
+ "operator": "equals",
346
+ "value": "final_communication"
347
+ }
348
+ ]
349
+ }
350
+ }
351
+ ]
352
+ }
@@ -0,0 +1,51 @@
1
+ # Common Symptom Playbooks
2
+
3
+ Pre-canned diagnostic patterns for the 5 most common Blender output divergences. Use these when Phase 1 reproduction is locked.
4
+
5
+ ## Playbook 1: "Render came out fully black"
6
+
7
+ - Phase 2 narrow: strip every prompt detail except subject + camera. Re-render.
8
+ - Phase 3 likely root causes (rank by evidence):
9
+ 1. Lighting plan missing key light.
10
+ 2. Camera occluded by hidden geometry.
11
+ 3. World HDRI not enabled in render settings.
12
+ 4. Render engine mismatch (Eevee vs Cycles render-time vs viewport).
13
+ - Phase 4 fix: route to `lighting-material-plan`. Pass criteria: re-render shows visible key-light contribution.
14
+
15
+ ## Playbook 2: "GLB is empty / mis-scaled / fails web import"
16
+
17
+ - Phase 2 narrow: open the GLB in [gltf.report](https://gltf.report) or `gltf-validator`. Check geometry, scale, materials.
18
+ - Phase 3 likely root causes:
19
+ 1. Export plan filtered out the hero geometry (selection-only flag).
20
+ 2. Scale unit mismatch (Blender meters vs glTF meters).
21
+ 3. Material non-portable (procedural shader baked-out missing).
22
+ 4. Wrong forward axis.
23
+ - Phase 4 fix: route to `glb-web-handoff`. Pass criteria: GLB opens in target viewer, shows hero geometry, scale correct.
24
+
25
+ ## Playbook 3: "Final response uses Blender jargon"
26
+
27
+ - Phase 2 narrow: highlight every jargon term in the response.
28
+ - Phase 3 likely root causes:
29
+ 1. Response writer received raw plan dump without translation step.
30
+ 2. Plan itself contained jargon (upstream).
31
+ - Phase 4 fix: route to `plain-language-response`. Pass criteria: response readable to a non-Blender user with no follow-up clarifications.
32
+
33
+ ## Playbook 4: "Recipe blocked despite recent smoke pass"
34
+
35
+ - Phase 2 narrow: list configured MCP servers per client + Blender-side add-ons.
36
+ - Phase 3 likely root causes:
37
+ 1. Path 1 + Path 2 both running (Single-bridge constraint violated).
38
+ 2. Two MCP clients targeting same Blender.
39
+ 3. Port collision (commonly `localhost:9876`).
40
+ 4. Anthropic Connector + manual `mcpServers.blender` both ON (both Path 1 host options targeting same Lab stack).
41
+ - Phase 4 fix: route to `bridge-conflicts`. Pass criteria: bridge state matrix shows exactly one active path.
42
+
43
+ ## Playbook 5: "Output exists but doesn't match brief"
44
+
45
+ - Phase 2 narrow: compare brief slot-by-slot against output. Find first mismatched slot.
46
+ - Phase 3 likely root causes (depends on which slot):
47
+ - Subject mismatch → planner overrode the brief.
48
+ - Mood mismatch → lighting planner.
49
+ - Deliverable mismatch → handoff skill.
50
+ - Acceptance failure → quality checker missed a check.
51
+ - Phase 4 fix: route to the earliest mismatched slot's owning skill. Pass criteria: re-run produces output matching the slot.