Diagram Driven Development (DDD) Skill

Maintain the ai/diagrams directory as the single source of truth for system understanding. All diagrams follow DDD principles, connecting Front-Stage (user experience) to Back-Stage (technical implementation) with clear impact annotations.

Capabilities

1. Create Diagrams - Generate new diagrams for features, architectures, journeys, tests, and refactorings
2. Update Diagrams - Synchronize existing diagrams with code changes
3. Audit Diagrams - Identify outdated, missing, or low-quality diagrams
4. Organize Diagrams - Maintain consistent structure and naming conventions
5. Index Management - Keep README.md index up-to-date with all diagrams
6. Quality Validation - Ensure all diagrams follow DDD principles

Quick Reference

For detailed instructions on each operation, see:

• CREATE.md - Creating new diagrams
• UPDATE.md - Updating existing diagrams
• AUDIT.md - Auditing diagram quality and coverage
• ORGANIZE.md - Directory structure and naming
• DDD_PRINCIPLES.md - Diagram Driven Development methodology
• MERMAID_GUIDE.md - Mermaid syntax patterns

Directory Structure

ai/diagrams/
├── README.md                    # Index of all diagrams
├── features/                    # Feature-specific diagrams
├── architecture/                # System architecture diagrams
├── journeys/                    # User journey diagrams
├── tests/                       # Test coverage diagrams
└── refactoring/                 # Before/After improvement diagrams

Common Workflows

Initial Setup Workflow

1. User starts new project or adds DDD to existing project
2. Create ai/diagrams/ directory structure
3. Generate initial system architecture diagram
4. Create README.md index
5. Document key user journeys

New Feature Workflow

1. User requests new feature
2. Create feature diagram showing user value
3. Connect Front-Stage (UX) to Back-Stage (implementation)
4. Document related files and components
5. Update README.md index

Code Change Workflow

1. Code is modified (new features, refactoring, etc.)
2. Identify affected diagrams
3. Update diagrams to reflect changes
4. Update "Last Updated" dates
5. Add change history entries

Audit Workflow

1. User requests diagram audit
2. Scan all diagrams in ai/diagrams/
3. Check for outdated diagrams (compare dates with git)
4. Identify missing diagrams (features without diagrams)
5. Validate DDD quality (Front-Stage/Back-Stage, impact annotations)
6. Report findings and recommendations

Refactoring Documentation Workflow

1. User plans code refactoring
2. Create "Before" diagram showing current state
3. Create "After" diagram showing improved state (highlight changes in #90EE90)
4. Add impact annotations explaining user benefits
5. Store in refactoring/ directory

Critical Instructions

REQUIRED: Before performing ANY diagram operations, you MUST load the relevant reference file(s) using the Read tool. These references contain essential DDD principles, quality standards, and operational procedures that are NOT included in this overview.

When the user asks to work with diagrams:

1. Identify the operation they want to perform (create, update, audit, organize)
2. MANDATORY: Load the relevant reference file(s) using the Read tool BEFORE executing any operations:
   • Creating diagrams → Read references/CREATE.md AND references/DDD_PRINCIPLES.md FIRST
   • Updating diagrams → Read references/UPDATE.md AND references/DDD_PRINCIPLES.md FIRST
   • Auditing diagrams → Read references/AUDIT.md FIRST
   • Organizing/restructuring → Read references/ORGANIZE.md FIRST
   • Understanding DDD → Read references/DDD_PRINCIPLES.md FIRST
   • Mermaid syntax help → Read references/MERMAID_GUIDE.md FIRST
3. Execute diagram operations following the exact patterns and quality standards from the loaded references
4. Validate quality using DDD principles checklist
5. Update index in README.md to reflect changes
6. Confirm actions and show diagram preview when possible

DO NOT attempt to create or modify diagrams without first loading and reading the relevant reference documentation, especially DDD_PRINCIPLES.md.

DDD Core Principles (Brief)

Every diagram MUST include:

• ✅ Front-Stage (user experience) AND Back-Stage (implementation)
• ✅ Impact Annotations explaining user value of technical components
• ✅ User Actions as entry/exit points
• ✅ Error Paths and recovery options
• ✅ Related Files documentation
• ❌ NO custom fill colors (except #90EE90 for Before/After changes)
• ❌ NO purely technical diagrams without user context

Naming Conventions

File Names

• Descriptive lowercase with hyphens
• Include diagram type prefix
• Format: `{type}-{descriptive-name}.m

...