Wave 3A: README & Mermaid Diagram Discovery & Audit

[ashleyshaw]

Overview

Systematic audit and discovery of all 44 README.md files and embedded Mermaid diagrams across the LightSpeed .github repository. This is Wave 3A of the comprehensive README/Mermaid modernization initiative.

Wave: Wave 3A (README & Mermaid Audit)
Owner: Codex
Epic: Next Issues Execution Plan
Estimated Effort: 2-3 hours
Blockers: None (can start immediately)
Unblocks: Wave 3B (Repair & Update), Wave 3C (Workflow Setup)

---

Acceptance Criteria

• Scan all 44 README.md files in repository
• Extract and categorize all embedded Mermaid diagrams
• Identify syntax errors (render failures)
• Identify outdated flows or process descriptions
• Identify missing accessibility attributes (accTitle, accDescr)
• Identify WCAG AA contrast compliance issues
• Generate comprehensive audit report in .github/reports/mermaid-audit/
• Categorize findings by priority (Critical, High, Medium, Low)
• Create inventory CSV for tracking repairs
• Output ready for Wave 3B (Repair & Update) team

---

README File Inventory (44 total)

Priority: High (6 files)

• README.md (root)
• .github/README.md
• docs/README.md
• agents/README.md
• instructions/README.md
• skills/README.md

Priority: High (12 files - Feature Folders)

• ai/ (agents.md, Claude.md, Gemini.md, RUNNERS.md)
• agents/ (already counted above)
• cookbook/README.md
• hooks/README.md
• instructions/ (already counted above)
• plugins/README.md
• skills/ (already counted above)
• workflows/README.md

Priority: Medium (20 files - Sub-Folders)

• Various sub-folder README files and reference docs

Priority: Low (6 files - Test/Config)

• Auto-generated or reference-only documentation

---

Audit Checklist

For Each README:

1. Frontmatter Validation

• File has YAML frontmatter (if applicable)
• Has title, description, created_date, last_updated
• Status field is current (not stale)

2. Mermaid Diagram Scan

• Identify all Mermaid code blocks (```mermaid)
• Count total diagrams
• Record diagram types (flowchart, graph, sequence, gantt, etc.)

3. Syntax Validation

• Run each Mermaid diagram through validator
• Record any parse errors or render failures
• Note deprecated syntax patterns

4. Content Assessment

• Verify diagram still reflects current architecture/process
• Check for outdated tool/service names
• Validate links in diagram descriptions

5. Accessibility Check

• Presence of accTitle attribute (diagram title for screen readers)
• Presence of accDescr attribute (diagram description for screen readers)
• Contrast ratios meet WCAG AA (3:1 minimum)
• Font sizes readable on mobile

6. Freshness Assessment

• Compare last_updated date to current date
• Flag if >6 months stale (needs refresh)
• Check commit history for last meaningful update

---

Deliverables

1. Audit Report (.github/reports/mermaid-audit/audit-report-2026-05-28.md)

Summary with sections:

• Executive summary (total files, diagram count, issue distribution)
• Critical findings (render failures, missing accessibility)
• By-category breakdown (syntax errors, staleness, WCAG issues)
• Recommendations for Wave 3B

2. Findings Inventory (.github/reports/mermaid-audit/findings.csv)

Columns:

• File path
• Diagram count
• Syntax errors (Y/N)
• Outdated flow (Y/N)
• Missing accessibility (Y/N)
• WCAG compliance (Pass/Fail)
• Priority (Critical/High/Medium/Low)
• Notes

3. Detailed Audit Log (.github/reports/mermaid-audit/audit-log.md)

Line-by-line audit with:

• File path
• Findings per file
• Specific recommendations
• Estimated repair effort

---

Execution Steps

1. Setup:

   • Create .github/reports/mermaid-audit/ directory
   • Initialize audit tracking spreadsheet

2. Discovery Phase (1-1.5 hours):

   • Scan all 44 README files
   • Extract Mermaid diagram code blocks
   • Run syntax validation on each

3. Assessment Phase (0.5-1 hour):

   • Evaluate accessibility attributes
   • Check WCAG contrast compliance
   • Assess content freshness

4. Reporting Phase (0.5 hours):

   • Generate audit report with findings
   • Create CSV inventory for Wave 3B
   • Output executive summary

5. Handoff to Wave 3B:

   • Share audit report with repair team (Claude)
   • Prioritize critical items for immediate fix

---

Definition of Done

• All 44 README files scanned and documented
• Mermaid diagram audit complete with detailed findings
• Audit report published to .github/reports/mermaid-audit/
• CSV inventory ready for Wave 3B repair team
• Findings categorized by priority and effort estimate
• Links to original files and affected diagrams documented
• Ready for Wave 3B (Repair & Update) handoff

---

Related Issues

• Wave 3B: README & Mermaid Repair & Update (Claude-owned, parallel execution)
• Wave 3C: Workflow & Agent Coordination Setup (Codex-owned, after 3A/3B progress)
• Epic: Next Issues Execution Plan

---

Success Metrics

• 100% of README files reviewed
• 100% of Mermaid diagrams catalogued
• Audit report with ≥95% accuracy (validated against actual renders)
• CSV inventory ready for programmatic processing
• Zero blockers for Wave 3B to begin repairs

---

Notes

• This is a discovery-only phase; repairs handled by Wave 3B (Claude)
• Focus on audit quality and complete inventory; repairs can be parallel
• Use .github/reports/mermaid-audit/ as canonical output location
• Reference mermaid.instructions.md for validation standards
• Coordinate with Wave 3B for repair prioritization

[linear-code]

LS-756