Repository navigation
improve architecture skill writes mermaid diagrams that fail to parse when an arrow label contains a . #1256
Description
Skill
improve-codebase-architecture
Harness and version
Claude Code 2.1.296, installed as plugin, version 1.3.1
Model and effort
Opus 5.5, medium efort
What happened
The HTML architecture review produced by the improve architecture skill had a diagram that would not draw. The first diagram in item 1 showed a mermaid syntax error. The other diagrams on the page drew fine.
Cause
The skill wrote a dotted arrow whose label contains a period:
S -.walks variable.pending.-> FV[(FormalVariable)]
In mermaid, the label on a dotted arrow (-. text .->) ends at the first .. Here it ends after variable, and mermaid can't read the rest of the line:
Lexical error on line 2. Unrecognized text.
... S -.walks variable.pending.-> FV[(Form
-----------------------^
What you expected
Have the skill always write arrow labels as -->|"..."| / -.->|"..."|. Code reviews often put dotted names like obj.attr or module.func in labels, so the inline -. text .-> form will keep breaking. Better still, have the skill run its diagrams through mermaid.parse before writing the file.
Activity
lab1207 commentedon Oct 12, 2026
Confirmed from the source, and the skill itself teaches the fragile form. The fix belongs in one place: the "Mermaid graph" section of
skills/engineering/improve-codebase-architecture/HTML-REPORT.md(checked atmain49dd158).Do this: in that section, after the flowchart example, add a label rule:
So the section's own example line 71,
C -.leak.-> D[PricingClient], becomesC -.->|"leak"| D[PricingClient].Why this is the whole story: line 71 is the pattern agents copy, and it renders only because
leakhas no period in it. Mermaid ends an inline dotted label at the first period, sowalks variable.pending.truncates the label and the rest of the line is unparseable, which is exactly the lexical error you pasted. Code-review labels are full of dotted names (obj.attr,module.func), so the inline form will keep breaking on every review that names one.Confirm: re-run the skill on the same repo and open the report HTML; the item 1 diagram should draw with no syntax error. If any other arrow form breaks, paste the line and I will look at that one too.
Two caveats. The report pins Mermaid v11 (
HTML-REPORT.md:15), so this is verified against that version's flowchart syntax; sequence-diagram messages (A->>B: text) use a different grammar and are unaffected. And yourmermaid.parsepre-write idea would catch everything, but it needs Node plus Mermaid in the agent environment, so the quoting rule is the minimal fix that covers every label.mattpocock commentedon Oct 12, 2026
Agent brief: in skills/engineering/improve-codebase-architecture/HTML-REPORT.md, the Mermaid graph example uses the inline dotted-label form (C -.leak.-> D), which agents copy; Mermaid ends that label at the first period, so a dotted name like variable.pending breaks the diagram. Change the example to the pipe form (C -.->|"leak"| D) and add one rule: always write edge labels as -->|"..."| or -.->|"..."|.