159 Tool 32546c63

# 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

```bash
# 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

```bash
$ 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

```bash
# 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