diff --git a/skill/slide-alchemy/references/failure-decision-tree.md b/skill/slide-alchemy/references/failure-decision-tree.md index 622e2a8..02844d2 100644 --- a/skill/slide-alchemy/references/failure-decision-tree.md +++ b/skill/slide-alchemy/references/failure-decision-tree.md @@ -1,51 +1,124 @@ # Failure Decision Tree +This document provides remediation guidance when a workflow step fails or produces unsatisfactory results. Follow the decision tree for the failing step to determine the correct course of action. + +--- + ## Base Problems -If the base still contains cards, title bars, central frames, icons, or text: +### Base still contains visible text, icons, cards, title bars, or central content -1. Regenerate the base with `base-prompt-template.md`. -2. Explicitly list the unwanted retained objects. -3. Do not hide the problem by covering it with white boxes. +1. Regenerate the base with a more explicit prompt listing the unwanted retained objects by name. +2. If the second attempt still has remnants, switch to generating the base from a text description of the background instead of editing the source image. +3. If remnants persist, split the page into multiple base regions with simpler content per region and regenerate each region. +4. Do NOT hide the problem by covering it with white boxes, solid fills, or local masks. Regeneration is the only acceptable fix. -If the base removes important outer decoration: +### Base removes important outer decoration or edge elements -1. Regenerate and explicitly list what to keep. +1. Regenerate and explicitly list what to keep (e.g., "Preserve the decorative border on the left side and the accent line at the bottom"). 2. Keep central content removal unchanged. +3. If decorative elements are consistently lost, consider moving them to `simple_geometry_svg_ooxml` instead of relying on the base image. + +### Base colors or gradients do not match the source + +1. Include explicit color references in the prompt (e.g., "Preserve the exact teal-to-navy gradient (#00B4D8 to #1B263B) on the left half"). +2. If the model cannot match colors, consider splitting the page into multiple base regions with simpler gradients. + +--- + +## Element Analysis Problems + +### `validate_element_analysis.py` reports errors + +1. Read the error messages from the validator. +2. Fix the reported fields in `element_analysis.json`. +3. Re-run the validator. Repeat until no errors remain. +4. If the validator itself has a bug, report it as an issue. + +### Elements misclassified between categories + +Common misclassifications: +- A simple icon (e.g., a star) classified as `icon_png` instead of `simple_geometry_svg_ooxml`. +- A complex gradient card classified as `simple_geometry_svg_ooxml` instead of `complex_png_whole`. +- A semantic icon (e.g., a trophy) forced into `simple_geometry_svg_ooxml`. + +Remediation: +1. Apply the core judgment rule: "If an element can be described by outline, fill color, and stroke alone, it is `simple_geometry_svg_ooxml`. If it depends on texture, lighting, gradients, or fine detail stacking, it is a PNG category." +2. When in doubt, classify semantic icons as `icon_png` (they are more stable as generated PNGs). +3. Update `element_analysis.json` and re-validate. + +### Duplicate components not detected + +1. Group elements by visual similarity rather than exact bounding-box match. +2. Create one component definition and reference it from multiple per-slide instances with appropriate position and scale transforms. + +--- ## Icon Sheet Problems -If an icon asset was cropped directly from the original/source slide: +### Icon asset was cropped directly from the original/source slide 1. Discard the crop. 2. Generate a new solid-key asset sheet with an image generation/editing model. 3. Slice the regenerated asset with transparent padding. -If an icon touches a crop edge: +### Icon touches a crop edge -1. Recrop with more padding. -2. If padding pulls in neighboring objects, regenerate the asset sheet with more spacing or fewer icons. +1. Recrop with more padding (add 8-16px on each side). +2. If padding pulls in neighboring objects, regenerate the asset sheet with more spacing or fewer icons per sheet. -If an icon crop contains red lines, card fragments, text, or other neighbors: +### Icon crop contains red lines, card fragments, text, or other neighbors -1. Do not manually erase fragments. +1. Do NOT manually erase fragments. 2. Regenerate the asset sheet with only PNG icons. 3. Put complex icons one per sheet if needed. -If a simple shape is being sliced as PNG: +### Generated icon does not match the source icon + +1. Regenerate with a more specific prompt describing the exact style, proportions, and color. +2. If the icon consistently differs, try generating at a larger size and scaling down. +3. For critical icons where visual fidelity is paramount, consider using the source icon as an image-editing reference rather than generating from scratch. + +### Asset sheet has poor contrast or key-color bleeding + +1. Use a key color that maximizes contrast with all icon colors (pure magenta #FF00FF or pure green #00FF00 are common choices). +2. Regenerate with explicit instructions: "Generate the icon on a pure magenta (#FF00FF) background. Do not blend the background color into the icon edges." +3. If bleeding persists, increase the padding around the icon in the asset sheet. + +### A simple shape is being sliced as PNG 1. Reclassify it as `simple_geometry_svg_ooxml`. 2. Rebuild it as editable geometry. -If a recognizable icon was rebuilt as PPT native geometry and no longer matches the source: +### A recognizable icon was rebuilt as PPT native geometry and no longer matches the source 1. Reclassify it as `icon_png` or `complex_png_whole`. 2. Regenerate it on a solid-key asset sheet with the image generation/editing model. 3. Slice it with transparent padding and update the compose spec placement. +--- + ## SVG / OOXML Problems -If `simple_svg_to_pptx.py` cannot represent a component: +### SVG does not render correctly in PowerPoint + +Common causes: Use of ``, `