feat: migrate skills review desk to astro

2026-09-05 16:54:37 +00:00
parent 107e429fb9
commit 71e4775573
66 changed files with 8184 additions and 96 deletions
@@ -0,0 +1,97 @@
+---
+name: diagram-plantuml
+description: Embed PlantUML diagrams inside a Confluence page using the {plantuml} macro in the storage body. Use when a page needs a sequence, component, class, state, activity, deployment, or timing diagram and the macro name is not in the caller's muscle memory.
+---
+
+# Diagram — PlantUML in Confluence
+
+PlantUML renders server-side on the Confluence PlantUML plugin. The macro is
+`{plantuml}`, the body is plain PlantUML between `@startuml` and `@enduml`,
+and the host (BASS) renders it through the bundled plugin — no external URL
+needed for private spaces.
+
+## Hard rules
+
+- **Macro name is `plantuml`**, lowercase. `{PlantUML}` and `{plantUml}` both
+  fail to render.
+- **Body goes inside `<ac:plain-text-body><![CDATA[ … ]]></ac:plain-text-body>`**,
+  not inside `<ac:rich-text-body>`. The rich-text body treats the body as
+  XHTML, which mangles `<`, `>`, and `&` that PlantUML relies on.
+- **Always include `@startuml` and `@enduml`** even though PlantUML accepts
+  bodies without them. The Confluence renderer is stricter than the CLI.
+- **No diagram wider than ~900 px.** Confluence content columns are narrow;
+  a wide diagram overflows on smaller screens. Split or simplify.
+- **No diagram inside an info / note / warning panel.** The renderer nests
+  and crops. Put the diagram at body root, then put a `{tip}` after it with
+  the takeaway.
+- **No diagram inside a code block.** Same nesting failure.
+- **Never paste a base64 PNG into the body** to skip PlantUML. If PlantUML
+  can't render what you drew, simplify the diagram.
+
+## Storage template
+
+```xml
+<ac:structured-macro ac:name="plantuml">
+  <ac:plain-text-body><![CDATA[@startuml
+!theme plain
+skinparam dpi 150
+
+participant Client
+participant Service
+
+Client -> Service: request
+Service --> Client: response
+@enduml]]></ac:plain-text-body>
+</ac:structured-macro>
+```
+
+The `!theme plain` directive keeps diagrams legible on the BASS light
+background; the `skinparam dpi 150` is the right size for the Confluence
+column width. Drop both when a diagram already has its own `skinparam`
+block.
+
+## Workflow
+
+1. Decide the diagram type. See [references/diagram-types.md](references/diagram-types.md)
+   for the cheat sheet (sequence, component, class, state, activity,
+   deployment, timing, use case, ER, mindmap).
+2. Draft the PlantUML in a `.puml` scratch file. Run `plantuml -tpng -checkonly
+   -failfast2 file.puml` if `plantuml` is on `$PATH` — fast feedback loop
+   before posting.
+3. Wrap in the storage template above.
+4. Add a one-line caption directly after the macro using a `{tip}` block or
+   a bolded sentence; do not rely on the title attribute (some renderers
+   strip it).
+5. Hand the body to the `page-reviewer` skill. The reviewer re-runs the
+   syntax check on every `{plantuml}` block.
+
+## Common patterns
+
+- **Sequence with notes:** use `note left of Alice: …` / `note right of
+  Bob: …`. Inside an `alt`/`opt`/`loop` block, the note attaches to the
+  branch.
+- **Component / C4:** use `!include <C4_Container>` only if the BASS PlantUML
+  plugin has the C4 stdlib. If unsure, prefer hand-drawn `component` arrows.
+- **State:** use `state "Long label" as S1` to avoid breaking state names
+  that contain spaces.
+- **Timing:** use `robust` for digital signals and `analog` for continuous;
+  mixing them on one line is a render error.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---------|--------------|
+| Macro renders as plain text | Macro name wrong, or the body is inside `<ac:rich-text-body>` instead of `<ac:plain-text-body>` |
+| Diagram renders empty | `@startuml / @enduml missing, or body has unescaped < / >` outside CDATA |
+| Diagram crops on the right | Width over the column budget — split or simplify |
+| Theme reverts to dark on dark space | Use `!theme plain` explicitly; some renderers ignore the page theme |
+| C4 include fails | Plugin doesn't ship the stdlib — switch to hand-drawn arrows |
+
+Full troubleshooting table: [references/troubleshooting.md](references/troubleshooting.md).
+
+## Related
+
+| Skill | Role |
+|-------|------|
+| `confluence-page` | Owns the storage body; delegates diagrams here |
+| `page-reviewer` | Re-runs the syntax check on every `{plantuml}` block |