feat: review Gustavo and Marcos submitted skills

submitted-skills/Marcos Silva/skills/diagram-plantuml/references/troubleshooting.md

@@ -0,0 +1,66 @@
+# PlantUML Troubleshooting
+
+Symptoms and fixes for the four classes of rendering failure on BASS
+Confluence.
+
+## Macro renders as plain text
+
+| Cause | Fix |
+|-------|-----|
+| Macro name wrong (`PlantUML`, `Plantuml`) | Use `plantuml`, lowercase |
+| Body inside `<ac:rich-text-body>` | Move to `<ac:plain-text-body>` |
+| Macro opened but not closed | Add the matching `</ac:structured-macro>` |
+| Page is in wiki renderer mode | Re-save in storage format (page properties → editor) |
+
+## Diagram renders empty
+
+| Cause | Fix |
+|-------|-----|
+| `@startuml` / `@enduml` missing | Add both, even if PlantUML accepts bodies without |
+| Body has unescaped `<` / `>` outside CDATA | Wrap entire body in `<![CDATA[ … ]]>` |
+| `!include` points to a stdlib the plugin doesn't ship | Replace with hand-drawn equivalent |
+| File-size limit exceeded (very large diagrams) | Split into multiple diagrams |
+
+## Diagram crops on the right
+
+| Cause | Fix |
+|-------|-----|
+| Width > ~900 px | Split the diagram horizontally into two, or simplify |
+| Long labels on long arrows | Shorten labels; move detail to body text |
+| Padding parameters set too high | Drop `skinparam Padding`, `skinparam Margin` overrides |
+
+## Theme reverts to dark on dark space
+
+| Cause | Fix |
+|-------|-----|
+| Page theme overrides the diagram theme | Use `!theme plain` explicitly at the top of the body |
+| BASS theme override | Hard-code colors with `skinparam` per element |
+
+## C4 / standard library includes fail
+
+| Cause | Fix |
+|-------|-----|
+| Plugin doesn't ship the stdlib | Switch to `component` diagram or hand-drawn boxes |
+| Include URL is blocked by network policy | Mirror the stdlib locally, use `!include /path/to/C4_Container.puml` (only if the plugin supports it) |
+
+## Debugging loop
+
+1. Save the `.puml` body to a file.
+2. Run `plantuml -tpng -checkonly -failfast2 file.puml`.
+3. If local parse fails, the body is wrong — fix the syntax.
+4. If local parse succeeds but Confluence fails, the wrapper is wrong — fix
+   the storage macro form.
+
+## When to give up on PlantUML
+
+- The diagram needs interactivity (hover, click). Confluence PlantUML does
+  not support this.
+- The diagram needs real images (logos, photos). Drop them in via attachment
+  instead.
+- The diagram needs to be edited by non-technical authors. PlantUML is not
+  the right tool.
+
+## When to escalate
+
+- The BASS plugin version changes and breaks a working diagram. Capture the
+  diff, fix the diagram, and update this troubleshooting page.