refactor(aidd-context): conform 09-mermaid to the skill contract

plugins/aidd-context/CATALOG.md

@@ -166,7 +166,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [01-mermaid.md](skills/09-mermaid/actions/01-mermaid.md) | - |
 | `-` | [README.md](skills/09-mermaid/README.md) | - |
 | `references` | [mermaid-conventions.md](skills/09-mermaid/references/mermaid-conventions.md) | - |
-| `-` | [SKILL.md](skills/09-mermaid/SKILL.md) | `Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow.` |
+| `-` | [SKILL.md](skills/09-mermaid/SKILL.md) | `Generate a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. Use when the user wants to turn an architecture, lifecycle, or flow description into a Mermaid diagram, or when another skill needs one. Not for other diagram formats like PlantUML or Graphviz, or for rendering a diagram to an image.` |
 
 #### `skills/10-learn`
 

plugins/aidd-context/skills/09-mermaid/README.md

@@ -1,59 +1,29 @@
-← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md)
+← [framework](../../../../README.md) / [aidd-context](../../README.md)
 
-# 04 - Mermaid
+# 09 - Mermaid
 
-Generates a 100% valid, high-quality Mermaid diagram from a markdown source
-through a structured plan-confirm-generate-review loop. Defaults to flow
-direction `LR` and targets Mermaid 10.8.0+.
+Generates a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop.
 
 ## When to use
 
-- Turning a written description (architecture, lifecycle, flow) into a
-  Mermaid diagram.
-- Producing a diagram to embed in an `INSTALL.md`, ADR, or memory file.
-- Invoked by other aidd-context skills that need a diagram (e.g.
-  `01-bootstrap` calls this from action 04).
+- Turning a written description (architecture, lifecycle, flow) into a Mermaid diagram.
+- Producing a diagram to embed in an `INSTALL.md`, a decision record, or a memory file.
+- When another skill needs a diagram (for example `01-bootstrap` calls it).
 
-## When NOT to use
+## When not to use
 
-- For non-Mermaid diagram formats (PlantUML, Graphviz, draw.io).
+- For other diagram formats (PlantUML, Graphviz, draw.io).
 - To freehand a diagram without a written source to plan from.
-- To render or export a diagram to PNG/SVG - this skill produces fenced
-  Mermaid text only.
+- To render or export to an image. This skill produces fenced Mermaid text only.
 
-## How to invoke
+## Flow
 
-```
-Use skill aidd-context:09-mermaid
-```
+One action with a six-step loop: get the source, plan, confirm the plan, generate, offer a review, review on confirm. The diagram is generated only from the confirmed plan, and never adds an element the user did not confirm.
 
-The skill runs one action with a six-step loop:
+## Requires
 
-1. Ask for the document to convert.
-2. Plan the diagram (components, parents/children, directions, relations,
-   labels).
-3. Confirm the plan with the user.
-4. Generate a 100% valid Mermaid diagram from the confirmed plan.
-5. Offer a review.
-6. Review on confirm: check syntax, empty/misplaced nodes, and suggest
-   improvements without adding elements absent from the confirmed plan.
+A written source (a paragraph, a list, or a section) describing what to diagram.
 
-## Outputs
+## Details
 
-- A fenced ```mermaid block containing a syntactically valid diagram that
-  parses against Mermaid 10.8.0+.
-- An optional review note when the user accepts the review step.
-
-## Prerequisites
-
-- A markdown source (paragraph, list, or section) describing what to
-  diagram.
-- Awareness of the project's Mermaid conventions (see
-  `references/mermaid-conventions.md`).
-
-## Technical details
-
-See [`SKILL.md`](SKILL.md) for the entry contract,
-[`actions/01-mermaid.md`](actions/01-mermaid.md) for the full process,
-and `references/mermaid-conventions.md` for the conventions enforced
-during generation.
+See [`SKILL.md`](SKILL.md) for the contract, [`actions/01-mermaid.md`](actions/01-mermaid.md) for the process, and [`references/mermaid-conventions.md`](references/mermaid-conventions.md) for the conventions and defaults every diagram follows.

plugins/aidd-context/skills/09-mermaid/SKILL.md

@@ -1,14 +1,27 @@
 ---
 name: 09-mermaid
-description: Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow.
+description: Generate a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. Use when the user wants to turn an architecture, lifecycle, or flow description into a Mermaid diagram, or when another skill needs one. Not for other diagram formats like PlantUML or Graphviz, or for rendering a diagram to an image.
 ---
 
-# Skill: mermaid
+# Mermaid
 
-Produces valid, structured Mermaid diagrams through iterative planning and user confirmation.
+Produces a valid, structured Mermaid diagram from a written source by planning it, confirming the plan, generating, and offering a review.
 
 ## Actions
 
-```markdown
-@actions/01-mermaid.md
-```
+| #   | Action    | Role                                                    | Input            |
+| --- | --------- | ------------------------------------------------------ | ---------------- |
+| 01  | `mermaid` | Plan, confirm, generate, and review one diagram         | a written source |
+
+Run action `01` and run its `## Test` before trusting the result.
+
+## Transversal rules
+
+- Plan before generating, and confirm the plan with the user. Block on the answer.
+- Generate only what the confirmed plan holds. Never add a node or a relationship the user did not confirm.
+- Follow the project's Mermaid conventions for every diagram.
+- Output the diagram as a fenced block, never describe it in prose.
+
+## References
+
+- `references/mermaid-conventions.md`: the conventions and defaults every generated diagram follows.

plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md

@@ -1,35 +1,24 @@
 # 01 - Mermaid
 
-Produce a 100% valid, high-quality Mermaid diagram from a markdown document through a plan-confirm-generate-review loop.
+Produce a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop.
 
-## Inputs
+## Input
 
-```yaml
-source: <markdown document to convert>
-```
+The written source to diagram: a paragraph, a list, or a section describing an architecture, a lifecycle, or a flow. Ask for it when it is not provided.
 
-## Outputs
+## Output
 
-A Mermaid diagram fenced as ```mermaid + an optional review note. On first user message, the action prints the six numbered steps below as short bullets so the user knows what is coming.
-
-```mermaid
-<rendered diagram>
-```
+A Mermaid diagram in a fenced block, plus an optional review note. On the first message, list the steps below as short bullets so the user knows what is coming.
 
 ## Process
 
-1. **Ask for the document to convert** when not already provided.
-2. **Plan the diagram.** Analyze the source and write down a detailed plan identifying at least:
-   - Components (main elements, logical groups; use colors).
-   - Children and parent elements.
-   - Directions and hierarchies.
-   - Relationships (colors, connections, dependencies).
-   - Notes and labels per element when needed.
-3. **Confirm the plan.** Ask the user "Do you confirm the plan?" and wait for explicit confirmation.
-4. **Generate** the 100% valid Mermaid diagram from the plan. Flow direction defaults to `LR`. Minimum Mermaid version 10.8.0. Apply the conventions in `@../references/mermaid-conventions.md`.
-5. **Offer a review.** Ask the user "Do you want me to review it?" and wait for an answer.
-6. **Review on confirm.** Check syntax, look for empty or misplaced nodes, suggest improvements. Do NOT add any extra elements that were not in the confirmed plan.
+1. **Get the source.** Ask for the document to diagram when it is not already provided.
+2. **Plan.** Analyze the source and write a plan that names: the components and their logical groups, the parent and child elements, the directions and the hierarchy, the relationships (connections, dependencies), and the labels or notes each element needs.
+3. **Confirm.** Ask the user to confirm the plan. Block on the answer.
+4. **Generate.** Produce a valid Mermaid diagram from the confirmed plan, following the conventions and defaults in `@../references/mermaid-conventions.md`.
+5. **Offer a review.** Ask whether the user wants a review, and wait.
+6. **Review on confirm.** Check the syntax, look for an empty or misplaced node, and suggest improvements. Never add an element that was not in the confirmed plan.
 
 ## Test
 
-The generated block is fenced with ```mermaid, parses without error against Mermaid 10.8.0+, follows the conventions in `@../references/mermaid-conventions.md`, and contains no nodes or relationships absent from the user-confirmed plan.
+- The diagram is in a fenced Mermaid block, parses without error, follows the conventions reference, and holds no node or relationship absent from the confirmed plan.

plugins/aidd-context/skills/09-mermaid/references/mermaid-conventions.md

@@ -1,45 +1,46 @@
 # Mermaid generation rules
 
+The Defaults, Header, Global, Naming, Links, and Styles sections apply to every diagram type. The States and Gantt sections apply only to their own type. For a type with no section here, the global rules still hold and the rest follows standard Mermaid syntax.
+
+## Defaults
+
+- Target Mermaid 10.8.0 or newer.
+- Flow direction defaults to `LR` unless the source implies another.
+
 ## Header
 
-- Always have title in schema using "---" to define it
+- Give the diagram a title through the `---` frontmatter block.
 
 ## Global
 
-- NEVER use "\n"
-- NEVER use "<br>" in labels
+- Keep a label on one line. A literal `\n` renders as the characters, never use it. Prefer a shorter label over a `<br>` break.
+- Use descriptive names, never `A` or `B`.
+- Keep naming consistent across the diagram.
 
 ## States and nodes
 
-- Define groups, parents, children
-- Use fork and join states
-- Use clear and concise names
-- Use "choice" for conditions
-- No standalone nodes
-- No empty nodes
+- Define groups, parents, and children where the source has them.
+- Use fork and join (`<<fork>>`, `<<join>>`) for parallel paths, and choice (`<<choice>>`) for a condition.
+- No standalone node, no empty node.
 
 ## Naming
 
-- Declare elements only (no links) at top
-- Consistent naming throughout
-- Descriptive names (no "A", "B")
-- Node IDs: unquoted alphanumeric (`MyNode`, not `"MyNode"`)
-- Labels: in brackets with quotes (`MyNode["My Label"]`)
-- Replace ":" with "$" in state names
+- Node ids are unquoted alphanumeric (`MyNode`, not `"MyNode"`).
+- Labels go in brackets with quotes (`MyNode["My Label"]`).
+- Keep `:` out of a state id, it delimits the state's description. Use a clean id and add a description on its own line if needed.
 
 ## Links
 
-- Links made at bottom of diagram
-- Use direction when possible
-- "A -- text --> B" for regular links
-- "A -.-> B" for conditional links
-- "A ==> B" for self-loops
+- Declare the elements first, then the links.
+- Give the link a direction.
+- `A -- text --> B` for a labeled link.
+- `A -.-> B` for a dashed link, for example a conditional or optional path.
+- `A ==> B` for a thick link, to emphasize a path. A self-loop is `A --> A`.
 
 ## Styles
 
-- Do style unless specified by user
+- Do not add styling unless the user asks for it.
 
 ## Gantt
 
-- Use tags: `active`, `done`, `crit`, `milestone`
-- Tags are combinable
+- Use the tags `active`, `done`, `crit`, `milestone`. They combine.