docs(python-architect): document mermaid classDiagram :::cssClass GitHub-render trap#970
Merged
danielmeppiel merged 2 commits intomainfrom Apr 27, 2026
Merged
Conversation
…Hub-render trap
GitHub's mermaid parser rejects ':::cssClass' appended to a relationship
line ('A *-- B:::touched') with parse error 'Expecting NEWLINE, EOF,
LABEL, got STYLE_SEPARATOR'. The shorthand is only valid as a
standalone 'class Name:::cssClass' declaration in classDiagram. This
trap silently breaks rendered diagrams in panel review verdict comments,
which are the persona's authoritative output channel.
The persona's existing illustrative example was already correct; this
adds an explicit gotcha block so the rule cannot be missed. Trap does
not apply to flowchart diagrams, where the inline form is valid.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Documents a Mermaid/GitHub rendering gotcha in the python-architect persona guidance so future panel outputs avoid invalid classDiagram styling syntax on GitHub.
Changes:
- Add an explicit gotcha note explaining that
:::cssClassmust be used in standaloneclass Name:::cssClassdeclarations forclassDiagramon GitHub. - Regenerate the
.github/mirror of the agent file and updateapm.lock.yamlaccordingly.
Show a summary per file
| File | Description |
|---|---|
.apm/agents/python-architect.agent.md |
Adds the explicit Mermaid classDiagram :::cssClass GitHub-rendering gotcha note. |
.github/agents/python-architect.agent.md |
Regenerated mirror of the authored .apm/ agent change. |
apm.lock.yaml |
Updates the content hash for the regenerated .github/agents/python-architect.agent.md. |
Copilot's findings
- Files reviewed: 3/3 changed files
- Comments generated: 0
3 tasks
danielmeppiel
added a commit
that referenced
this pull request
Apr 27, 2026
* chore(release): cut 0.9.4 CHANGELOG entry for 0.9.4 covers all 7 PRs merged since v0.9.3: - #974 SKILL_BUNDLE day-0 install parity (Added) - #954 automate apm-triage-panel workflow (Added) - #970 python-architect mermaid classDiagram trap (Changed) - #911 REQUESTS_CA_BUNDLE TLS validation (Fixed) - #971 triage-panel project-sync dispatch (Fixed) - #910 CLI consistency cleanup (Fixed) - #958 issue templates label taxonomy (Fixed) - #953 docs auto-deploy after bot-cut releases (Fixed) Open milestone 0.9.4 issues (41) reassigned to 0.9.5. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(changelog): tighten 0.9.4 entries (so-what for developers) Refactor per Keep-a-Changelog spirit: lead with developer impact, trim agent-internals prose, group maintainer-only changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(changelog): add #660 install.sh air-gapped entry to 0.9.4 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
While running the apm-review-panel skill on Epic #898, the Python Architect's "After" class diagram failed to render on GitHub with:
The cause: GitHub's mermaid parser only accepts the
:::cssClassshorthand as a standaloneclass Name:::cssClassdeclaration inclassDiagram. Appending it after a relationship arrow (A *-- B:::touched) parses fine in flowchart but not in classDiagram. The persona's existing example was already correct, but the rule was implicit -- the next reviewer drifted from it and silently shipped a broken diagram.Verdict comment that hit the trap: #898 (comment) (since patched to standalone form).
What
Adds one explicit Gotcha block under the OO / class diagram section. No code changes, no behavior changes -- this is persona-contract documentation that protects every future panel review's mermaid output.
Files
.apm/agents/python-architect.agent.md-- the authored source.github/agents/python-architect.agent.md-- regenerated viaapm install --target copilotper repo conventionapm.lock.yaml-- hash bump for the regenerated mirrorTest
The block reads as plain documentation; no executable contract changes. Verified by re-rendering the patched Epic #898 diagram on GitHub (now renders correctly with standalone
class X:::toucheddeclarations).Independent of and orthogonal to PR #897 (visual-communicator persona).