Easy Diagram Generation Tool

Easy Diagram Generation Tool

This tool automates the process of identifying and preparing Easy difficulty diagrams with high MicroSim match scores for generation.

Overview

The generate-easy-diagrams.py script:

1. Reads the diagrams.csv file generated by diagram-report.py
2. Filters for diagrams matching criteria:
   • Difficulty = Easy
   • First recommended MicroSim score > 90 (configurable)
3. Extracts full specifications from the chapter markdown files
4. Generates individual specification files for each candidate
5. Creates reports and execution plans for batch processing

Quick Start

# Run from repository root
python src/diagram-reports/generate-easy-diagrams.py

# View report only (don't create files)
python src/diagram-reports/generate-easy-diagrams.py --dry-run

# Use custom score threshold
python src/diagram-reports/generate-easy-diagrams.py --min-score 95

Output Files

The script creates the following in docs/learning-graph/easy-diagrams/:

1. generation-report.md

Summary report showing:

• Total candidates found
• Count by MicroSim generator type
• Detailed listing by chapter

2. execution-plan.md

Step-by-step plan organized by generator type with:

• Diagram title and chapter
• Match score
• Specification file path
• Command to invoke the skill

3. specs/ directory

Individual specification files for each diagram:

• Named: {chapter_num}-{diagram-slug}.md
• Contains full diagram specification
• Ready to use with MicroSim generator skills

Example Run

$ python src/diagram-reports/generate-easy-diagrams.py

======================================================================
Easy Diagram Generation Tool
======================================================================
CSV File: docs/learning-graph/diagrams.csv
Chapters Dir: docs/chapters
Output Dir: docs/learning-graph/easy-diagrams
Min Score: 90
Dry Run: False
======================================================================

Reading CSV: docs/learning-graph/diagrams.csv
Found 2 candidates (Easy difficulty, score > 90)

Report saved to: docs/learning-graph/easy-diagrams/generation-report.md
Execution plan saved to: docs/learning-graph/easy-diagrams/execution-plan.md

Saving specification files to: docs/learning-graph/easy-diagrams/specs
Saved 2 specification files

======================================================================
NEXT STEPS:
======================================================================
1. Review the generation report
2. Review the execution plan
3. Specification files are in: docs/learning-graph/easy-diagrams/specs
4. Use Claude Code to invoke the recommended skills with each specification
======================================================================

Workflow Integration

Manual Execution

For each diagram in the execution plan:

1. Read the specification file
2. Invoke the recommended skill using Claude Code:

   Use the {generator-name} skill to create the following diagram:
   
   [paste specification content]
   

3. Review and save the generated MicroSim

Automated Execution (via Claude Code)

You can ask Claude Code to process all diagrams:

Please process all Easy diagrams in the execution plan at
docs/learning-graph/easy-diagrams/execution-plan.md.

For each diagram:
1. Read the specification file
2. Invoke the recommended MicroSim generator skill
3. Generate and save the MicroSim

Command-Line Options

--csv PATH              Path to diagrams.csv
                        Default: docs/learning-graph/diagrams.csv

--chapters-dir PATH     Path to chapters directory
                        Default: docs/chapters

--output-dir PATH       Output directory for generated files
                        Default: docs/learning-graph/easy-diagrams

--min-score N           Minimum match score threshold (0-100)
                        Default: 90

--dry-run               Generate report only, don't save files

Example: Custom Configuration

# Generate diagrams with score > 95 only
python src/diagram-reports/generate-easy-diagrams.py --min-score 95

# Use custom paths
python src/diagram-reports/generate-easy-diagrams.py \
  --csv path/to/diagrams.csv \
  --chapters-dir path/to/chapters \
  --output-dir path/to/output

# Preview what would be generated
python src/diagram-reports/generate-easy-diagrams.py --dry-run

Current Results

Based on the existing diagrams.csv:

• Total Candidates: 2 Easy diagrams with score > 90
• Generators Needed:
  • timeline-generator: 1 diagram
  • mermaid-generator: 1 diagram

Identified Diagrams

1. Content Generation Process Timeline (Chapter 10)

   • Generator: timeline-generator
   • Score: 98/100
   • Type: Horizontal timeline showing 8 stages of content generation

2. MicroSim File Relationship Diagram (Chapter 12)

   • Generator: mermaid-generator
   • Score: 93/100
   • Type: Block diagram showing file relationships

Technical Details

Specification Extraction

The script uses regex patterns to:

• Locate diagram sections in chapter markdown files
• Extract content from <details> blocks
• Remove MicroSim recommendation sections
• Preserve all specification details

Filename Slugification

Diagram titles are converted to filesystem-safe slugs:

• Convert to lowercase
• Replace non-alphanumeric characters with hyphens
• Remove leading/trailing hyphens

Example: "Content Generation Process Timeline" → "content-generation-process-timeline"

Error Handling

The script handles:

• Missing CSV files
• Missing chapter directories
• Missing diagram specifications
• Malformed recommendation strings

Warnings are printed to console but don't stop execution.

Related Tools

• diagram-report.py: Generates the source diagrams.csv file
• microsim-matcher skill: Analyzes diagram specs and recommends generators
• MicroSim generator skills: timeline-generator, mermaid-generator, etc.

Future Enhancements

Potential improvements:

• Support for Medium and Hard difficulty diagrams
• Batch skill invocation through Claude Code API
• Progress tracking for completed diagrams
• Quality validation after generation
• Integration with chapter update workflow

Troubleshooting

No candidates found:

• Check that diagrams.csv exists and has data
• Verify difficulty column contains "Easy" values
• Confirm recommendations are present with scores > threshold
• Try lowering --min-score threshold

Missing specifications:

• Ensure chapter files exist in docs/chapters/
• Verify diagram titles match exactly between CSV and chapter files
• Check that <details> blocks are properly formatted

File permission errors:

• Ensure output directory is writable
• Check disk space availability
• Verify no file locks on output files