Skip to main content

Fix Mermaid Diagrams

System Prompt​

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

  1. IMMEDIATELY execute - no questions, no explanations first
  2. ALWAYS show full output from script/tool execution
  3. ALWAYS provide summary after execution completes

DO NOT:

  • Say "I don't need to take action" - you ALWAYS execute when invoked
  • Ask for confirmation unless requires_confirmation: true in frontmatter
  • Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Usage​

/fix-mermaid-diagrams

Fix diagrams in: $ARGUMENTS

Arguments​

$ARGUMENTS - Fixing Scope (optional)​

Specify what to fix:

  • Entire repository: No arguments or "--scope repo"
  • Single file: "--scope file --path diagrams/diagram-01.mmd"
  • Directory: "--scope repo --path diagrams/phase-1/"
  • Dry run: "--scope repo --dry-run"
  • With backup: "--scope repo --backup --verbose"

Default Behavior​

If no arguments:

  • Fixes all .mmd files in repository
  • Applies idempotent fix patterns
  • Creates backup before fixing
  • Provides comprehensive report

Execute mermaid-diagram-fixer subagent to fix Mermaid diagram syntax for GitHub compatibility with idempotent patterns, comprehensive validation, and safety verification.

Command​

Use mermaid-diagram-fixer subagent to fix Mermaid diagrams following these requirements:

Scope​

{{#if scope}} Scope: {{scope}} {{#if path}} Path: {{path}} {{/if}} {{else}} Scope: repo (entire repository including all submodules) {{/if}}

Execution Mode​

{{#if dry_run}} Mode: Dry run (preview fixes without applying) {{else}} Mode: Full execution (apply fixes and save changes) {{/if}}

Verbosity​

{{#if verbose}} Verbosity: Verbose (detailed output for each file) {{else}} Verbosity: Standard (summary only) {{/if}}

Backup​

{{#if backup}} Backup: Enabled (create backup before fixing) {{else}} Backup: Disabled (no backup - use with caution) {{/if}}

Fixing Strategy​

Apply idempotent fixes for GitHub Mermaid compatibility issues:

Priority 1: Line Breaks (CRITICAL)

  • Remove all <br/>, <br>, <br /> tags
  • Replace with spaces for single-line labels
  • GitHub Mermaid doesn't support ANY line break syntax

Priority 2: Over-Encoded Ampersands (HIGH)

  • Fix &amp;amp;... multiple encoding
  • Normalize to single &amp;
  • Prevent re-encoding on subsequent runs

Priority 3: Excessive Quotes (HIGH)

  • Fix [""""Text""""] from repeated wrapping
  • Normalize to ["Text"] single quote
  • Idempotent: won't re-apply to fixed quotes

Priority 4: Cylinder Nodes (MEDIUM)

  • Fix [""""(Label)""""] to exactly 3 quotes
  • Ensure ["""(Label)"""] format
  • Cylinder nodes require exact quote count

Priority 5: Double Braces (MEDIUM)

  • Replace {{ with {
  • Replace }} with }
  • Mermaid doesn't support double braces

Priority 6: Graph Syntax (LOW)

  • Replace deprecated graph TB with flowchart TB
  • Update all graph directions (TB, TD, BT, RL, LR)
  • Maintain backward compatibility

Workflow Phases​

Execute 4-phase fixing workflow:

Phase 1: Discovery & Analysis

  • Enumerate all .mmd files in scope
  • Check for git status and conflicts
  • Identify files with syntax issues
  • Generate processing plan

Phase 2: Backup & Preparation {{#if backup}}

  • Create timestamped backup directory
  • Copy all files to backup location
  • Verify backup integrity {{else}}
  • Skip backup (dry-run mode or backup disabled) {{/if}}

Phase 3: Fix Application {{#if dry_run}}

  • Preview fixes without writing
  • Report what would be changed
  • Show before/after diffs {{else}}
  • Apply idempotent fix patterns
  • Validate each fix before saving
  • Track statistics (files processed, fixes applied) {{/if}}

Phase 4: Verification & Reporting

  • Verify all fixes applied correctly
  • Generate comprehensive report:
    • Files processed
    • Issues found per category
    • Fixes applied per pattern
    • Errors encountered
  • Recommend next steps (git commit, validation)

Output Format​

Summary Report:

✅ Mermaid Diagram Fixing Complete

Files Processed: 119
Issues Found: 342
Fixes Applied: 342

Breakdown:
  - Line breaks removed: 156
  - Ampersands normalized: 8
  - Quotes normalized: 73
  - Cylinder nodes fixed: 5
  - Double braces replaced: 82
  - Graph syntax updated: 18

Duration: 12.3 seconds
Backup Location: diagrams.backup.2025-12-02-15-30-45/

Verbose Output (if --verbose):

Processing: diagrams/diagram-01.mmd
  ✓ Removed 3 line breaks
  ✓ Fixed 1 over-encoded ampersand
  ✓ Normalized 2 excessive quotes
  Status: Fixed (3 changes)

Processing: diagrams/diagram-02.mmd
  Status: No changes needed

...

Error Handling​

File Not Found:

  • Report missing files
  • Continue processing remaining files
  • Include in error summary

Invalid Mermaid Syntax:

  • Report malformed diagrams
  • Skip fixing (to avoid corruption)
  • Recommend manual review

Git Conflicts:

  • Detect uncommitted changes
  • Warn about potential conflicts
  • Allow --force flag to proceed anyway

Write Errors:

  • Automatic rollback from backup
  • Detailed error reporting
  • Safe failure modes

Examples​

Fix All Diagrams in Repository​

/fix-mermaid-diagrams --scope repo

Preview Fixes (Dry Run)​

/fix-mermaid-diagrams --scope repo --dry-run

Fix Single File​

/fix-mermaid-diagrams --scope file --path diagrams/diagram-01.mmd

Fix with Backup and Verbose Output​

/fix-mermaid-diagrams --scope repo --backup --verbose

Fix Specific Directory​

/fix-mermaid-diagrams --scope repo --path diagrams/phase-1-claude-framework/

Integration​

With Git Workflow​

# Fix diagrams, then commit
/fix-mermaid-diagrams --scope repo
/git-sync --target all

With Documentation Update​

# Fix diagrams, then regenerate documentation
/fix-mermaid-diagrams --scope repo
# Manual: Update CHANGELOG.md or README.md

With Validation​

# Fix, then validate on GitHub
/fix-mermaid-diagrams --scope repo
# Manual: Push and check GitHub rendering

Safety Guarantees​

✅ Idempotent Patterns - Never re-apply already-fixed patterns ✅ Read-Before-Write - Always read and validate before modifying ✅ Backup Support - Create backups before bulk operations ✅ Dry-Run Mode - Preview changes without applying ✅ Rollback Capability - Restore from backup on failure ✅ Atomic Operations - Each fix is independent ✅ Git Awareness - Detect conflicts and uncommitted changes ✅ Comprehensive Logging - Full audit trail of changes

Performance​

Expected Processing Time:

  • Small repo (<50 files): <10 seconds
  • Medium repo (50-200 files): <30 seconds
  • Large repo (200+ files): <2 minutes

Memory Usage:

  • <100MB for most repositories
  • <500MB for very large repositories
  • Streaming mode for files >10MB

Troubleshooting​

No Changes Applied​

Possible causes:

  • Files already fixed (idempotent patterns)
  • No matching syntax issues found
  • Dry-run mode enabled

Solution: Run with --verbose to see detailed analysis

Regressions After Fixing​

Possible causes:

  • Overly aggressive patterns
  • Edge case not handled

Solution: Restore from backup, report issue

Git Conflicts​

Possible causes:

  • Uncommitted local changes
  • Files modified externally

Solution: Commit or stash changes first

  • Agent: agents/mermaid-diagram-fixer.md
  • Skill: skills/mermaid-diagram-fixing.md
  • Script: scripts/fix-mermaid-diagrams.py
  • Tests: tests/unit/test_mermaid_fixer.py

Success Output​

When mermaid diagram fixing completes:

✅ COMMAND COMPLETE: /fix-mermaid-diagrams
Scope: <repo|file|directory>
Files Processed: N
Issues Found: N
Fixes Applied: N
Backup: <path|disabled>
Duration: <time>

Completion Checklist​

Before marking complete:

  • Scope identified
  • Files discovered
  • Backup created (if enabled)
  • Fixes applied
  • Report generated

Failure Indicators​

This command has FAILED if:

  • ❌ No .mmd files found
  • ❌ Write errors occurred
  • ❌ Backup failed
  • ❌ Invalid mermaid syntax

When NOT to Use​

Do NOT use when:

  • Creating new diagrams (use direct creation)
  • Non-mermaid diagrams
  • Already validated diagrams

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Skip dry-runUnexpected changesPreview first
No backupLost diagramsEnable backup
Ignore errorsBroken diagramsReview manually

Principles​

This command embodies:

  • #3 Complete Execution - Full fix workflow
  • #4 Confirm Destructive - Backup before changes
  • #9 Based on Facts - Idempotent patterns

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Last Updated: 2025-12-02 Status: Production Ready Maintained By: CODITECT Production Operations Team