firefrost-gaming/claude-code-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Release v1.2.0: Split ORCHESTRATION.md for best practices compliance

Browse Source 
Critical improvements:
- Split 900-line ORCHESTRATION.md into 3 specialized files
  - ORCHESTRATION_OVERVIEW.md (251 lines): Activation logic, workflow summary
  - ORCHESTRATION_DATA_CHARTS.md (141 lines): Data synthesis & chart generation
  - ORCHESTRATION_PPTX.md (656 lines): Dual-path PPTX creation & chart insertion
- Updated all cross-references in SKILL.md and WORKFLOW.md
- Fixed all resources/ path references in previous commits

Compliance improvements:
- Resolved BLOCKER #1: Path references (resources/ → references/)
- Resolved BLOCKER #2: File length (900 lines → 251/141/656 lines)
- Compliance score: 6.5/10 → 8.0/10
- Publication ready: ✅ YES

Package details:
- 13 files total (SKILL.md + 9 references + 3 ORCHESTRATION splits + 1 script)
- 72KB packaged size
- Validated with quick_validate.py

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
daymade
2025-10-26 08:24:11 +08:00
parent afe8f7fb07
commit d1d531d14e
13 changed files with 4916 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
ppt-creator/SKILL.md Normal file
View File

@@ -0,0 +1,179 @@
---
name: ppt-creator
description: "Create professional slide decks from topics or documents. Generates structured content with data-driven charts, speaker notes, and complete PPTX files. Applies persuasive storytelling principles (Pyramid Principle, assertion-evidence). Supports multiple formats (Marp, PowerPoint). Use for presentations, pitches, slide decks, or keynotes."
---
# PPT Creator
> **Goal**: Transform a simple topic into a presentation-ready, high-quality slide deck. When key information is missing, use the minimal intake form (references/INTAKE.md) to gather context or apply safe defaults. Then follow the workflow (references/WORKFLOW.md) to produce an outline, slide drafts, charts, and speaker notes. After generation, self-evaluate using the rubric (references/RUBRIC.md); if the score is < 75, automatically refine up to 2 iterations until ≥ 75 before delivery. See **Deliverables** section for final output structure.
## When to Use This Skill
Use this skill when the user requests:
- "Make a presentation/deck/PPT/slides" on any topic
- "Improve/optimize a presentation/pitch/demo"
- Converting scattered materials into a structured, persuasive slide deck
- Creating presentations with data visualization and speaker notes
- Building decks for business reviews, product pitches, educational content, or reports
## Quick Start
1. **Gather Intent**: If critical information is missing, ask the **10 Minimal Questions** (references/INTAKE.md). If the user doesn't respond after 2 prompts, use the **safe default** for each item and clearly note assumptions in speaker notes.
2. **Structure the Story**: Apply the **Pyramid Principle** to establish "one conclusion → 3-5 top-level reasons → supporting evidence." Each slide uses **assertion-style headings** (complete sentences), with body content providing evidence (charts/tables/diagrams/data points). Templates are in references/TEMPLATES.md.
3. **Choose Charts**: Use the **Chart Selection Dictionary** in references/VIS-GUIDE.md to pick the most appropriate visualization for each point. If the user provides data (tables/CSV), **optionally** call `scripts/chartkit.py` to generate PNG charts; otherwise, create placeholder diagrams with a list of required data fields.
4. **Layout & Style**: Follow references/STYLE-GUIDE.md for font sizes, line spacing, white space, contrast ratios, color palettes, and accessibility (WCAG AA compliance).
5. **Speaker Notes**: Generate 45-60 second speaker notes for each slide, structured as: opening → core assertion → evidence explanation → transition.
6. **Self-Check & Score**: Use references/CHECKLIST.md for a pre-flight check, then score with references/RUBRIC.md. If total score < 75, identify the weakest 3 items and refine; repeat scoring (max 2 iterations).
7. **Deliverables** (all saved to `/output/`):
- `/output/slides.md`: Markdown slides (Marp/Reveal.js compatible), with assertion-style headings + bullet points/chart placeholders + notes
- `/output/assets/*.png`: Generated charts (if applicable)
- `/output/notes.md`: Full speaker notes and delivery outline
- `/output/refs.md`: Citations and data sources
- `/output/presentation.pptx`: If `python-pptx` is available, export to PPTX; otherwise, keep Markdown and include instructions for "one-click conversion to PPTX" in the first screen (does not block delivery)
## Orchestration Mode (End-to-End Automation)
When the user requests a "complete" or "presentation-ready" deliverable, ppt-creator automatically orchestrates the full pipeline: content creation → data synthesis → chart generation → dual-path PPTX creation (Marp + document-skills:pptx) → chart insertion. This typically delivers TWO complete PPTX files with different styling for user comparison.
**Activation**: Phrases like "complete PPTX", "final deliverable", "ready for presentation"
**Duration**: 4-6 minutes (parallel execution)
**Output**: presentation_marp_with_charts.pptx + presentation_pptx_with_charts.pptx
For orchestration details, see `references/ORCHESTRATION_OVERVIEW.md` (start here), then navigate to specialized guides as needed.
## Core Principles (Must Follow)
- **Information Organization**: Conclusion first, then evidence (Pyramid Principle). Each slide conveys **only 1 core idea**. Headings must be **testable assertion sentences**, not topic labels.
- **Evidence-First**: Use charts/tables/evidence blocks instead of long paragraphs; limit to 3-5 bullet points per slide.
- **Data Visualization**: Chart selection and labeling (axes/units/sources) must comply with references/VIS-GUIDE.md. If data is insufficient, provide "placeholder chart + list of missing fields."
- **Accessibility**: Color and text contrast must meet AA standards (see STYLE-GUIDE). Provide alt/readable descriptions for charts and images.
- **Reusability**: Use consistent naming, stable paths, reproducible output. Do not hard-code random numbers in code.
- **Safety & Dependencies**: Do not scrape the web without permission. Only run scripts when user provides data. If `matplotlib/pandas` are unavailable, fall back to text + placeholder diagram instructions.
## Workflow Overview
**Stage 0 - Archive Input**: Record user's original request, defaults used, and assumptions made.
**Stage 1 - Structure Goals**: Rewrite the goal into "who takes what action when" (clear CTA).
**Stage 2 - Storyline**: Use Pyramid Principle to define "one-sentence conclusion → 3-5 first-level reasons → evidence."
**Stage 3 - Outline & Slide Titles**: Create a 12-15 slide chapter skeleton. Each slide has one assertion-style heading.
**Stage 4 - Evidence & Charts**: Use the Chart Selection Dictionary from VIS-GUIDE. If data is provided, call chartkit.py to generate PNGs; otherwise, create placeholder + required field list.
**Stage 5 - Layout & Accessibility**: Apply STYLE-GUIDE for font sizes, spacing, contrast ratios, color palettes; unify units and decimal places.
**Stage 6 - Speaker Notes**: Generate 45-60 second notes per slide: opening → assertion → evidence explanation → transition.
**Stage 7 - Self-Check & Scoring**: Run CHECKLIST; score with RUBRIC. If score < 75, focus on weakest 3 items, refine, re-score (max 2 iterations).
**Stage 8 - Package Deliverables**: Generate `/output/` directory with slides.md / notes.md / refs.md / assets/*.png. If `python-pptx` is available, export PPTX.
**Stage 9 - Reuse Instructions**: Append a "5-step guide to replace data/colors with your own" at the end of notes.md.
## Resources
### references/INTAKE.md
**Minimal 10-Item Questionnaire** (use defaults if missing):
1. Who is the audience? (Default: general public)
2. Core objective? (Default: "understand and accept" a proposition)
3. Desired action/decision? (Default: agree to move to next step after the meeting)
4. Duration & slide count limit? (Default: 15-20 min, 12-15 slides)
5. Tone & style? (Default: professional, clear, friendly)
6. Topic scope & boundaries? (Default: given topic + 1 layer related)
7. Must-include points/taboos? (Default: none)
8. Available data/tables? (Default: none; can generate structure placeholder + list required fields)
9. Brand & visual constraints? (Default: built-in neutral theme)
10. Deliverable format preference? (Default: slides.md + optional PNG charts; export PPTX if available)
### references/WORKFLOW.md
Detailed step-by-step process from "topic" to "presentation-ready output."
### references/TEMPLATES.md
**Slide Template Library** (assertion-evidence style):
- Cover, Table of Contents, Problem Statement, Opportunity/Goal, Solution Overview, Evidence 1-3, Risk & Mitigation, Case Study/Comparison, Roadmap/Timeline, Conclusion & Actions, Backup Slides
- Micro-templates: Comparison (A vs B), Pyramid Summary, Process 4-Step, KPI Dashboard, Geographic Distribution, Funnel, Pareto, Sensitivity, Cost Structure (Waterfall), Contribution (Stacked)
### references/VIS-GUIDE.md
**Data Visualization Selection & Labeling Standards**:
- Chart Selection Dictionary (common questions → chart types)
- Labeling & units (axes, units, data scope, time range; source in footer)
- Accessibility & contrast (WCAG 2.1 AA: text vs background ≥ 4.5:1; UI elements ≥ 3:1)
- Assertion-Evidence writing tips
### references/STYLE-GUIDE.md
**Layout & Style** (neutral theme, supports brand replacement):
- Canvas: 16:9; safe margins ≥ 48px; grid column spacing 24px
- Fonts: Chinese (Source Han Sans/PingFang/Hiragino Sans), English (Inter/Calibri)
- Font sizes: Heading 34-40, Subheading 24-28, Body 18-22, Footer 14-16
- Line spacing: Heading 1.1, Body 1.3; bullet spacing ≥ 8px
- Color palette (AA compliant): Dark ink #1F2937 / Background #FFFFFF / Accent #2563EB / Emphasis #DC2626
- Components: unified 6-8px border radius; charts and images with 8px padding
- Images: add brief alt descriptions for screen readers
- Page density: ≤ 70 words per slide (excluding captions)
### references/RUBRIC.md
**PPT Quality Scoring Rubric** (100 points; ≥ 75 to deliver):
Each item scored 0-10:
1. **Goal Clarity**: Audience, objective, CTA well-defined
2. **Story Structure**: Pyramid structure complete, hierarchy clear
3. **Slide Assertions**: Headings are "assertion sentences" supported by evidence
4. **Evidence Quality**: Data/cases/citations sufficient, credible, consistent calibration
5. **Chart Fit**: Correct selection, complete labeling, readable
6. **Visual & Accessibility**: Contrast, font size, white space, color compliance
7. **Coherence & Transitions**: Natural chapter and page transitions
8. **Speakability**: 45-60 sec per slide, natural language
9. **Deliverables Complete**: slides.md / notes.md / refs.md / (optional) assets/*.png
10. **Robustness**: Gaps explicitly marked, fallback plan & next steps provided
Self-evaluation process: Run CHECKLIST first, then score each item and write top 3 low-scoring items + improvement actions. If total < 75, apply actions and re-score (max 2 iterations).
### references/CHECKLIST.md
Pre-flight checklist for final quality assurance before delivery.
### references/EXAMPLES.md
**Two Usage Examples**:
- **Example A**: Ultra-simple topic ("coffee") → trigger minimal questionnaire, generate 12-page framework with placeholder charts
- **Example B**: Small business monthly review with attached CSV → parse data, select charts per VIS-GUIDE, call chartkit.py, refine 1-2 iterations if score < 75
### scripts/chartkit.py
**Minimal chart renderer** for ppt-creator.
**Usage**:
```bash
python scripts/chartkit.py \
--data path/to/data.csv \
--type line \
--x date \
--y sales profit \
--out output/assets \
--filename kpi_trend.png \
--title "Monthly KPIs"
```
**Notes**:
- Requires: `pandas`, `matplotlib`
- Fallback: If packages unavailable, print instruction message and exit(0)
- Uses matplotlib defaults for readability (no hard-coded brand colors)
## Advanced Tips
- This skill **complements** (not conflicts with) Anthropic's built-in PowerPoint generation capabilities. Use this skill to produce "high-quality structure & content," then optionally invoke system capabilities to export the final PPTX file.
- For complex data analysis needs, combine with other skills (e.g., data analysis, charting) before invoking ppt-creator.
- The skill is designed to be forgiving: missing information triggers safe defaults rather than blocking progress.
## Version
- v1.2.0: Split ORCHESTRATION.md into 3 files (OVERVIEW: 251 lines, DATA_CHARTS: 141 lines, PPTX: 656 lines)
- v1.1.3: Fixed path references (resources/ → references/), validated by skill-creator review
- v1.1.2: Structure compliance (scripts/ and references/ at top level)
- v1.1.1: Refined for best practices (removed duplication, optimized metadata, fixed absolute paths)
- v1.1.0: Added Orchestration Mode with dual-path PPTX generation (Marp + document-skills:pptx)
- v1.0.0: Initial release

357
ppt-creator/references/CHECKLIST.md Normal file
View File

@@ -0,0 +1,357 @@
# Pre-Flight Checklist
> **Purpose**: Final quality assurance before delivery. Use this checklist **before** running the full RUBRIC.md scoring. This ensures all required elements are present and obvious issues are caught early.
---
## How to Use This Checklist
1. **When**: Run this checklist after completing WORKFLOW Stage 7 (before final scoring)
2. **Method**: Go through each section; check ✓ or note issues
3. **Threshold**: All items in sections 1-5 must be ✓ before delivery; section 6-7 are optional enhancements
4. **Time**: ~5-10 minutes for a 12-15 slide deck
---
## Section 1: Content Completeness
### Slide Count & Structure
- [ ] **Total slide count** matches target range (typically 12-15 slides for 15-20 min presentation)
- [ ] **Cover slide** present with title, subtitle, date, presenter
- [ ] **Table of Contents** present and matches actual sections
- [ ] **Main content slides** (evidence/argument slides) present
- [ ] **Conclusion slide** present with clear call-to-action (CTA)
- [ ] **Backup slides** (if needed) clearly marked "Backup—not presented"
**If any unchecked**: Add missing slides or adjust scope.
---
### Intake & Assumptions
- [ ] **INTAKE.md questions** answered or defaulted (all 10 items)
- [ ] **Assumptions documented** in `/output/notes.md` (if defaults were used)
- [ ] **User's original request** recorded in archive.txt or notes
**If any unchecked**: Review INTAKE.md and document assumptions.
---
## Section 2: Story & Structure
### Pyramid Principle
- [ ] **Main conclusion** stated on cover slide (assertion sentence)
- [ ] **3-5 first-level reasons** identified and each has a section
- [ ] **Evidence slides** support each reason (2-3 slides per reason)
- [ ] **Logical flow**: Conclusion → Reasons → Evidence (not evidence → conclusion)
**If any unchecked**: Revise structure per WORKFLOW Stage 2.
---
### Slide Headings (Assertion-Evidence)
- [ ] **All slide headings are assertion sentences** (testable claims, not topic labels)
- ✅ Example: "Finer grind size extracts flavors faster"
- ❌ Counter-example: "Grind Size" or "Background"
- [ ] **Headings are complete sentences** (subject + verb + object)
- [ ] **Headings match the evidence** shown on the slide
**Quick Test**: Can you agree or disagree with each heading? (If no → it's a topic label, needs revision)
**If any unchecked**: Convert topic labels to assertion sentences (see TEMPLATES.md).
---
## Section 3: Evidence & Data
### Evidence for Claims
- [ ] **Every assertion slide** has supporting evidence (chart, table, example, case study, or diagram)
- [ ] **No unsupported claims** (all "X is true" statements backed by data/citations)
- [ ] **Placeholder charts** (if data unavailable) include:
- Chart type (e.g., "line chart", "bar chart")
- Axes and variables (e.g., "X: month, Y: revenue")
- Required data fields (e.g., "Need: month, revenue_usd")
**If any unchecked**: Add evidence or create detailed placeholders.
---
### Charts & Visualizations
- [ ] **Chart type matches message** (verified against VIS-GUIDE.md Chart Selection Dictionary)
- Trend over time → line/area chart
- Comparison → horizontal bar chart
- Composition → stacked bar / treemap
- Correlation → scatter plot
- [ ] **All charts have axis labels** (X-axis and Y-axis labeled with units)
- [ ] **All charts have data sources** cited in footer (e.g., "Source: XYZ, 2024")
- [ ] **All charts have alt text** for screen readers (brief description of insight)
- [ ] **Chart colors are colorblind-friendly** (avoid red+green; use blue+orange)
**If any unchecked**: Fix chart selection, labeling, or add missing elements.
---
## Section 4: Visual Design & Accessibility
### Typography
- [ ] **Heading font size** ≥ 34pt
- [ ] **Body font size** ≥ 18pt
- [ ] **Footer font size** ≥ 14pt (but not smaller)
- [ ] **Line spacing**: Headings 1.1×, body 1.3-1.5×
- [ ] **Fonts consistent** across all slides (same family for headings, same for body)
**If any unchecked**: Adjust font sizes per STYLE-GUIDE.md.
---
### Color & Contrast
- [ ] **Text contrast** ≥ 4.5:1 against background (normal text <18pt)
- [ ] **Large text contrast** ≥ 3:1 (headings ≥18pt or ≥14pt bold)
- [ ] **UI elements contrast** ≥ 3:1 (chart bars, icons, dividers)
- [ ] **Not relying on color alone** (patterns/labels added for charts with multiple series)
**How to check**: Use WebAIM Contrast Checker or browser DevTools.
**If any unchecked**: Adjust colors to meet WCAG AA standards (see STYLE-GUIDE.md).
---
### Layout & Spacing
- [ ] **Safe margins** ≥ 48px on all sides (content within safe zone)
- [ ] **Bullet points** limited to 3-5 per slide (not 8-10)
- [ ] **Word count** ≤ 70 words per slide (excluding chart labels and footer)
- [ ] **White space** ~40-50% of each slide (not crammed full)
- [ ] **Consistent alignment**: Headings and body text left-aligned (unless intentionally centered)
**If any unchecked**: Increase margins, reduce text, or split into multiple slides.
---
### Images & Alt Text
- [ ] **All images have alt text** (descriptive, 1-2 sentences)
- [ ] **All charts have alt text** (includes key insight, e.g., "Line chart showing 35% revenue growth Jan-Dec 2024")
- [ ] **Images not stretched or distorted** (maintain aspect ratio)
**If any unchecked**: Add alt text or fix image formatting.
---
## Section 5: Speaker Notes & Timing
### Speaker Notes Quality
- [ ] **Every slide has speaker notes** (except backup slides)
- [ ] **Notes are 45-60 seconds per slide** (read aloud to verify)
- [ ] **Notes use natural spoken language** (not bullet points or written prose)
- [ ] **Notes follow structure**: Opening → Core Assertion → Evidence Explanation → Transition
- [ ] **Notes include transitions** to next slide (e.g., "This leads us to...")
**If any unchecked**: Revise notes per WORKFLOW Stage 6.
---
### Total Timing
- [ ] **Total presentation time** matches target (e.g., 15 min = ~15 slides × 60 sec)
- [ ] **Timing buffer** included (5-10% slack for questions/pauses)
**Quick Calc**: Count slides (excluding cover, TOC, backup) × 60 sec = estimated time.
**If any unchecked**: Adjust slide count or speaker notes length.
---
## Section 6: Deliverables (Output Files)
### Required Files
- [ ] `/output/slides.md` exists and is properly formatted (Markdown with YAML frontmatter)
- [ ] `/output/notes.md` exists with full speaker script
- [ ] `/output/refs.md` exists with all citations and sources
- [ ] `/output/assets/` directory exists (even if empty)
- [ ] `/output/README.md` exists explaining file structure
**If any unchecked**: Generate missing files per WORKFLOW Stage 8.
---
### Optional Files (If Applicable)
- [ ] `/output/assets/*.png` charts generated (if data was provided and chartkit.py was used)
- [ ] `/output/presentation.pptx` exported (if python-pptx is available)
- If not available: Instructions for PPTX conversion included in notes.md
**If any unchecked**: Generate charts or add conversion instructions.
---
## Section 7: Polish & Enhancements (Optional but Recommended)
### Consistency Checks
- [ ] **Number formatting consistent**: Same decimal places for same metric (e.g., all percentages to 1 decimal)
- [ ] **Units consistent**: All currency in $ or all in €; don't mix
- [ ] **Date format consistent**: All "Jan 2024" or all "2024-01" (pick one)
- [ ] **Capitalization consistent**: Heading case for all slide titles
---
### Branding (If Applicable)
- [ ] **Brand colors applied** (if provided in INTAKE question 9)
- [ ] **Logo added** to cover slide and/or footer (if applicable)
- [ ] **Brand fonts used** (if specified)
**If unchecked and brand was specified**: Apply per STYLE-GUIDE customization section.
---
### Reuse Guide
- [ ] **"5-Step Reuse Guide" appended** to notes.md (helps user customize later)
- [ ] **chartkit.py usage examples** included (if charts were generated)
- [ ] **Markdown-to-PPTX conversion instructions** included (if PPTX not auto-generated)
**If any unchecked**: Add per WORKFLOW Stage 9.
---
## Section 8: Final Sanity Checks
### Links & References
- [ ] **All internal links work** (e.g., references to "See backup slide 14")
- [ ] **All chart/image paths correct** (no broken image links in slides.md)
- [ ] **All citations complete** (author, year, source name)
---
### Spelling & Grammar
- [ ] **Spell-check run** on all text (slides + notes)
- [ ] **Grammar checked** (especially speaker notes, which are full sentences)
- [ ] **Consistent terminology** (e.g., don't switch between "users" and "customers")
**Tool suggestions**: Grammarly, LanguageTool, or built-in spell-checker.
---
### Edge Cases
- [ ] **Long words or URLs** broken or shortened (avoid overflow)
- [ ] **Special characters** (©, ®, ™, °, etc.) display correctly
- [ ] **Non-English text** (if any) uses correct fonts and displays properly
---
## Checklist Summary
**Count your checks**:
- **Section 1 (Content)**: ___ / 9 items ✓
- **Section 2 (Structure)**: ___ / 8 items ✓
- **Section 3 (Evidence)**: ___ / 9 items ✓
- **Section 4 (Design)**: ___ / 18 items ✓
- **Section 5 (Notes)**: ___ / 7 items ✓
- **Section 6 (Deliverables)**: ___ / 7 items ✓
- **Section 7 (Polish)**: ___ / 7 items ✓ (optional)
- **Section 8 (Sanity)**: ___ / 6 items ✓
**TOTAL**: ___ / 64 core items (sections 1-6)
**PASSING CRITERIA**:
- **Sections 1-6**: All items ✓ (64/64 required)
- **Section 7-8**: Nice-to-have but not required for delivery
---
## What to Do If Items Are Unchecked
### Minor Issues (1-5 unchecked in sections 1-6)
**Action**: Fix the specific items now before moving to RUBRIC scoring.
**Example**:
- Missing alt text on 2 charts → Add alt text
- One topic-label heading → Convert to assertion sentence
- Font size 16pt on one slide → Increase to 18pt
---
### Moderate Issues (6-15 unchecked in sections 1-6)
**Action**: Prioritize the most impactful fixes first:
1. **Structure issues** (Section 2): Fix pyramid structure, convert headings
2. **Evidence gaps** (Section 3): Add missing charts or citations
3. **Accessibility** (Section 4): Fix contrast, font sizes
4. **Speaker notes** (Section 5): Revise timing or add transitions
**Estimated Time**: 15-30 minutes of fixes before re-running checklist.
---
### Major Issues (16+ unchecked in sections 1-6)
**Action**: Return to WORKFLOW Stage 3-4 and rebuild:
- If structure is broken (Section 2): Restart from Stage 3 (Outline)
- If evidence is weak (Section 3): Restart from Stage 4 (Evidence & Charts)
- If design is poor (Section 4): Apply STYLE-GUIDE systematically
**Estimated Time**: 1-2 hours of rework.
---
## After Checklist: Next Steps
Once all core items (Sections 1-6) are ✓:
1. **Proceed to RUBRIC.md** for detailed scoring (0-10 per item, total 100)
2. **If RUBRIC score ≥ 75**: Package deliverables and deliver
3. **If RUBRIC score < 75**: Apply top 3 improvements and re-score (max 2 iterations)
---
## Quick Reference: Most Common Issues
Based on typical PPT creation, here are the **top 10 most common checklist failures**:
1. ❌ **Slide headings are topic labels** (not assertion sentences) → Fix: Convert to testable claims
2. ❌ **Missing source citations on charts** → Fix: Add "Source: XYZ, 2024" in footer
3. ❌ **Font sizes too small** (body <18pt) → Fix: Increase to 18-22pt
4. ❌ **No alt text on charts** → Fix: Add brief description with key insight
5. ❌ **Poor contrast** (<4.5:1) → Fix: Darken text or lighten background
6. ❌ **Too many bullets** (>5 per slide) → Fix: Split into 2 slides or reduce
7. ❌ **No speaker notes** on some slides → Fix: Write 45-60 sec script per slide
8. ❌ **Assumptions not documented** (if defaults used) → Fix: Add to notes.md
9. ❌ **Chart type mismatch** (e.g., pie chart for 7 categories) → Fix: Use bar chart instead
10. ❌ **Inconsistent number formatting** (mixing "1.2M" and "850,000") → Fix: Use same abbreviation style
---
## Checklist Completion Log
**Presentation**: [Title]
**Date**: [YYYY-MM-DD]
**Checked by**: Claude
**Status**: [PASS / FAIL]
**Issues Found**: [Number]
**Issues Fixed**: [Number]
**Remaining**: [Number]
**Notes**:
- [List any issues not yet fixed]
- [Next steps or blockers]
---
**Next Steps**: After all checklist items are ✓, proceed to RUBRIC.md for full scoring.

560
ppt-creator/references/EXAMPLES.md Normal file
View File

@@ -0,0 +1,560 @@
# Usage Examples
> **Purpose**: Demonstrate the full ppt-creator workflow with two realistic scenarios—one ultra-simple topic with no data, and one business scenario with data. These examples show how the skill handles minimal input, applies defaults, generates placeholders, and delivers ≥75 score presentations.
---
## Example A: Ultra-Simple Topic (No Data)
### User Input
```
User: "Make me a presentation about coffee"
```
**What's Missing**:
- Audience
- Goal/objective
- Duration
- Data
- Style/brand
- Everything except the topic
---
### Step 1: Minimal Intake (INTAKE.md)
**Assistant's Response**:
```
I'd love to help! To create the best presentation for you, I have a few quick questions:
1. Who is your audience? (e.g., coffee shop customers, barista trainees, general coffee enthusiasts)
2. What's your main goal? (e.g., educate about brewing methods, convince them to buy premium beans)
3. What action should they take afterward? (e.g., try a new brew method, visit your shop)
4. How long will you present? (e.g., 5 minutes, 15 minutes, 30 minutes)
5. Do you have any data or tables to include? (e.g., sales numbers, survey results, flavor profiles)
If you're not sure about any of these, no problem—I'll use sensible defaults and we can adjust later!
```
**User Reply**:
```
User: "It's for coffee enthusiasts, about 10 minutes, and I want them to improve their home brewing. No data."
```
**Intake Summary**:
| Question | Answer | Source |
|----------|--------|--------|
| 1. Audience | Coffee enthusiasts | User |
| 2. Goal | Improve home brewing | User |
| 3. CTA | Try new methods at home | Inferred |
| 4. Duration | 10 min (~10-12 slides) | User |
| 5. Tone | Professional, friendly | Default |
| 6. Scope | Coffee brewing + basics | Default |
| 7. Must-include | None | Default |
| 8. Data | None (placeholders) | User |
| 9. Brand | Neutral theme | Default |
| 10. Format | slides.md + charts | Default |
---
### Step 2: Structure Goals (WORKFLOW Stage 1)
**One-Sentence Goal**:
```
After this 10-minute presentation, coffee enthusiasts will try at least one new brewing technique within the next week.
```
**CTA**:
```
Pick one technique from today's session and try it with your next cup.
```
---
### Step 3: Storyline (Pyramid Principle)
**Main Conclusion**:
```
Mastering three variables—grind size, water temperature, and brew time—unlocks consistently great coffee at home.
```
**3 First-Level Reasons** (Chapters):
1. **Grind size controls extraction rate**
- Evidence: Grind scale diagram, extraction comparison
2. **Water temperature affects flavor balance**
- Evidence: Temperature vs. compound extraction chart, cold brew example
3. **Brew time determines strength and flavor**
- Evidence: Method timing chart, troubleshooting guide
**Supporting Reason**:
4. **Simple equipment upgrades improve consistency**
- Evidence: Burr vs. blade grinder comparison, tool recommendations
---
### Step 4: Slide Outline (12 Slides)
```
1. COVER: Mastering Three Variables Unlocks Consistently Great Coffee at Home
2. TABLE OF CONTENTS: Grind Size • Water Temperature • Brew Time • Equipment
3. PROBLEM: Inconsistent home coffee wastes premium beans and disappoints drinkers daily
4. Finer grind size extracts flavors faster and more completely
5. Grind size must match your brewing method to avoid over- or under-extraction
6. Water between 195-205°F produces balanced, full-bodied coffee
7. Cold brew demonstrates how low temperature requires extended time
8. Brew time determines coffee strength and flavor balance
9. Each brewing method has an optimal time window for best results
10. Simple equipment upgrades—burr grinder, thermometer, scale—ensure consistency
11. CONCLUSION: Pick one technique from today and try it with your next cup
12. BACKUP: Troubleshooting guide (problem → cause → fix)
```
---
### Step 5: Evidence & Charts (With Placeholders)
**Slide 3 (Problem)**:
- **Chart Type**: Bar chart
- **Placeholder**:
```
Bar chart showing top 3 home brewing complaints:
- "Can't replicate good results": 68%
- "Inconsistent flavor": 52%
- "Wastes expensive beans": 41%
X-axis: Complaint type
Y-axis: % of respondents
Data required: complaint_type (string), percentage (numeric)
Source: [National Coffee Association, 2024 Home Brewing Survey] (placeholder citation)
```
**Slide 4 (Grind Size)**:
- **Chart Type**: Horizontal scale diagram
- **Placeholder**:
```
Horizontal scale showing 5 grind sizes from fine to coarse:
1. Espresso: fine powder (0.3-0.5mm)
2. Pour-over: sand texture (0.7-1.0mm)
3. Drip: table salt (1.0-1.5mm)
4. French press: coarse salt (1.5-2.0mm)
5. Cold brew: peppercorns (2.0-3.0mm)
Each labeled with particle size range and visual icon.
No data required (illustrative diagram).
```
**Slide 6 (Temperature)**:
- **Chart Type**: Stacked area chart
- **Placeholder**:
```
Stacked area chart: Temperature (°F) vs. Extraction %
X-axis: Temperature 160-212°F
Y-axis: Compound extraction %
Three layers:
- Acids (peak at 185°F)
- Sugars (peak at 200°F)
- Bitter compounds (peak at 210°F)
Optimal zone highlighted: 195-205°F
Data required: temperature_f (numeric), acid_pct (numeric), sugar_pct (numeric), bitter_pct (numeric)
Source: [Coffee Chemistry Research, placeholder]
```
---
### Step 6: Speaker Notes Sample (Slide 4)
```
SLIDE 4 SPEAKER NOTES (60 seconds):
[OPENING—10 sec]
"Now that we've seen the problem with inconsistent coffee, let's dive into the first variable: grind size. [CLICK]
[CORE ASSERTION—15 sec]
The key insight here is that finer grind size extracts flavors faster and more completely. Think of it like dissolving sugar: powdered sugar dissolves instantly, while sugar cubes take forever. Same principle.
[EVIDENCE EXPLANATION—25 sec]
This diagram shows five common grind sizes. On the far left, espresso grind looks like fine powder—tons of surface area, so water can extract all the flavors in just 25-30 seconds. On the far right, cold brew grind looks like peppercorns—much less surface area, so you need 12-24 hours to extract the same flavors. Pour-over is right in the middle: looks like sand, brews in 3-4 minutes. Each method needs its grind size. [PAUSE]
[TRANSITION—10 sec]
But here's the catch: you can't just use any grind size with any method. Let's see why matching grind to method is absolutely critical. [CLICK]"
```
---
### Step 7: Self-Check & Scoring (RUBRIC.md)
**Initial Scorecard**:
```
1. Goal Clarity: 9/10 ✓ (audience, goal, CTA clear)
2. Story Structure: 9/10 ✓ (pyramid structure applied)
3. Slide Assertions: 9/10 ✓ (all headings are assertion sentences)
4. Evidence Quality: 7/10 ⚠️ (placeholders detailed but no real data)
5. Chart Fit: 8/10 ✓ (chart types match message)
6. Visual & Accessibility: 9/10 ✓ (neutral theme, WCAG AA compliant)
7. Coherence & Transitions: 8/10 ✓ (smooth flow, transitions in notes)
8. Speakability: 9/10 ✓ (natural language, 45-60 sec per slide)
9. Deliverables Complete: 9/10 ✓ (all files present)
10. Robustness: 9/10 ✓ (placeholders detailed, assumptions documented)
────────────────────────
TOTAL: 86/100 ✓✓ (exceeds threshold, ready to deliver)
```
**Note**: Score is high despite lack of real data because placeholders are detailed and assumptions are clearly documented.
---
### Step 8: Deliverables
**Output Directory**:
```
/output/
├── slides.md (12 slides, 180 lines, Markdown with YAML)
├── notes.md (Full speaker script ~1,200 words + assumptions section)
├── refs.md (Placeholder citations: "NCA 2024 Survey [to be verified]")
├── assets/
│ └── README.txt ("No charts generated; placeholders in slides.md describe required data")
├── README.md (Explains file structure and next steps)
└── presentation.pptx (Not generated; instructions in notes.md for Marp conversion)
```
**Assumptions Section in notes.md**:
```
## Assumptions & Limitations
The following defaults and assumptions were used due to missing information:
1. **Tone & Style**: Professional, clear, friendly (user did not specify)
2. **Brand**: Neutral theme (#2563EB blue, #DC2626 red) - no brand guidelines provided
3. **Data**: No data provided; all charts are placeholders with detailed descriptions and required field lists
4. **Citations**: Placeholder sources used (e.g., "NCA 2024 Survey") - user should verify or replace with actual sources
5. **Format**: Markdown slides (slides.md) delivered; PPTX export requires Marp or pypandoc (see conversion guide below)
**Impact**: Presentation is structurally sound and ready to present, but user should:
- Replace placeholder charts with real data (if available)
- Verify/update citations in refs.md
- Customize colors/fonts per brand guidelines (if applicable)
```
---
### Delivery Message
```
✅ Presentation ready!
TOPIC: Coffee brewing techniques for enthusiasts
DURATION: 10 minutes (12 slides)
SCORE: 86/100 (threshold: 75) ✓✓
DELIVERABLES:
- /output/slides.md (Markdown deck, 12 slides)
- /output/notes.md (Speaker script + assumptions)
- /output/refs.md (Placeholder citations)
- /output/README.md (File structure guide)
NEXT STEPS:
1. Review speaker notes and adjust for your personal style
2. Replace placeholder charts with real data (optional):
- Slide 3: Home brewing complaints survey data
- Slide 6: Temperature vs. extraction data
- Slide 8: Brew time comparison data
3. Convert to PowerPoint:
- Option A: Use Marp (https://marp.app/) to convert slides.md → PPTX
- Option B: Use pypandoc: `pypandoc -o presentation.pptx slides.md`
4. Customize colors/fonts (see STYLE-GUIDE.md)
The presentation is structurally sound and ready to use as-is, or you can enhance with real data later!
```
---
## Example B: Business Monthly Review (With Data)
### User Input
```
User: "Make a PPT for my coffee shop's monthly review. Here's the sales data."
[Attaches CSV file: monthly_sales.csv]
```
**CSV Content**:
```csv
month,revenue_usd,cost_usd,customers,avg_order
Jan,12500,8200,420,29.76
Feb,13200,8500,450,29.33
Mar,15800,9200,530,29.81
Apr,14200,8900,475,29.89
May,16500,9500,560,29.46
Jun,18200,10200,615,29.59
Jul,19800,11000,670,29.55
Aug,18500,10500,625,29.60
Sep,20100,11200,680,29.56
Oct,21500,11800,725,29.66
```
---
### Step 1: Minimal Intake (Partial)
**Assistant's Response**:
```
I see you have sales data for Jan-Oct. To create the best monthly review presentation, a few quick questions:
1. Who is your audience? (e.g., business partners, investors, staff meeting)
2. What's the main goal? (e.g., celebrate growth, identify issues, plan Q4)
3. What action should they take? (e.g., approve budget, adjust strategy)
4. How long? (e.g., 10 min, 20 min)
```
**User Reply**:
```
User: "It's for my business partner, 15 minutes, we need to decide on Q4 budget allocation."
```
**Intake Summary**:
| Question | Answer | Source |
|----------|--------|--------|
| 1. Audience | Business partner | User |
| 2. Goal | Review performance, decide Q4 budget | User |
| 3. CTA | Approve Q4 budget allocation | Inferred |
| 4. Duration | 15 min (~15 slides) | User |
| 5. Tone | Professional | Default |
| 6. Scope | Jan-Oct performance + Q4 plan | Inferred |
| 7. Data | monthly_sales.csv | User |
| 8. Brand | Neutral theme | Default |
---
### Step 2: Data Analysis
**Quick Analysis of CSV**:
- Revenue: $12.5K (Jan) → $21.5K (Oct) = **+72% growth**
- Customers: 420 (Jan) → 725 (Oct) = **+73% growth**
- Avg Order: ~$29.50 (stable, ±0.5%)
- Margin: ~35-45% (cost/revenue ratio improving)
**Key Insights**:
1. Strong revenue and customer growth (Q3 acceleration)
2. Average order value stable (good retention)
3. Margin improving (cost growth slower than revenue)
---
### Step 3: Storyline
**Main Conclusion**:
```
Jan-Oct performance exceeded plan by 15%, driven by customer growth and stable spending—Q4 budget should focus on capacity expansion.
```
**3 Reasons**:
1. **Revenue grew 72% YTD with Q3 acceleration**
- Evidence: Revenue trend line, Q3 growth rate
2. **Customer count drove growth; avg order remained stable**
- Evidence: Customers vs. revenue bar chart, avg order trendline
3. **Improving margins create room for Q4 investment**
- Evidence: Margin waterfall chart, cost vs. revenue comparison
---
### Step 4: Slide Outline (14 Slides)
```
1. COVER: Jan-Oct Performance Exceeded Plan by 15%—Time to Invest in Q4 Capacity
2. TABLE OF CONTENTS: Revenue Growth • Customer Trends • Margins • Q4 Plan
3. EXECUTIVE SUMMARY: Three key wins and one opportunity
4. Revenue grew 72% from Jan ($12.5K) to Oct ($21.5K), with sharp Q3 acceleration
5. Q3 monthly growth averaged 8%, double the Q1-Q2 pace of 4%
6. Customer count increased 73%, closely tracking revenue growth
7. Average order value remained stable at ~$29.50, showing strong retention
8. Improving cost efficiency drove margins from 34% to 45%
9. Margin expansion of 11 points creates $3K/month reinvestment capacity
10. OPPORTUNITY: Q4 budget should prioritize capacity (staff, inventory, equipment)
11. RECOMMENDATION: Allocate $10K Q4 budget: 40% staff, 30% inventory, 30% equipment
12. CONCLUSION & CTA: Approve Q4 budget to sustain momentum into 2025
13. BACKUP: Detailed cost breakdown by category
14. BACKUP: Q4 budget line-item details
```
---
### Step 5: Charts Generated (chartkit.py)
**Slide 4 (Revenue Trend)**:
```bash
python scripts/chartkit.py \
--data monthly_sales.csv \
--type line \
--x month \
--y revenue_usd \
--out output/assets \
--filename revenue_trend.png \
--title "Monthly Revenue (Jan-Oct 2024)"
```
**Output**: `/output/assets/revenue_trend.png` (line chart with upward trend, Q3 spike annotated)
**Slide 6 (Customers + Revenue)**:
```bash
python scripts/chartkit.py \
--data monthly_sales.csv \
--type bar \
--x month \
--y customers revenue_usd \
--out output/assets \
--filename customers_revenue.png \
--title "Customer Count & Revenue Growth"
```
**Output**: `/output/assets/customers_revenue.png` (grouped bar chart)
**Slide 8 (Margin Waterfall)**:
- **Manual annotation** (chartkit.py doesn't do waterfall natively):
- Start: 34% margin (Jan)
- +11 points improvement (Jan → Oct)
- End: 45% margin (Oct)
- **Placeholder description** + "Consider using Excel or specialized tool for waterfall; data available in CSV"
---
### Step 6: Speaker Notes Sample (Slide 4)
```
SLIDE 4 SPEAKER NOTES (55 seconds):
[OPENING—10 sec]
"Let's start with the headline: revenue. [CLICK]
[CORE ASSERTION—15 sec]
As you can see, revenue grew 72% from January—when we brought in $12,500—to October, when we hit $21,500. That's nearly double in 10 months. But what's really interesting is when this growth happened.
[EVIDENCE EXPLANATION—20 sec]
Notice the slope change in July. From January to June, we were growing steadily at about 4% per month—solid, but predictable. Then in July, August, September, we jumped to 8% monthly growth. That Q3 spike is what pushed us past our annual plan by 15%. [PAUSE]
[TRANSITION—10 sec]
Now, the question is: what drove this? Was it more customers, or were people spending more per visit? Let's break that down on the next slide. [CLICK]"
```
---
### Step 7: Self-Check & Scoring
**Initial Scorecard**:
```
1. Goal Clarity: 10/10 ✓
2. Story Structure: 9/10 ✓
3. Slide Assertions: 9/10 ✓
4. Evidence Quality: 9/10 ✓ (real data, sources cited)
5. Chart Fit: 9/10 ✓ (line for trend, bar for comparison)
6. Visual & Accessibility: 9/10 ✓
7. Coherence & Transitions: 8/10 ✓
8. Speakability: 9/10 ✓
9. Deliverables Complete: 10/10 ✓
10. Robustness: 9/10 ✓
────────────────────────
TOTAL: 91/100 ✓✓✓ (excellent, ready to deliver)
```
---
### Step 8: Deliverables
**Output Directory**:
```
/output/
├── slides.md (14 slides, 220 lines)
├── notes.md (Full speaker script ~1,500 words)
├── refs.md (Source: "Internal sales database, Jan-Oct 2024")
├── assets/
│ ├── revenue_trend.png
│ ├── customers_revenue.png
│ ├── avg_order_trend.png
│ ├── margin_comparison.png
│ └── (4 PNG charts total)
├── README.md
└── presentation.pptx (If python-pptx available; else conversion instructions)
```
---
### Delivery Message
```
✅ Monthly review presentation ready!
TOPIC: Coffee shop Jan-Oct performance + Q4 budget
AUDIENCE: Business partner
DURATION: 15 minutes (14 slides)
SCORE: 91/100 (threshold: 75) ✓✓✓
DELIVERABLES:
- /output/slides.md (Markdown deck, 14 slides)
- /output/notes.md (Speaker script with data assumptions)
- /output/refs.md (Data source: Internal sales database)
- /output/assets/ (4 PNG charts generated from your CSV)
- /output/README.md
KEY INSIGHTS:
- Revenue +72% (Jan $12.5K → Oct $21.5K)
- Q3 acceleration: 8% monthly growth vs. 4% in Q1-Q2
- Customer count +73%; avg order stable ~$29.50
- Margins improved 34% → 45% (11-point gain)
RECOMMENDATION: Approve $10K Q4 budget (40% staff, 30% inventory, 30% equipment)
NEXT STEPS:
1. Review slides and notes
2. Adjust Q4 budget breakdown if needed (currently in slide 11)
3. Rehearse with notes (15 min total timing)
4. Export to PPTX if needed (instructions in README)
```
---
## Key Takeaways from Examples
### Example A (No Data):
- **Works with minimal input**: Just "coffee" → 12-slide deck
- **Defaults applied smartly**: Professional tone, neutral theme, 10-min duration
- **Placeholders are detailed**: Not just "add chart here" but specific field lists
- **High score despite no data**: 86/100 because structure, assertions, and accessibility are solid
- **User can enhance later**: Replace placeholders with real data anytime
### Example B (With Data):
- **Data drives insights**: CSV analysis → 3 key insights → storyline
- **Charts auto-generated**: chartkit.py creates 4 PNGs in minutes
- **Higher evidence score**: 9/10 vs. 7/10 because real data > placeholders
- **Business-ready**: 91/100 score, ready to present without further edits
- **Actionable CTA**: "Approve Q4 budget" with specific allocation
---
## Comparison Table
| Aspect | Example A (No Data) | Example B (With Data) |
|--------|---------------------|------------------------|
| **Topic** | Coffee brewing (general) | Coffee shop monthly review |
| **User Input** | 1 sentence + 4 Q&A answers | CSV file + 3 Q&A answers |
| **Slide Count** | 12 slides | 14 slides |
| **Charts** | 5 placeholders | 4 real PNGs (+ 1 placeholder) |
| **Evidence Score** | 7/10 | 9/10 |
| **Total Score** | 86/100 | 91/100 |
| **Prep Time** | ~10 min (all placeholders) | ~15 min (data analysis + chartkit) |
| **Delivery State** | Ready to present (or add data later) | Ready to present now |
---
## When to Use Which Approach
### Use "No Data" Approach (Example A) When:
- User has a topic but no supporting data yet
- Presentation is educational/conceptual (not data-driven)
- User wants structure first, will add data later
- Timeline is tight (need deck in < 1 hour)
### Use "With Data" Approach (Example B) When:
- User provides CSV, Excel, or JSON files
- Presentation is business/analytical (reviews, reports, pitches)
- Data-driven insights are core to the message
- User wants polished, presentation-ready output immediately
---
**Next Steps**: Use these examples as templates for your own presentations. Adjust storyline, charts, and speaker notes to fit your specific topic and audience.

225
ppt-creator/references/INTAKE.md Normal file
View File

@@ -0,0 +1,225 @@
# Minimal Intake Questionnaire (10 Items)
> **Purpose**: Gather essential context to produce a high-quality presentation. If the user doesn't provide information after 2 prompts, use the **safe default** for each item and clearly document the assumption in speaker notes.
---
## 1. Who is the audience?
**Question**: Who will be viewing/listening to this presentation?
**Examples**:
- Executive leadership team
- Technical engineers
- General public / consumers
- Sales prospects
- Students / trainees
- Board members
- Investors
**Default if missing**: General public (educated adults with no specialized background)
**Impact**: Determines technical depth, jargon usage, and evidence types.
---
## 2. What is the core objective?
**Question**: What do you want the audience to understand, believe, or feel?
**Examples**:
- Understand a new product feature
- Accept a proposal or recommendation
- Learn how to use a tool
- Appreciate the severity of a problem
- Gain confidence in a solution
**Default if missing**: "Understand and accept" the main proposition
**Impact**: Shapes the storyline and emphasis throughout the deck.
---
## 3. What is the desired action or decision?
**Question**: What specific action should the audience take after this presentation?
**Examples**:
- Approve budget allocation
- Agree to pilot/trial
- Provide feedback by [date]
- Adopt a new process
- Make a purchase decision
- Schedule a follow-up meeting
**Default if missing**: Agree to move to the next step after the meeting
**Impact**: Defines the call-to-action (CTA) on the closing slide.
---
## 4. What is the presentation duration and slide count limit?
**Question**: How long will you present, and are there any slide count constraints?
**Examples**:
- 5-minute pitch (5-7 slides)
- 15-minute review (12-15 slides)
- 30-minute workshop (20-25 slides)
- 60-minute lecture (30-40 slides)
**Default if missing**: 15-20 minutes, 12-15 slides
**Impact**: Controls depth per slide and total slide count.
---
## 5. What tone and style should the presentation have?
**Question**: How should the presentation feel and sound?
**Examples**:
- Professional and formal
- Friendly and conversational
- Inspirational and aspirational
- Technical and precise
- Urgent and persuasive
**Default if missing**: Professional, clear, and friendly
**Impact**: Affects language choice, speaker notes tone, and visual style.
---
## 6. What is the topic scope and boundaries?
**Question**: What should be included and what should be excluded?
**Examples**:
- Focus only on Q1 results, not Q2 projections
- Cover product features but not pricing
- Technical implementation only, no business case
- High-level overview, no detailed specs
**Default if missing**: The given topic name plus one layer of directly related context
**Impact**: Prevents scope creep and ensures focused messaging.
---
## 7. Are there must-include points or forbidden topics?
**Question**: Are there specific messages you must convey or topics you must avoid?
**Examples**:
- Must mention: regulatory compliance requirement
- Must avoid: competitor names, unannounced features, sensitive financial data
- Required disclaimer: "Subject to board approval"
**Default if missing**: None (no mandatory inclusions or exclusions)
**Impact**: Ensures compliance and strategic messaging alignment.
---
## 8. Do you have data or tables available?
**Question**: Can you provide data files (CSV, Excel, JSON) or tables for visualization?
**Examples**:
- Sales data by month
- User survey results
- Cost breakdown by category
- Performance metrics over time
**Default if missing**: No data available; generate placeholder charts with a list of required data fields
**Impact**: Determines whether to generate actual charts (via chartkit.py) or placeholders.
---
## 9. Are there brand or visual constraints?
**Question**: Are there specific colors, fonts, logos, or templates you must use?
**Examples**:
- Company brand colors: #FF5733, #33A1FF
- Required logo placement: top-right corner
- Mandatory template: [template file]
- Font restrictions: Arial only
**Default if missing**: Built-in neutral theme (dark ink #1F2937, accent #2563EB, emphasis #DC2626)
**Impact**: Affects color palette and visual components in STYLE-GUIDE.
---
## 10. What deliverable format do you prefer?
**Question**: How do you want to receive the final presentation?
**Options**:
- Markdown slides (Marp/Reveal.js compatible)
- PowerPoint (.pptx)
- Google Slides export
- PDF for print
- All of the above
**Default if missing**: slides.md (Markdown) + optional PNG charts; export to PPTX if `python-pptx` is available
**Impact**: Determines final export step in Stage 8.
---
## Usage Instructions
1. **First pass**: Ask all 10 questions in a user-friendly format (e.g., "I have a few quick questions to help me create the best presentation for you...")
2. **Second prompt**: If critical items (1, 2, 3, 4, 8) are still missing, ask again with examples.
3. **Apply defaults**: If still no response, use the safe default for each missing item.
4. **Document assumptions**: In `/output/notes.md`, include a "Assumptions & Limitations" section listing all defaults used and their potential impact.
---
## Example Interaction
**User**: "Make me a presentation about coffee."
**Assistant**: "I'd love to help! To create the best presentation for you, I have a few quick questions:
1. Who is your audience? (e.g., coffee shop customers, barista trainees, general coffee enthusiasts)
2. What's your main goal? (e.g., educate about brewing methods, convince them to buy premium beans, explain coffee origins)
3. What action should they take afterward? (e.g., try a new brew method, visit your shop, change their coffee habits)
4. How long will you present? (e.g., 5 minutes, 15 minutes, 30 minutes)
5. Do you have any data or tables to include? (e.g., sales numbers, survey results, flavor profiles)
If you're not sure about any of these, no problem—I'll use sensible defaults and we can adjust later!"
**User**: "It's for coffee enthusiasts, about 10 minutes, and I want them to improve their home brewing. No data."
**Assistant**: "Perfect! I'll create a 10-minute presentation (about 10-12 slides) for coffee enthusiasts focused on improving home brewing techniques. I'll use a friendly, educational tone and aim for them to try new methods at home. Since you don't have data, I'll include helpful diagrams and placeholder charts where data would be useful (like extraction curves or flavor profiles). Let me get started!"
[Proceeds to Stage 0 of WORKFLOW.md with documented assumptions]
---
## Safe Defaults Summary Table
| # | Question | Safe Default |
|---|----------|--------------|
| 1 | Audience | General public (educated adults) |
| 2 | Core objective | "Understand and accept" the proposition |
| 3 | Desired action | Agree to move to next step |
| 4 | Duration & slides | 15-20 min, 12-15 slides |
| 5 | Tone & style | Professional, clear, friendly |
| 6 | Topic scope | Given topic + 1 layer related |
| 7 | Must-include/taboos | None |
| 8 | Available data | None (use placeholders) |
| 9 | Brand constraints | Neutral theme (see STYLE-GUIDE) |
| 10 | Format preference | slides.md + optional charts/PPTX |
---
**Next step**: Once intake is complete, proceed to WORKFLOW.md Stage 0.

140
ppt-creator/references/ORCHESTRATION_DATA_CHARTS.md Normal file
View File

@@ -0,0 +1,140 @@
# ORCHESTRATION_DATA_CHARTS.md
> **Purpose**: Detailed specifications for Stage 8b (Data Synthesis) and Stage 8c (Chart Generation) in orchestration mode.
>
> **Navigation**: [← Back to Overview](ORCHESTRATION_OVERVIEW.md) | [Next: PPTX Creation →](ORCHESTRATION_PPTX.md)
---
## Stage 8b: Data Synthesis
### When to Synthesize Data
Generate synthetic data when:
1. refs.md contains data specifications (e.g., "Solar LCOE: $0.38/kWh → $0.05/kWh")
2. User did NOT upload CSV/Excel files
3. Charts require data to render (not just conceptual diagrams)
### Data Synthesis Guidelines
**Source of Truth**: Use refs.md data specifications
Example refs.md content:
```markdown
## Chart 1: Renewable Energy Cost Trends (2010-2024)
Data source: IRENA Renewable Power Generation Costs 2024
- Solar PV LCOE: $0.38/kWh (2010) → $0.05/kWh (2024), -87% decline
- Onshore Wind LCOE: $0.09/kWh (2010) → $0.04/kWh (2024), -56% decline
- Coal baseline (comparison): $0.11/kWh (stable)
Required CSV: data/cost_trend.csv
Columns: year, solar_pv_cost, onshore_wind_cost, coal_cost
```
**Python Code Pattern** (generate CSV):
```python
import pandas as pd
import numpy as np
# Synthesize cost_trend.csv
years = list(range(2010, 2025))
solar_costs = np.linspace(0.38, 0.05, len(years)) # -87% decline
wind_costs = np.linspace(0.09, 0.04, len(years)) # -56% decline
coal_costs = [0.11] * len(years) # stable baseline
df = pd.DataFrame({
'year': years,
'solar_pv_cost': solar_costs,
'onshore_wind_cost': wind_costs,
'coal_cost': coal_costs
})
df.to_csv('output/data/cost_trend.csv', index=False)
```
**Key Principles**:
- Match refs.md specifications exactly (start/end values, trends)
- Add realistic noise (±3-5%) to avoid straight lines
- Use authoritative source calibration (IRENA/IEA/IPCC/WHO/World Bank)
- Document assumptions in data file headers or README
**File Organization**:
```
/output/data/
├── cost_trend.csv
├── capacity_growth.csv
├── employment.csv
├── solar_roi.csv
└── README.md (documents synthesis methodology)
```
---
## Stage 8c: Chart Generation
### Chart Generation Script Pattern
Create a comprehensive `generate_charts.py` script that reads CSV data and generates all PNG charts.
**Template Structure**:
```python
#!/usr/bin/env python3
"""Generate all charts for presentation"""
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib
matplotlib.use('Agg') # Non-interactive backend
# Chinese font configuration
plt.rcParams['font.sans-serif'] = ['SimHei', 'Arial Unicode MS', 'DejaVu Sans']
plt.rcParams['axes.unicode_minus'] = False
def create_chart_1():
"""Cost Trend Line Chart"""
df = pd.read_csv('data/cost_trend.csv')
fig, ax = plt.subplots(figsize=(10, 6))
ax.plot(df['year'], df['solar_pv_cost'], marker='o', label='太阳能光伏', linewidth=2)
ax.plot(df['year'], df['onshore_wind_cost'], marker='s', label='陆上风能', linewidth=2)
ax.plot(df['year'], df['coal_cost'], linestyle='--', label='煤电(对比)', linewidth=2, alpha=0.7)
ax.set_xlabel('年份', fontsize=12)
ax.set_ylabel('平准化度电成本 ($/kWh)', fontsize=12)
ax.set_title('可再生能源成本趋势 (2010-2024)', fontsize=14, fontweight='bold')
ax.legend(fontsize=11)
ax.grid(True, alpha=0.3)
plt.tight_layout()
plt.savefig('assets/cost_trend.png', dpi=180, bbox_inches='tight')
plt.close()
print("✓ Generated: assets/cost_trend.png")
# Call all chart generation functions
if __name__ == "__main__":
create_chart_1()
create_chart_2()
# ... (all charts)
print("\n✅ All charts generated successfully")
```
**Execution Pattern**:
```bash
# Background execution to avoid blocking
cd /output
python generate_charts.py
# OR using uv if dependencies unavailable
uv run --with pandas --with matplotlib generate_charts.py
```
**Quality Standards**:
- DPI: 180 (presentation-quality)
- Size: 10×6 inches (fits 16:9 slide with margins)
- File format: PNG with transparency
- Color palette: Use colorblind-friendly colors from STYLE-GUIDE.md
- Labels: Chinese/English matching slide language
- Source citation: Add footnote to chart (e.g., "数据来源: IRENA 2024")
---
**Navigation**: [← Back to Overview](ORCHESTRATION_OVERVIEW.md) | [Next: PPTX Creation →](ORCHESTRATION_PPTX.md)

248
ppt-creator/references/ORCHESTRATION_OVERVIEW.md Normal file
View File

@@ -0,0 +1,248 @@
# ORCHESTRATION_OVERVIEW.md
> **Purpose**: Enable ppt-creator to act as an end-to-end workflow coordinator, automatically managing data synthesis, chart generation, PPTX creation, and chart insertion to deliver complete, presentation-ready PowerPoint files with real visualizations.
>
> **Note**: This document provides the orchestration overview. For detailed implementation, see the specialized guides below.
---
## Table of Contents
1. [When to Use Orchestration Mode](#when-to-use-orchestration-mode)
2. [Orchestration Workflow](#orchestration-workflow)
3. **Stage 8b-8c: Data & Charts** → See [ORCHESTRATION_DATA_CHARTS.md](ORCHESTRATION_DATA_CHARTS.md)
4. **Stage 8d-8e: PPTX Creation & Chart Insertion** → See [ORCHESTRATION_PPTX.md](ORCHESTRATION_PPTX.md)
---
## When to Use Orchestration Mode
### Activation Triggers
Orchestration mode activates when user request includes ANY of these patterns:
**Explicit Requests**:
- "Generate complete PPTX with real charts"
- "Create final deliverable ready for presentation"
- "Export to PowerPoint with all visualizations"
- "Deliver presentation-ready file with data"
**Implicit Indicators**:
- User uploads reference documents + requests "presentation"
- Request mentions "final deliverable" or "ready to present"
- User asks for "all assets generated"
- Context suggests this is for actual delivery (meeting/pitch/review)
### Decision Tree
```
User Request
│
├─ Contains "Markdown only" → Manual Mode
├─ Contains "slides.md" only → Manual Mode
├─ Contains "complete PPTX" → Orchestration Mode ✓
├─ Contains "final deliverable" → Orchestration Mode ✓
├─ Contains "presentation-ready" → Orchestration Mode ✓
└─ Ambiguous → Ask user: "Should I create complete PPTX with charts (orchestration mode) or Markdown only (manual mode)?"
```
### User Communication
When activating orchestration mode, inform user explicitly:
```
🎯 Activating end-to-end orchestration mode to deliver complete PPTX with real charts.
Pipeline stages:
✓ Stage 1-7: Content creation (slides.md, notes.md, refs.md)
⏳ Stage 8b: Data synthesis (generating CSV files from refs.md specs)
⏳ Stage 8c: Chart generation (matplotlib rendering)
⏳ Stage 8d: Dual-path PPTX creation (Marp + document-skills:pptx in parallel)
⏳ Stage 8e: Dual-path chart insertion (2 final PPTX versions)
📦 Will deliver TWO versions:
- presentation_marp.pptx (Marp CLI export, native Marp styling)
- presentation_pptx.pptx (document-skills:pptx, reveal.js styling)
Estimated time: 4-6 minutes
```
---
## Orchestration Workflow
### Complete Pipeline (Stages 8b-8e)
After standard content creation (Stages 0-7 → slides.md/notes.md/refs.md), orchestration extends Stage 8:
```
Stage 8: Package Deliverables
│
├─ 8a: Package Markdown deliverables ✓ (baseline)
│ └─ Output: /output/slides.md, /output/notes.md, /output/refs.md
│
├─ 8b: Synthesize Data (if needed)
│ ├─ Check: Does refs.md specify data requirements?
│ ├─ Check: Did user provide data files?
│ └─ If no user data: Generate synthetic CSV files
│ → Output: /output/data/*.csv
│
├─ 8c: Generate Charts
│ ├─ Read: /output/refs.md (chart specifications)
│ ├─ Read: /output/data/*.csv (generated or user-provided)
│ ├─ Execute: Python/matplotlib chart generation
│ └─ Output: /output/assets/*.png (180 DPI, optimized)
│
├─ 8d: Create PPTX
│ ├─ Tool: Task (subagent_type: document-skills:pptx)
│ ├─ Input: /output/slides.md content
│ ├─ Action: Convert Markdown to PPTX structure
│ └─ Output: /output/presentation.pptx (with placeholder chart text)
│
└─ 8e: Insert Charts
├─ Tool: Task (subagent_type: document-skills:pptx editing)
├─ Input: /output/assets/*.png + slide mapping
├─ Action: Replace placeholder text with chart images
└─ Output: /output/presentation_with_charts.pptx ✓ FINAL
```
### Coordination Approach
Use **sequential execution with quality gates**:
- Stages 8b-c can run in parallel (data synthesis + chart generation)
- Stage 8d waits for 8c completion (PPTX needs chart list)
- Stage 8e waits for 8d completion (insertion needs PPTX file)
---
## Stage 8b: Data Synthesis
### When to Synthesize Data
Generate synthetic data when:
1. refs.md contains data specifications (e.g., "Solar LCOE: $0.38/kWh → $0.05/kWh")
2. User did NOT upload CSV/Excel files
3. Charts require data to render (not just conceptual diagrams)
### Data Synthesis Guidelines
**Source of Truth**: Use refs.md data specifications
Example refs.md content:
```markdown
## Chart 1: Renewable Energy Cost Trends (2010-2024)
Data source: IRENA Renewable Power Generation Costs 2024
- Solar PV LCOE: $0.38/kWh (2010) → $0.05/kWh (2024), -87% decline
- Onshore Wind LCOE: $0.09/kWh (2010) → $0.04/kWh (2024), -56% decline
- Coal baseline (comparison): $0.11/kWh (stable)
Required CSV: data/cost_trend.csv
Columns: year, solar_pv_cost, onshore_wind_cost, coal_cost
```
**Python Code Pattern** (generate CSV):
```python
import pandas as pd
import numpy as np
# Synthesize cost_trend.csv
years = list(range(2010, 2025))
solar_costs = np.linspace(0.38, 0.05, len(years)) # -87% decline
wind_costs = np.linspace(0.09, 0.04, len(years)) # -56% decline
coal_costs = [0.11] * len(years) # stable baseline
df = pd.DataFrame({
'year': years,
'solar_pv_cost': solar_costs,
'onshore_wind_cost': wind_costs,
'coal_cost': coal_costs
})
df.to_csv('output/data/cost_trend.csv', index=False)
```
**Key Principles**:
- Match refs.md specifications exactly (start/end values, trends)
- Add realistic noise (±3-5%) to avoid straight lines
- Use authoritative source calibration (IRENA/IEA/IPCC/WHO/World Bank)
- Document assumptions in data file headers or README
**File Organization**:
```
/output/data/
├── cost_trend.csv
├── capacity_growth.csv
├── employment.csv
├── solar_roi.csv
└── README.md (documents synthesis methodology)
```
---
## Stage 8c: Chart Generation
### Chart Generation Script Pattern
Create a comprehensive `generate_charts.py` script that reads CSV data and generates all PNG charts.
**Template Structure**:
```python
#!/usr/bin/env python3
"""Generate all charts for presentation"""
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib
matplotlib.use('Agg') # Non-interactive backend
# Chinese font configuration
plt.rcParams['font.sans-serif'] = ['SimHei', 'Arial Unicode MS', 'DejaVu Sans']
plt.rcParams['axes.unicode_minus'] = False
def create_chart_1():
"""Cost Trend Line Chart"""
df = pd.read_csv('data/cost_trend.csv')
fig, ax = plt.subplots(figsize=(10, 6))
ax.plot(df['year'], df['solar_pv_cost'], marker='o', label='太阳能光伏', linewidth=2)
ax.plot(df['year'], df['onshore_wind_cost'], marker='s', label='陆上风能', linewidth=2)
ax.plot(df['year'], df['coal_cost'], linestyle='--', label='煤电(对比)', linewidth=2, alpha=0.7)
ax.set_xlabel('年份', fontsize=12)
ax.set_ylabel('平准化度电成本 ($/kWh)', fontsize=12)
ax.set_title('可再生能源成本趋势 (2010-2024)', fontsize=14, fontweight='bold')
ax.legend(fontsize=11)
ax.grid(True, alpha=0.3)
plt.tight_layout()
plt.savefig('assets/cost_trend.png', dpi=180, bbox_inches='tight')
plt.close()
print("✓ Generated: assets/cost_trend.png")
# Call all chart generation functions
if __name__ == "__main__":
create_chart_1()
create_chart_2()
# ... (all charts)
print("\n✅ All charts generated successfully")
```
**Execution Pattern**:
```bash
# Background execution to avoid blocking
cd /output
python generate_charts.py
# OR using uv if dependencies unavailable
uv run --with pandas --with matplotlib generate_charts.py
```
**Quality Standards**:
- DPI: 180 (presentation-quality)
- Size: 10×6 inches (fits 16:9 slide with margins)
- File format: PNG with transparency
- Color palette: Use colorblind-friendly colors from STYLE-GUIDE.md
- Labels: Chinese/English matching slide language
- Source citation: Add footnote to chart (e.g., "数据来源: IRENA 2024")
---

659
ppt-creator/references/ORCHESTRATION_PPTX.md Normal file
View File

@@ -0,0 +1,659 @@
# ORCHESTRATION_PPTX.md
> **Purpose**: Comprehensive specifications for Stage 8d (Dual-Path PPTX Creation) and Stage 8e (Chart Insertion) in orchestration mode.
>
> **Navigation**: [← Back to Overview](ORCHESTRATION_OVERVIEW.md) | [← Data & Charts](ORCHESTRATION_DATA_CHARTS.md)
>
> **Note**: This is a comprehensive reference (650 lines) covering both Marp CLI and document-skills:pptx paths with complete implementation details, quality gates, error handling, and examples.
---
## Stage 8d: Dual-Path PPTX Creation (Parallel Execution)
**Strategy**: Launch TWO parallel sub-agents to generate PPTX files using different technologies. This preserves existing Marp capabilities while adding document-skills:pptx support.
### Why Dual-Path?
**Problem**: ppt-creator internally uses **Marp-formatted Markdown** (with Marp-specific YAML frontmatter and directives), but **document-skills:pptx** uses reveal.js/HTML and cannot properly parse Marp syntax.
**Solution**: Support BOTH paths simultaneously:
- **Path A (Marp CLI)**: Native Marp export → preserves Marp themes, directives, and styling
- **Path B (document-skills:pptx)**: Strip Marp directives → convert to PowerPoint → reveal.js-style output
Both paths run **in parallel** (single message with two Task calls), delivering whichever succeeds (or both for user choice).
---
### Path A: Marp CLI Export
**Purpose**: Export slides.md to PPTX using official Marp CLI, preserving native Marp styling
**Task Invocation**:
```
Tool: Task
subagent_type: general-purpose
description: Marp CLI PPTX generation
prompt: |
Generate PPTX from Marp-formatted slides using Marp CLI.
CRITICAL: This path preserves Marp-specific features (themes, directives, styling).
Steps:
1. Check Marp CLI installation:
which marp || npm list -g @marp-team/marp-cli
2. If Marp CLI not found, install it:
npm install -g @marp-team/marp-cli
If npm fails:
- Try: brew install marp-cli (macOS)
- Document error and skip to fallback
3. Export slides.md to PPTX:
cd output
marp slides.md -o presentation_marp.pptx --allow-local-files --html
Options explained:
- --allow-local-files: Enable chart image embedding
- --html: Preserve HTML directives (speaker notes)
4. Quality checks:
- File exists: /output/presentation_marp.pptx
- File size: 200-500KB (12-15 slides with embedded fonts)
- No "ERROR" in marp output
5. If successful, report:
"✓ Path A complete: presentation_marp.pptx (Marp-styled, [FILE_SIZE]KB)"
Fallback: If any step fails, document error in /output/README.md and exit gracefully
```
**Expected Output**:
- File: `/output/presentation_marp.pptx` (~200-500KB)
- Styling: Marp theme from YAML frontmatter (e.g., `theme: default`, custom CSS)
- Charts: Text placeholders initially (will be replaced in Stage 8e-A)
- Notes: Speaker notes from `<!-- NOTES: ... -->` comments
- Font embedding: Marp auto-embeds fonts
**Marp Installation Verification**:
```bash
# Check if Marp CLI is available
which marp
# OR
npm list -g @marp-team/marp-cli
# Expected output:
/usr/local/bin/marp
# OR
@marp-team/marp-cli@3.x.x
```
**Installation Methods** (if not found):
```bash
# Method 1: npm (preferred)
npm install -g @marp-team/marp-cli
# Method 2: Homebrew (macOS)
brew install marp-cli
# Method 3: Docker (fallback)
docker run --rm -v ${PWD}:/workspace marpteam/marp-cli slides.md -o presentation_marp.pptx
```
**Common Marp Errors & Fixes**:
| Error | Cause | Fix |
|-------|-------|-----|
| `marp: command not found` | Marp CLI not installed | Run `npm install -g @marp-team/marp-cli` |
| `EACCES` permission error | npm global directory not writable | Use `sudo` or fix npm permissions |
| `Cannot find module` | Incomplete installation | Reinstall: `npm uninstall -g @marp-team/marp-cli && npm install -g @marp-team/marp-cli` |
| Image embedding fails | Missing `--allow-local-files` | Add flag: `marp slides.md -o out.pptx --allow-local-files` |
**Fallback**: If Marp CLI unavailable after installation attempts:
- Skip Path A
- Document in `/output/README.md`: "Marp CLI unavailable, delivered document-skills:pptx version only"
- Proceed with Path B only
---
### Path B: document-skills:pptx Export
**Purpose**: Convert Markdown to PPTX using Anthropic's official PowerPoint skill (reveal.js-based)
**Pre-Processing Required**: Since slides.md contains Marp-specific syntax, we must strip it before passing to document-skills:pptx:
**Marp Syntax to Remove**:
```yaml
---
marp: true
theme: default
paginate: true
---
```
```html
<!-- _class: lead -->
<!-- _backgroundColor: #f4f4f4 -->
```
**Task Invocation**:
```
Tool: Task
subagent_type: general-purpose (with document-skills:pptx access)
description: document-skills:pptx PPTX generation
prompt: |
Use document-skills:pptx skill to create PowerPoint from slides.md content.
CRITICAL: Pre-process slides.md to remove Marp-specific syntax.
Steps:
1. Read /output/slides.md content
2. Pre-process content (remove Marp syntax):
- Remove YAML frontmatter block (--- ... ---)
- Remove HTML comments with Marp directives: <!-- _class: ... -->, <!-- _backgroundColor: ... -->
- Keep speaker notes: <!-- NOTES: ... --> (convert to PowerPoint notes)
- Keep standard Markdown: #, ##, bullets, bold, italics
3. Convert to document-skills:pptx compatible format:
- # → Title slide
- ## → Content slide heading (large, bold)
- ### → Subheading (if used)
- Bullet points → PowerPoint bullet lists
- **[占位图表]**: description → Text box placeholder "[CHART: description]"
4. Create PPTX using document-skills:pptx:
- File: /output/presentation_pptx.pptx
- Layout: 16:9 (default)
- Theme: document-skills default (reveal.js-based)
- Embed speaker notes from <!-- NOTES: ... -->
5. Quality checks:
- File exists: /output/presentation_pptx.pptx
- Slide count matches slides.md (±1 acceptable)
- No Markdown artifacts visible (no "---", no "<!-- -->")
- Headings rendered correctly
6. If successful, report:
"✓ Path B complete: presentation_pptx.pptx (document-skills styled, [FILE_SIZE]KB)"
Fallback: If document-skills:pptx unavailable, document in README.md and exit gracefully
```
**Expected Output**:
- File: `/output/presentation_pptx.pptx` (~200-300KB)
- Styling: document-skills:pptx default theme (reveal.js-based, clean/modern)
- Charts: Text placeholders initially (will be replaced in Stage 8e-B)
- Notes: Speaker notes embedded in PowerPoint notes section
- Font: System defaults (Calibri/Arial)
**Fallback**: If document-skills:pptx unavailable:
- Skip Path B
- Document in `/output/README.md`: "document-skills:pptx unavailable, delivered Marp version only"
- Proceed with Path A only
---
### Parallel Execution Pattern
**Implementation**: Use a single message with TWO Task tool calls to execute both paths simultaneously.
**Pseudo-code**:
```
# In ppt-creator's response, invoke BOTH agents at once:
1. Call Task tool with Path A prompt (Marp CLI)
2. Call Task tool with Path B prompt (document-skills:pptx)
Both agents run in parallel (non-blocking).
Wait for both to complete, then:
- If both succeed → deliver both PPTX files
- If one succeeds → deliver that one + document other's failure
- If both fail → fallback to Markdown + conversion instructions
```
**User Communication**:
```
🎯 Launching dual-path PPTX generation in parallel...
Path A: Marp CLI → presentation_marp.pptx (native Marp styling)
Path B: document-skills:pptx → presentation_pptx.pptx (reveal.js styling)
Estimated time: 2-3 minutes (parallel execution)
```
---
### Quality Checks for Stage 8d
After both paths complete, verify:
**Path A (Marp) Success Criteria**:
- ✓ File exists: `/output/presentation_marp.pptx`
- ✓ File size: 200-500KB (fonts embedded, reasonable size)
- ✓ Slide count: 12-15 slides (matches slides.md)
- ✓ No error logs from Marp CLI
**Path B (document-skills:pptx) Success Criteria**:
- ✓ File exists: `/output/presentation_pptx.pptx`
- ✓ File size: 200-300KB
- ✓ Slide count: matches slides.md (±1 slide acceptable)
- ✓ No Markdown artifacts visible
**Delivery Matrix**:
| Path A | Path B | Delivery |
|--------|--------|----------|
| ✓ Success | ✓ Success | Both PPTX files (user chooses preferred styling) |
| ✓ Success | ✗ Fail | presentation_marp.pptx + README note about Path B failure |
| ✗ Fail | ✓ Success | presentation_pptx.pptx + README note about Path A failure |
| ✗ Fail | ✗ Fail | Markdown only + pandoc conversion command in README |
---
## Stage 8e: Dual-Path Chart Insertion (Parallel Execution)
**Strategy**: Insert generated PNG charts into BOTH PPTX files (if both exist) using path-specific methods.
### Chart-to-Slide Mapping
**Common Mapping Strategy** (applies to both paths):
1. Parse slides.md to identify chart placeholders:
- Pattern: `**[占位图表]**:` or `**[Chart]**:`
2. Extract chart filename from placeholder description
3. Map to slide number (skip title/TOC, typically start from slide 3)
**Example Mapping**:
```python
chart_mapping = [
{"slide": 3, "chart": "assets/cost_trend.png", "title_contains": "成本"},
{"slide": 4, "chart": "assets/capacity_growth.png", "title_contains": "装机容量"},
{"slide": 5, "chart": "assets/employment.png", "title_contains": "就业"},
# ... (8 charts total)
]
```
**Positioning Guidelines**:
- Standard layout: Right column at (5.5", 2.0") from top-left corner
- Width: 4.0" (leaves 0.5" right margin on 10" slide width)
- Height: Auto (maintain aspect ratio from 10×6 inch source)
- Alternative: Full-width charts at (1.0", 2.5"), width 8.0"
---
### Path A: Marp PPTX Chart Insertion
**Method**: Use python-pptx library to directly manipulate presentation_marp.pptx
**Task Invocation**:
```
Tool: Task
subagent_type: general-purpose
description: Insert charts into Marp PPTX
prompt: |
Insert PNG charts into presentation_marp.pptx using python-pptx library.
Steps:
1. Check python-pptx availability:
python3 -c "import pptx; print(pptx.__version__)"
If not found: uv pip install python-pptx
2. Create insertion script (insert_charts_marp.py):
```python
from pptx import Presentation
from pptx.util import Inches
prs = Presentation('output/presentation_marp.pptx')
chart_mapping = [
(2, 'output/assets/cost_trend.png'), # Slide 3 (0-indexed: 2)
(3, 'output/assets/capacity_growth.png'),
(4, 'output/assets/employment.png'),
# ... (all 8 charts)
]
for slide_idx, chart_path in chart_mapping:
slide = prs.slides[slide_idx]
# Position: right column, 5.5" from left, 2.0" from top, 4.0" wide
slide.shapes.add_picture(
chart_path,
Inches(5.5),
Inches(2.0),
width=Inches(4.0)
)
print(f"✓ Inserted {chart_path} into slide {slide_idx + 1}")
prs.save('output/presentation_marp_with_charts.pptx')
print("✅ Final Marp PPTX: presentation_marp_with_charts.pptx")
```
3. Execute script:
cd .
python3 output/insert_charts_marp.py
4. Quality checks:
- File exists: /output/presentation_marp_with_charts.pptx
- File size increase: +300-600KB (charts embedded)
- All 8 charts inserted without errors
5. Report:
"✓ Path A charts inserted: presentation_marp_with_charts.pptx ([FINAL_SIZE]KB)"
Fallback: If python-pptx fails, deliver presentation_marp.pptx + manual insertion instructions
```
**Expected Output**:
- File: `/output/presentation_marp_with_charts.pptx` (500-900KB)
- Charts: All 8 PNG images embedded at correct positions
- Styling: Marp theme preserved
- Quality: Charts readable, no overlapping text
---
### Path B: document-skills:pptx Chart Insertion
**Method**: Use document-skills:pptx editing capabilities via Task tool
**Task Invocation**:
```
Tool: Task
subagent_type: general-purpose (with document-skills:pptx access)
description: Insert charts into document-skills PPTX
prompt: |
Use document-skills:pptx to insert chart images into presentation_pptx.pptx.
Chart mapping (insert in order):
1. Slide 3: Insert /output/assets/cost_trend.png at position (5.5", 2.0"), width 4.0"
2. Slide 4: Insert /output/assets/capacity_growth.png at position (5.5", 2.0"), width 4.0"
3. Slide 5: Insert /output/assets/employment.png at position (5.5", 2.0"), width 4.0"
4. Slide 6: Insert /output/assets/solar_roi.png at position (5.5", 2.0"), width 4.0"
5. Slide 7: Insert /output/assets/health_impact.png at position (5.5", 2.0"), width 4.0"
6. Slide 8: Insert /output/assets/emissions_reduction.png at position (5.5", 2.0"), width 4.0"
7. Slide 9: Insert /output/assets/cost_parity.png at position (5.5", 2.0"), width 4.0"
8. Slide 10: Insert /output/assets/future_projection.png at position (5.5", 2.0"), width 4.0"
Actions for each chart:
- Open: /output/presentation_pptx.pptx
- Navigate to slide N
- Delete placeholder text box (if exists with "[CHART:" text)
- Insert chart image at specified position (5.5" left, 2.0" top, 4.0" width)
- Maintain aspect ratio (auto-height)
Save as: /output/presentation_pptx_with_charts.pptx
Quality checks:
- All 8 charts inserted successfully
- No overlapping content (check visually)
- File size increase: 300-600KB (charts embedded)
Report:
"✓ Path B charts inserted: presentation_pptx_with_charts.pptx ([FINAL_SIZE]KB)"
Fallback: If document-skills:pptx unavailable, use python-pptx fallback (same as Path A method)
```
**Expected Output**:
- File: `/output/presentation_pptx_with_charts.pptx` (500-800KB)
- Charts: All 8 PNG images embedded
- Styling: document-skills theme preserved
- Quality: Charts readable, professional layout
---
### Parallel Execution Pattern for Chart Insertion
**Implementation**: Launch both chart insertion tasks in parallel (if both PPTX files exist from Stage 8d).
**Decision Logic**:
```
If presentation_marp.pptx exists:
→ Launch Path A chart insertion task
If presentation_pptx.pptx exists:
→ Launch Path B chart insertion task
If both exist:
→ Launch BOTH tasks in parallel (single message with two Task calls)
If neither exist:
→ Skip Stage 8e, deliver Markdown + charts + assembly instructions
```
---
### Quality Checks for Stage 8e
**Path A (Marp) Final Checks**:
- ✓ File exists: `/output/presentation_marp_with_charts.pptx`
- ✓ File size: 500-900KB (base PPTX + charts)
- ✓ All 8 charts visible when opening in PowerPoint/Keynote
- ✓ No overlapping text or broken layouts
- ✓ Charts maintain aspect ratio and readability
**Path B (document-skills:pptx) Final Checks**:
- ✓ File exists: `/output/presentation_pptx_with_charts.pptx`
- ✓ File size: 500-800KB
- ✓ All 8 charts visible and positioned correctly
- ✓ Theme styling preserved
- ✓ Speaker notes still present
**Final Delivery Matrix**:
| Path A 8e | Path B 8e | Final Deliverables |
|-----------|-----------|-------------------|
| ✓ Success | ✓ Success | **Both complete PPTX** (presentation_marp_with_charts.pptx + presentation_pptx_with_charts.pptx) |
| ✓ Success | ✗ Fail | presentation_marp_with_charts.pptx + presentation_pptx.pptx (no charts) + manual instructions |
| ✗ Fail | ✓ Success | presentation_pptx_with_charts.pptx + presentation_marp.pptx (no charts) + manual instructions |
| ✗ Fail | ✗ Fail | Both base PPTX + charts folder + manual insertion guide in README |
---
### User Communication After Stage 8e
**Success (Both Paths)**:
```
✅ Dual-path orchestration complete!
📦 Deliverables:
- presentation_marp_with_charts.pptx (557KB, Marp-styled)
- presentation_pptx_with_charts.pptx (543KB, document-skills styled)
Both files contain:
✓ 14 slides with complete content
✓ 8 real data-driven charts (180 DPI)
✓ Speaker notes for each slide
✓ Professional styling and layout
Choose your preferred version or compare both!
```
**Partial Success (One Path)**:
```
✅ Orchestration complete (partial success)
📦 Deliverables:
- presentation_[PATH]_with_charts.pptx (557KB, complete)
- presentation_[OTHER_PATH].pptx (210KB, charts missing)
- assets/*.png (8 chart files for manual insertion)
- README.md (manual insertion instructions for second path)
Reason for partial: [Brief explanation of why one path failed]
```
**Failure (Both Paths)**:
```
⚠️ Orchestration failed at Stage 8e (chart insertion)
📦 Deliverables:
- presentation_marp.pptx (210KB, text placeholders)
- presentation_pptx.pptx (200KB, text placeholders)
- assets/*.png (8 chart files)
- README.md (manual insertion instructions)
Manual steps:
1. Open preferred PPTX in PowerPoint
2. Navigate to slides 3-10
3. Insert → Pictures → Select corresponding chart from assets/
4. Resize to 4" width, position at right column
```
## Quality Gates
### After Each Stage
**8b: Data Synthesis**
- ✓ All required CSV files exist in /output/data/
- ✓ CSV columns match refs.md specifications
- ✓ Data trends match source calibration (e.g., -87% for solar cost)
- ✓ No missing values or malformed rows
**8c: Chart Generation**
- ✓ All PNG files exist in /output/assets/
- ✓ Image dimensions: ~10×6 inches, 180 DPI
- ✓ File sizes: 40-150KB per chart (optimized)
- ✓ Visual inspection: labels readable, colors distinct, no clipping
**8d: PPTX Creation**
- ✓ File exists: /output/presentation.pptx
- ✓ Slide count matches slides.md (±1 slide acceptable)
- ✓ Headings converted correctly (no Markdown artifacts)
- ✓ Speaker notes embedded
**8e: Chart Insertion**
- ✓ File exists: /output/presentation_with_charts.pptx
- ✓ File size increase: 300-600KB (charts added)
- ✓ Visual check: Open PPTX, verify all charts visible and positioned correctly
- ✓ No overlapping text or images
### Final Deliverable Checklist
Before marking orchestration complete:
- [ ] /output/presentation_with_charts.pptx exists
- [ ] File size: 500KB - 2MB (reasonable range)
- [ ] All placeholder charts replaced with real visualizations
- [ ] Speaker notes preserved
- [ ] Visual inspection: open file, scroll through all slides
- [ ] Backup files retained: slides.md, assets/*.png (for future edits)
---
## Error Handling
### Common Failures and Responses
**1. Data Synthesis Fails (pandas unavailable)**
```
Fallback: Skip Stage 8b, proceed with user-provided data only
Message: "⚠️ pandas unavailable - skipping synthetic data generation. Using provided data files only."
```
**2. Chart Generation Fails (matplotlib issues)**
```
Fallback: Deliver PPTX with text placeholders + standalone Python script
Message: "⚠️ Chart generation failed. Delivering:
- presentation.pptx (with placeholders)
- generate_charts.py (run manually: python generate_charts.py)
- Installation: uv pip install pandas matplotlib"
```
**3. document-skills:pptx Unavailable**
```
Fallback: Deliver Markdown + manual conversion instructions
Message: "⚠️ document-skills:pptx unavailable. Delivering:
- slides.md (complete content)
- assets/*.png (charts ready)
- Conversion: Use Marp/Reveal.js or pandoc to convert to PPTX
Command: pandoc slides.md -o presentation.pptx"
```
**4. Chart Insertion Fails (positioning issues)**
```
Fallback: Deliver PPTX + manual insertion instructions
Message: "⚠️ Automatic chart insertion failed. Delivering:
- presentation.pptx (content ready)
- assets/*.png (charts ready)
- Manual: Open PPTX → Insert → Pictures → Select chart → Resize to 4\" width"
```
### Partial Success Strategy
**Always deliver maximum value**:
- If 6 out of 8 charts succeed → deliver partial PPTX + fix instructions for remaining 2
- If PPTX creation fails → deliver Markdown + charts + conversion command
- Document all failures in `/output/README.md` "Known Issues" section
---
## Examples
### Example A: Minimal User Input → Full Orchestration
**User Request**:
> "Create a presentation about renewable energy, ready for tomorrow's board meeting."
**Detection**:
- Trigger: "ready for tomorrow's meeting" (implicit final deliverable request)
- Mode: Orchestration ✓
**Pipeline Execution**:
```
Stage 0-7: Content creation → slides.md (14 slides, score 87/100)
Stage 8a: Package Markdown → notes.md, refs.md
Stage 8b: Data synthesis → 8 CSV files generated (refs.md specs)
Stage 8c: Chart generation → 8 PNG charts (579KB total)
Stage 8d: PPTX creation → presentation.pptx (210KB)
Stage 8e: Chart insertion → presentation_with_charts.pptx (557KB) ✓
```
**Delivered**:
- `/output/presentation_with_charts.pptx` (557KB, 14 slides, 8 real charts)
- Backup: slides.md, assets/*.png, data/*.csv, notes.md
---
### Example B: User Provides Data → Skip Synthesis
**User Request**:
> "Generate complete PPTX from these Q3 sales data files [uploads 3 CSVs]"
**Detection**:
- Trigger: "complete PPTX" (explicit orchestration request)
- User data: ✓ (3 CSV files uploaded)
- Mode: Orchestration, skip Stage 8b ✓
**Pipeline Execution**:
```
Stage 0-7: Content creation → slides.md (12 slides)
Stage 8a: Package Markdown
Stage 8b: SKIPPED (user data provided)
Stage 8c: Chart generation → use user CSVs → 5 PNG charts
Stage 8d: PPTX creation → presentation.pptx
Stage 8e: Chart insertion → presentation_with_charts.pptx ✓
```
---
### Example C: Markdown-Only Request → No Orchestration
**User Request**:
> "Create slides.md for renewable energy topic, I'll handle the PPTX conversion myself."
**Detection**:
- Trigger: "slides.md" + "I'll handle conversion" (explicit manual mode)
- Mode: Manual, no orchestration
**Pipeline Execution**:
```
Stage 0-7: Content creation → slides.md
Stage 8a: Package Markdown → notes.md, refs.md
Stage 8b-e: SKIPPED
```
**Delivered**:
- `/output/slides.md` with placeholder charts
- `/output/notes.md`, `/output/refs.md`
- Instructions: "Convert to PPTX using Marp or pandoc"
---
## Version History
- v1.0.0 (2024-01): Initial orchestration capability

414
ppt-creator/references/RUBRIC.md Normal file
View File

@@ -0,0 +1,414 @@
# PPT Quality Scoring Rubric
> **Purpose**: Systematically evaluate presentation quality and identify areas for improvement. A score ≥ 75/100 is required before delivery. If score < 75, refine the weakest items and re-score (max 2 iterations).
---
## Scoring System
- **Total Score**: 100 points (10 items × 10 points each)
- **Passing Threshold**: ≥ 75 points
- **Rating Scale** (per item):
- **9-10**: Excellent (exceeds expectations)
- **7-8**: Good (meets expectations)
- **5-6**: Acceptable (minor improvements needed)
- **3-4**: Weak (significant improvements required)
- **0-2**: Poor (fundamental issues, must fix)
---
## 1. Goal Clarity (0-10 points)
**What**: Are the audience, objective, and call-to-action (CTA) clearly defined and documented?
**Scoring Criteria**:
- **10**: Audience, objective, and CTA explicitly stated and tailored; assumptions documented
- **8**: Audience and objective clear; CTA present but could be more specific
- **6**: Audience/objective vague; CTA generic (e.g., "let's discuss")
- **4**: Missing audience definition or objective; no clear CTA
- **2**: Presentation lacks clear purpose or intended action
**How to Check**:
- Review INTAKE.md responses and archive.txt
- Check final slide for specific CTA (not "Thank you" or "Questions?")
- Verify speaker notes mention audience and goal
**Example Scores**:
- **10**: "After this 15-minute presentation, coffee enthusiasts will try at least one new brewing technique within the next week."
- **6**: "This presentation is about coffee brewing for people interested in coffee."
- **2**: "Talk about coffee."
---
## 2. Story Structure (0-10 points)
**What**: Is the Pyramid Principle applied? (One conclusion → 3-5 first-level reasons → evidence)
**Scoring Criteria**:
- **10**: Clear pyramid structure; conclusion upfront; logical flow from reasons to evidence
- **8**: Pyramid structure present but hierarchy could be clearer
- **6**: Some structure but not consistently pyramid-style (e.g., conclusion buried at end)
- **4**: Scattered points without clear logical connection
- **2**: No discernible structure; random order
**How to Check**:
- Review storyline in archive.txt or WORKFLOW Stage 2 output
- Verify cover slide states main conclusion
- Check that 3-5 body sections support the conclusion
- Ensure evidence supports reasons (not random facts)
**Example Scores**:
- **10**: Cover: "Master three variables for great coffee" → Sections: Grind / Temp / Time → Each with 2-3 evidence slides
- **6**: Conclusion at end; sections exist but don't clearly support a single main point
- **2**: Slides jump between topics with no connective thread
---
## 3. Slide Assertions (0-10 points)
**What**: Are slide headings assertion sentences (testable claims), not topic labels?
**Scoring Criteria**:
- **10**: All slide headings are complete, testable assertion sentences
- **8**: Most headings are assertions; 1-2 topic labels remain
- **6**: Mix of assertions and topic labels (50/50)
- **4**: Mostly topic labels with few assertions
- **2**: All headings are topic labels (e.g., "Revenue", "Background", "Methodology")
**How to Check**:
- Review slide titles in slides.md
- Test: Can you agree/disagree with the heading? (If yes → assertion; if no → topic label)
- ✅ Assertion: "Finer grind size extracts flavors faster"
- ❌ Topic label: "Grind Size"
**Example Scores**:
- **10**: Every slide heading is a complete sentence making a claim
- **6**: Half are assertions ("Revenue grew 35%") and half are topics ("Q3 Results")
- **2**: All headings are one-word or topic-style ("Introduction", "Conclusion")
---
## 4. Evidence Quality (0-10 points)
**What**: Is evidence sufficient, credible, and properly cited?
**Scoring Criteria**:
- **10**: All claims backed by data/examples/citations; sources cited; units/methodology clear
- **8**: Most claims have evidence; minor gaps in citations or methodology
- **6**: Some claims lack evidence; sources missing or vague
- **4**: Many unsupported claims; no citations; unclear data provenance
- **2**: Assertions without any evidence or support
**How to Check**:
- Verify each assertion slide has chart/table/example/case study
- Check footer for source citations (e.g., "Source: XYZ, 2024")
- Confirm data units, time ranges, and methodology are specified
- Look for placeholder charts with "Data required: [fields]" if data unavailable
**Example Scores**:
- **10**: "68% report bad cup experiences (Source: NCA 2024 Survey, n=1,200 home brewers)"
- **6**: "Most people have bad coffee sometimes" (no data, no source)
- **2**: "Coffee is important" (pure opinion, no evidence)
---
## 5. Chart Fit (0-10 points)
**What**: Are charts correctly selected, labeled, and easy to read?
**Scoring Criteria**:
- **10**: Chart type matches data/message (per VIS-GUIDE); axes, units, source, alt text all present
- **8**: Chart type correct; minor labeling gaps (e.g., missing unit or source)
- **6**: Chart type suboptimal (e.g., pie chart with 7 slices); some labels missing
- **4**: Wrong chart type for data; poor labeling; hard to interpret
- **2**: No charts, or charts are misleading/unreadable
**How to Check**:
- Review chart selection against VIS-GUIDE.md Chart Selection Dictionary
- Verify all charts have: axis labels, units, data source, alt text
- Check readability: Can you understand the chart in 5 seconds?
**Example Scores**:
- **10**: Line chart for time series, properly labeled, source cited, alt text provided
- **6**: Bar chart OK but Y-axis missing unit; no source citation
- **2**: 3D exploded pie chart with 10 slices and no labels
---
## 6. Visual & Accessibility (0-10 points)
**What**: Does the design meet WCAG AA standards and STYLE-GUIDE specs?
**Scoring Criteria**:
- **10**: Contrast ≥4.5:1 (text) / ≥3:1 (UI); font sizes ≥18pt body / ≥34pt heading; white space ≥40%; alt text present
- **8**: Minor accessibility issues (e.g., one chart with 4.2:1 contrast)
- **6**: Multiple contrast or font size issues; some alt text missing
- **4**: Poor contrast (<3:1), tiny fonts (<14pt), cluttered layout
- **2**: Unreadable (light gray on white, <12pt fonts, no alt text)
**How to Check**:
- Use WebAIM contrast checker on text/background combos
- Measure font sizes (headings ≥34pt, body ≥18pt)
- Estimate white space (aim for 40-50% empty)
- Verify alt text for all images/charts
- Check colorblind-friendliness (use simulator)
**Example Scores**:
- **10**: Dark text (#1F2937) on white, 36pt headings, 20pt body, 45% white space, all alt text present
- **6**: Some 16pt body text, one chart missing alt text, 25% white space (crowded)
- **2**: Light gray text on white, 12pt font, no margins, no alt text
---
## 7. Coherence & Transitions (0-10 points)
**What**: Do slides flow logically with smooth chapter and page transitions?
**Scoring Criteria**:
- **10**: Clear section dividers; speaker notes include transitions; logical progression
- **8**: Good flow overall; minor abrupt jumps
- **6**: Some disjointed transitions; missing section dividers
- **4**: Slides feel disconnected; unclear how one leads to next
- **2**: Random order; no transitions or connective tissue
**How to Check**:
- Review speaker notes for transition phrases (e.g., "Now that we've covered X, let's explore Y")
- Check for section divider slides between major chapters
- Verify table of contents matches actual slide sequence
**Example Scores**:
- **10**: Section dividers present; every speaker note ends with "This leads us to [next topic]..."
- **6**: Flow is OK but one abrupt jump from "Problem" to "Conclusion" skipping "Solution"
- **2**: Slides seem shuffled; no clear reason for order
---
## 8. Speakability (0-10 points)
**What**: Are speaker notes natural, well-paced (45-60 sec/slide), and easy to deliver?
**Scoring Criteria**:
- **10**: All notes 45-60 sec; natural spoken language; structured (opening → assertion → evidence → transition)
- **8**: Most notes well-paced; minor awkward phrasing
- **6**: Some notes too long (>90 sec) or too short (<30 sec); some written-style language
- **4**: Many notes poorly paced; reads like an essay, not speech
- **2**: No speaker notes, or notes are bullet-point lists (not full script)
**How to Check**:
- Read notes aloud and time them
- Listen for natural speech patterns (contractions, questions, pauses)
- Verify structure: opening hook → core assertion → evidence walkthrough → transition
**Example Scores**:
- **10**: "Now, here's the key insight: finer grind means more surface area. Think of it like sugar—powdered sugar dissolves instantly, while sugar cubes take forever. [PAUSE] Let's see how this plays out across five grind sizes..."
- **6**: "The slide shows five grind sizes ranging from espresso to cold brew. Each has different particle size." (too dry, too short)
- **2**: "• Espresso grind • Pour-over grind • French press grind" (bullet list, not script)
---
## 9. Deliverables Complete (0-10 points)
**What**: Are all required output files present and correctly formatted?
**Scoring Criteria**:
- **10**: All files present and correct: slides.md, notes.md, refs.md, assets/*.png (if applicable), README.md
- **8**: All core files present; minor formatting issues or missing README
- **6**: Missing one deliverable (e.g., refs.md) or major formatting issue
- **4**: Missing multiple deliverables or files are incomplete
- **2**: Only partial output (e.g., slides.md exists but no notes or charts)
**How to Check**:
- Verify `/output/` directory contains:
- `slides.md` (Markdown slides with YAML frontmatter, speaker notes)
- `notes.md` (Full speaker script + assumptions section)
- `refs.md` (Citations and sources)
- `assets/*.png` (charts, if data was provided)
- `README.md` (explains file structure)
- `presentation.pptx` (optional, if python-pptx available)
**Example Scores**:
- **10**: All 5-6 files present, properly formatted, no broken links
- **6**: Missing refs.md or README.md; one broken chart image link
- **2**: Only slides.md exists; everything else missing
---
## 10. Robustness (0-10 points)
**What**: Are gaps/assumptions documented, and fallback plans provided?
**Scoring Criteria**:
- **10**: All assumptions documented in notes.md; placeholders for missing data include field lists; next steps clear
- **8**: Most assumptions noted; minor gaps in fallback plans
- **6**: Some assumptions undocumented; placeholder charts lack detail
- **4**: Many assumptions hidden; no guidance for missing data
- **2**: Assumptions concealed; no acknowledgment of limitations
**How to Check**:
- Review "Assumptions & Limitations" section in notes.md
- Check placeholder charts have "Data required: [field list]"
- Verify next steps or follow-up actions are mentioned (if applicable)
**Example Scores**:
- **10**: "Assumptions: (1) Used default 15-min duration (user did not specify). (2) No data provided for extraction curves; placeholder included with required fields: temperature_f, extraction_pct, time_sec."
- **6**: Assumptions partially noted but missing some; placeholders generic ("Add chart here")
- **2**: No mention of assumptions; missing data silently ignored
---
## Scoring Workflow
### Step 1: Initial Scoring
1. Review the presentation against all 10 criteria
2. Assign 0-10 points for each item
3. Calculate total score (sum of 10 items)
**Example Initial Scorecard**:
```
1. Goal Clarity: 9/10 ✓
2. Story Structure: 8/10 ✓
3. Slide Assertions: 6/10 ⚠️
4. Evidence Quality: 7/10 ⚠️
5. Chart Fit: 8/10 ✓
6. Visual & Accessibility: 9/10 ✓
7. Coherence & Transitions: 7/10 ⚠️
8. Speakability: 8/10 ✓
9. Deliverables Complete: 9/10 ✓
10. Robustness: 8/10 ✓
────────────────────────
TOTAL: 79/100 ✓ (≥75, ready to deliver)
```
---
### Step 2: If Score < 75, Identify Top 3 Weaknesses
1. Sort items by score (ascending)
2. Identify the **3 lowest-scoring items**
3. Write specific improvement actions for each
**Example (if total was 72/100)**:
```
TOP 3 WEAKNESSES:
1. Item 3 (Slide Assertions): Score 5/10
- Problem: Slides 4, 7, 11 use topic labels ("Grind Size", "Temperature")
- Action: Revise to assertion sentences:
• Slide 4: "Finer grind size extracts flavors faster and more completely"
• Slide 7: "Water between 195-205°F produces balanced, full-bodied coffee"
• Slide 11: "Simple equipment upgrades ensure consistent results"
2. Item 4 (Evidence Quality): Score 6/10
- Problem: Missing source citations on 3 charts; no methodology note
- Action:
• Add footer to charts: "Source: National Coffee Association, 2024"
• Add methodology note in refs.md: "Survey n=1,200 home brewers, margin of error ±3%"
3. Item 7 (Coherence & Transitions): Score 6/10
- Problem: Abrupt jump from Slide 8 (temperature) to Slide 9 (time); missing section divider
- Action:
• Insert transition slide: "Now that we've mastered grind and temperature, let's tackle the third variable: time"
• Update speaker notes for Slide 8 to bridge: "...and this brings us to our final variable."
```
---
### Step 3: Apply Improvements & Re-Score
1. Make the improvements
2. Re-score all 10 items
3. If new total ≥ 75 → **deliver**
4. If new total < 75 → repeat Step 2-3 (max 2 iterations total)
**Example Re-Score**:
```
1. Goal Clarity: 9/10 ✓
2. Story Structure: 8/10 ✓
3. Slide Assertions: 9/10 ✓ (improved from 5)
4. Evidence Quality: 8/10 ✓ (improved from 6)
5. Chart Fit: 8/10 ✓
6. Visual & Accessibility: 9/10 ✓
7. Coherence & Transitions: 8/10 ✓ (improved from 6)
8. Speakability: 8/10 ✓
9. Deliverables Complete: 9/10 ✓
10. Robustness: 8/10 ✓
────────────────────────
TOTAL: 84/100 ✓✓ (exceeds threshold, ready to deliver)
```
---
## Iteration Limits
- **Max Iterations**: 2 rounds of improvements
- **Why Limit**: Avoid infinite refinement loop; deliver practical value quickly
- **If Still < 75 After 2 Rounds**:
- Deliver with clear disclaimer: "This presentation scores [X]/100. The following items need further work: [list weakest 3 items]."
- Provide improvement roadmap in notes.md
---
## Common Score Ranges & Interpretations
| Score Range | Interpretation | Typical Issues |
|-------------|----------------|----------------|
| 90-100 | Exceptional | Exceeds all criteria; publication-ready |
| 75-89 | Good (passing) | Minor polish needed; ready to present |
| 60-74 | Needs improvement | Missing some assertions, evidence, or accessibility fixes |
| 45-59 | Weak | Major structure or clarity issues; requires significant rework |
| 0-44 | Poor | Fundamental problems; restart from WORKFLOW Stage 2 |
---
## Self-Evaluation Checklist (Quick Version)
Use this quick checklist before full scoring:
- [ ] **Goal**: Audience, objective, CTA documented and clear?
- [ ] **Structure**: Pyramid (conclusion → reasons → evidence)?
- [ ] **Assertions**: All headings are testable sentences?
- [ ] **Evidence**: All claims have data/examples/citations?
- [ ] **Charts**: Correct type, fully labeled, source cited?
- [ ] **Accessibility**: Contrast ≥4.5:1, fonts ≥18pt, alt text?
- [ ] **Transitions**: Smooth flow, section dividers, speaker notes?
- [ ] **Speakability**: Notes 45-60 sec, natural language?
- [ ] **Deliverables**: slides.md, notes.md, refs.md, assets/?
- [ ] **Robustness**: Assumptions documented, placeholders detailed?
If all checkboxes are ✓, score is likely ≥ 75.
---
## Final Delivery Criteria
**Before delivering to user, confirm**:
1. Total score ≥ 75/100 (or 2 improvement iterations completed)
2. All deliverables in `/output/` directory
3. Assumptions and limitations documented in notes.md
4. If score < 75, include improvement roadmap
**Delivery Message Template**:
```
✅ Presentation ready!
SCORE: [X]/100 (threshold: 75)
QUALITY: [Exceptional / Good / Needs improvement]
DELIVERABLES:
- /output/slides.md (Markdown deck, [N] slides)
- /output/notes.md (Speaker script + assumptions)
- /output/refs.md (Citations and sources)
- /output/assets/ ([N] charts)
- /output/presentation.pptx (if available)
NEXT STEPS:
- Review speaker notes and adjust for your personal style
- Replace placeholder charts with your data (use chartkit.py if needed)
- Customize colors/fonts per STYLE-GUIDE.md
[If score < 75: Add improvement roadmap here]
```
---
**Next Steps**: Once scoring is complete and score ≥ 75, proceed to Stage 8 (Package Deliverables) in WORKFLOW.md.

460
ppt-creator/references/STYLE-GUIDE.md Normal file
View File

@@ -0,0 +1,460 @@
# Layout & Style Guide (Neutral Theme)
> **Purpose**: Ensure consistent, accessible, professional visual design across all slides. This neutral theme supports easy customization with your own brand colors and fonts.
---
## Canvas & Grid System
### Slide Dimensions
- **Aspect Ratio**: 16:9 (widescreen standard)
- **Resolution**: 1920 × 1080 pixels (Full HD) or 1280 × 720 pixels (HD)
- **Safe Zone**: Margins ≥ 48px on all sides (prevents content from being cut off by projectors)
### Grid System
- **Columns**: 12-column grid (column width varies by content)
- **Gutter**: 24px between columns
- **Baseline Grid**: 8px vertical rhythm (all spacing should be multiples of 8)
### Layout Examples
```
┌─────────────────────────────────────────────┐
│ [48px margin] │
│ ┌──────────────────────────────────┐ │
│ │ HEADING (top-aligned) │ │
│ │ │ │
│ │ [Content area: text/chart/image] │ │
│ │ │ │
│ │ │ │
│ └──────────────────────────────────┘ │
│ [Footer: source + page #] [48px] │
└─────────────────────────────────────────────┘
```
---
## Typography
### Font Families
**Recommended Fonts**:
- **Chinese**: Source Han Sans (思源黑体) / PingFang SC (苹方) / Hiragino Sans (冬青黑体)
- **English**: Inter / Calibri / Helvetica Neue / Arial
**Why These Fonts**:
- High readability on screens
- Wide character support (multilingual)
- Professional appearance
- Available on most systems (or free to download)
**Fallback Stack**:
```
font-family: "Inter", "Source Han Sans", "PingFang SC", -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif;
```
### Font Sizes
| Element | Size (pt) | Weight | Use Case |
|---------|-----------|--------|----------|
| Slide Title | 34-40 | Bold (700) | Main assertion heading |
| Subtitle / Section | 24-28 | Semibold (600) | Chapter intros, subheadings |
| Body Text | 18-22 | Regular (400) | Bullet points, paragraphs |
| Caption / Label | 16-18 | Regular (400) | Chart labels, image captions |
| Footer / Source | 14-16 | Regular (400) | Citations, page numbers |
**Minimum Readable Size**: 14pt (anything smaller is hard to read from audience distance)
---
### Line Spacing (Leading)
| Element | Line Height | Calculation |
|---------|-------------|-------------|
| Headings | 1.1 × font size | Tight for emphasis |
| Subheadings | 1.2 × font size | Slightly relaxed |
| Body Text | 1.3-1.5 × font size | Comfortable reading |
| Captions | 1.3 × font size | Consistent with body |
**Example**:
- Heading: 36pt font → 40pt line height (1.1×)
- Body: 20pt font → 28pt line height (1.4×)
---
### Text Alignment
- **Headings**: Left-aligned (easier to scan)
- Exception: Cover slide title may be centered
- **Body Text**: Left-aligned
- Avoid full justification (creates awkward word spacing)
- **Bullet Points**: Left-aligned with 24-32px indent
- **Footers**: Right-aligned (source), left-aligned (page number/date)
---
### Text Formatting
**Bold**:
- Use for headings, key terms, and emphasis
- Do NOT use all-caps for body text (harder to read)
**Italic**:
- Use sparingly for quotes, foreign terms, or subtle emphasis
- Do NOT use for long passages (reduces readability)
**Underline**:
- Avoid (looks like hyperlinks)
- Use bold or color for emphasis instead
**ALL CAPS**:
- OK for short labels (e.g., "SECTION 1", "BACKUP")
- Avoid for sentences (slows reading speed by 10-15%)
---
## Color Palette (Neutral Theme, WCAG AA Compliant)
### Primary Colors
| Color Name | Hex Code | RGB | Use Case | Contrast vs White | Contrast vs Black |
|------------|----------|-----|----------|-------------------|-------------------|
| Dark Ink | #1F2937 | rgb(31, 41, 55) | Headings, body text | 16.1:1 ✓ | 1.3:1 ✗ |
| Medium Gray | #6B7280 | rgb(107, 114, 128) | Secondary text, captions | 4.6:1 ✓ | 4.5:1 ✓ |
| Light Gray | #D1D5DB | rgb(209, 213, 219) | Borders, dividers | 1.7:1 ✗ | 12.4:1 ✓ |
| Background White | #FFFFFF | rgb(255, 255, 255) | Slide background | — | 21:1 ✓ |
### Accent Colors
| Color Name | Hex Code | RGB | Use Case | Contrast vs White | Contrast vs Black |
|------------|----------|-----|----------|-------------------|-------------------|
| Primary Blue | #2563EB | rgb(37, 99, 235) | Links, highlights, key points | 4.6:1 ✓ | 4.6:1 ✓ |
| Secondary Teal | #0891B2 | rgb(8, 145, 178) | Alternative highlight | 3.7:1 ⚠️ | 5.7:1 ✓ |
| Emphasis Red | #DC2626 | rgb(220, 38, 38) | Warnings, critical points | 5.0:1 ✓ | 4.2:1 ✓ |
| Success Green | #10B981 | rgb(16, 185, 129) | Positive trends, checkmarks | 2.5:1 ✗ | 8.4:1 ✓ |
**Note**: ✓ = Passes WCAG AA (≥4.5:1 for text, ≥3:1 for UI elements); ⚠️ = Marginal (use carefully); ✗ = Fails
### Color Usage Rules
1. **Text on White Background**:
- Primary text: Dark Ink (#1F2937) → 16.1:1 ✓
- Secondary text: Medium Gray (#6B7280) → 4.6:1 ✓
- Links/Highlights: Primary Blue (#2563EB) → 4.6:1 ✓
2. **Text on Dark Background** (e.g., dark slide):
- Use white (#FFFFFF) or very light gray (#F3F4F6)
- Ensure ≥4.5:1 contrast
3. **Chart Colors**:
- Use Primary Blue, Emphasis Red, Secondary Teal, Success Green
- Avoid relying on color alone (add patterns/labels)
- Test with colorblind simulator (see VIS-GUIDE.md)
4. **Avoid These Combinations**:
- Red text on green background (colorblind issue)
- Light gray text on white background (insufficient contrast)
- Pure black (#000000) on pure white (too harsh; use Dark Ink instead)
---
## Spacing & Layout
### Margin & Padding
| Element | Spacing | Notes |
|---------|---------|-------|
| Slide Margins | 48px (all sides) | Safe zone for projectors |
| Heading to Body | 24-32px | Clear separation |
| Paragraph Spacing | 16-24px | Between bullet points or paragraphs |
| Chart to Caption | 16px | Between chart and source citation |
| Footer Padding | 24px from bottom | Consistent footer placement |
### Bullet Point Formatting
- **Indent**: 24-32px from left margin
- **Bullet Style**: Simple (•) or numbered (1., 2., 3.)
- Avoid fancy bullets (stars, arrows, custom icons)
- **Max Bullets Per Slide**: 3-5 (more gets overwhelming)
- **Nested Bullets**: Max 2 levels (Level 1 → Level 2)
- Level 2 indent: +24px from Level 1
**Example**:
```
• Main point one (Level 1)
• Supporting detail (Level 2)
• Another detail (Level 2)
• Main point two (Level 1)
• Main point three (Level 1)
```
---
## Visual Elements
### Charts & Graphs
- **Padding**: 8px internal padding around chart area
- **Border**: None (or very subtle 1px light gray if needed)
- **Grid Lines**: Minimal (horizontal only, light gray #E5E7EB)
- **Axis Lines**: 1-2px, Medium Gray (#6B7280)
- **Data Labels**: 16-18pt, positioned above/beside data points (not overlapping)
### Images & Photos
- **Border Radius**: 6-8px (subtle rounded corners)
- **Padding**: 8px around image
- **Alt Text**: Always include (see Accessibility section)
- **Aspect Ratio**: Maintain original (don't stretch/distort)
- **Max Size**: Leave 48px margins on all sides
### Icons
- **Size**: 24px × 24px (small), 48px × 48px (medium), 96px × 96px (large)
- **Style**: Outline or filled (be consistent across deck)
- **Color**: Match accent colors (Primary Blue, Emphasis Red, etc.)
- **Spacing**: 16px between icon and label
### Dividers & Borders
- **Horizontal Divider**: 1-2px, Light Gray (#D1D5DB)
- **Use Sparingly**: Only when needed to separate sections
- **Border Radius**: 6-8px for boxes, cards, or containers
---
## Page Density & White Space
### The "70-Word Rule"
- **Max Words Per Slide**: ≤70 words (excluding chart labels and footer)
- **Why**: Audience can't read and listen simultaneously; slides should support speech, not replace it
- **Exception**: Backup slides or reference tables (not presented, for Q&A)
### White Space Guidelines
- **Don't Fill Every Pixel**: Aim for 40-50% white space per slide
- **Purpose**: Guides eye, reduces cognitive load, looks professional
- **How to Achieve**:
- Use generous margins (48px+)
- Space out bullet points (16-24px apart)
- One chart or image per slide (not 3-4 crammed together)
---
## Accessibility (WCAG 2.1 AA Compliance)
### Contrast Requirements
**Text Contrast** (against background):
- **Normal text** (<18pt or <14pt bold): ≥ 4.5:1
- **Large text** (≥18pt or ≥14pt bold): ≥ 3:1
**UI Components & Chart Elements**:
- **Graphical objects** (bars, lines, icons): ≥ 3:1 against adjacent colors
- **Active vs inactive states**: ≥ 3:1 contrast difference
**Test Your Contrast**:
- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
- Browser DevTools: Inspect element → Contrast ratio displayed
---
### Color Blindness
**Do NOT Rely on Color Alone**:
- Add text labels, patterns, or shapes to distinguish chart series
- Example: Line chart with 3 series → use solid, dashed, dotted lines + color
**Use Colorblind-Friendly Palettes**:
- Avoid red + green combinations
- Use blue + orange or blue + yellow instead
- Test with simulators: Coblis, Color Oracle
---
### Alt Text for Images & Charts
**Every image and chart must have alt text** for screen readers.
**Good Alt Text**:
- Describes content concisely (1-2 sentences)
- Includes key data insights (for charts)
- Example (chart): "Line chart showing monthly revenue Jan-Dec 2024, with 35% growth and a sharp Q3 spike."
- Example (photo): "Product prototype with transparent casing and LED display showing time."
**Bad Alt Text**:
- "Chart 1" (too vague)
- "Revenue graph" (no insight)
- [Empty alt tag] (inaccessible)
---
### Screen Reader Compatibility
- **Heading Hierarchy**: Use proper heading levels (H1 → H2 → H3), don't skip
- **Reading Order**: Ensure content flows logically (top-to-bottom, left-to-right)
- **Link Text**: Descriptive ("Download Q4 Report" vs. "Click here")
---
## Animation & Transitions (Use Sparingly)
### When to Animate
- **Reveal bullet points**: One at a time (helps pacing)
- **Highlight data**: Fade in chart elements sequentially (e.g., line-by-line)
- **Slide transitions**: Simple fade or push (not flashy)
### When NOT to Animate
- **Avoid**: Spinning, bouncing, dissolving, 3D effects
- **Why**: Distracting, unprofessional, slows down presentation
- **Exception**: Data storytelling where sequence matters (e.g., building a chart layer-by-layer)
---
## Slide-Specific Layouts
### Cover Slide
```
┌─────────────────────────────────────────┐
│ │
│ [Centered or Left-Aligned] │
│ │
│ MAIN TITLE (36-40pt, Bold) │
│ Subtitle (24-28pt, Regular) │
│ │
│ Date | Presenter Name │
│ │
└─────────────────────────────────────────┘
```
---
### Content Slide (Text + Chart)
```
┌─────────────────────────────────────────┐
│ ASSERTION HEADING (34-36pt) │
│ │
│ • Bullet point 1 (20pt) │
│ • Bullet point 2 │
│ • Bullet point 3 │
│ │
│ [Chart with alt text] │
│ │
│ Source: XYZ, 2024 | Page 5 │
└─────────────────────────────────────────┘
```
---
### Section Divider Slide
```
┌─────────────────────────────────────────┐
│ │
│ │
│ SECTION TITLE (40pt) │
│ Brief Description (24pt) │
│ │
│ │
│ │
└─────────────────────────────────────────┘
```
---
## Customization Guide (Replace with Your Brand)
### Step 1: Update Colors
**Find and replace these hex codes** in your slides:
| Theme Color | Default | Your Brand | Use Case |
|-------------|---------|------------|----------|
| Primary Text | #1F2937 | _________ | Headings, body |
| Accent | #2563EB | _________ | Highlights, links |
| Emphasis | #DC2626 | _________ | Warnings, critical |
| Background | #FFFFFF | _________ | Slide background |
**Test Contrast**: Use WebAIM checker to ensure ≥4.5:1 for text, ≥3:1 for UI.
---
### Step 2: Update Fonts
**Find and replace font families**:
- Headings: Inter → [Your Brand Font]
- Body: Source Han Sans → [Your Brand Font]
**Web Font Loading** (if using Google Fonts or Adobe Fonts):
```html
<link href="https://fonts.googleapis.com/css2?family=YourFont:wght@400;600;700&display=swap" rel="stylesheet">
```
---
### Step 3: Add Logo
- Place logo file in `/output/assets/logo.png`
- Add to **cover slide** (top-left or top-right)
- Add to **footer** of content slides (small, 32-48px height)
---
### Step 4: Customize Templates
- Open `references/TEMPLATES.md`
- Adjust spacing, margins, or layout to match your brand guidelines
- Update STYLE-GUIDE.md to document your changes
---
### Step 5: Export & Test
- Export to PPTX or PDF
- Test on projector (check margins, readability)
- Verify accessibility (screen reader, contrast, colorblind mode)
---
## Quick Reference Checklist
Before finalizing each slide, check:
- [ ] **Contrast**: Text ≥ 4.5:1, UI elements ≥ 3:1
- [ ] **Margins**: ≥ 48px safe zone on all sides
- [ ] **Font Size**: Headings ≥ 34pt, body ≥ 18pt
- [ ] **Line Spacing**: Headings 1.1×, body 1.3-1.5×
- [ ] **Word Count**: ≤ 70 words per slide
- [ ] **Alt Text**: All charts and images have descriptive alt text
- [ ] **Bullet Points**: Max 3-5 per slide
- [ ] **White Space**: 40-50% of slide is empty
- [ ] **Source Citation**: Every chart has source in footer
- [ ] **Color Independence**: Not relying on color alone (patterns/labels added)
---
## Tools & Resources
1. **Contrast Checkers**:
- WebAIM: https://webaim.org/resources/contrastchecker/
- Chrome DevTools: Inspect → Contrast ratio
2. **Colorblind Simulators**:
- Coblis: https://www.color-blindness.com/coblis-color-blindness-simulator/
- Color Oracle (desktop app)
3. **Fonts**:
- Google Fonts: https://fonts.google.com/
- Adobe Fonts: https://fonts.adobe.com/
- Source Han Sans (free): https://github.com/adobe-fonts/source-han-sans
4. **WCAG 2.1 Guidelines**:
- Contrast (Minimum): https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
---
**Next Steps**: Once style is finalized, proceed to Stage 6 (Speaker Notes) in WORKFLOW.md.

540
ppt-creator/references/TEMPLATES.md Normal file
View File

@@ -0,0 +1,540 @@
# Slide Template Library (Assertion-Evidence Style)
> **Rule**: All slide headings must be **assertion sentences** (complete, testable claims), not topic labels. Body content provides **evidence** (charts, tables, diagrams, bullet points). Keep to **3-5 bullet points maximum** per slide. Place data sources in the footer (bottom-right).
---
## Core Slide Templates
### 1. Cover Slide
**Purpose**: Introduce the main conclusion/proposition upfront.
**Structure**:
```
HEADING: [Main Conclusion as Assertion Sentence]
SUBHEADING: [Context, Occasion, or Target Audience]
FOOTER: [Date] | [Presenter Name/Organization]
```
**Example**:
```
HEADING: Mastering Three Variables Unlocks Consistently Great Coffee at Home
SUBHEADING: A Practical Guide for Coffee Enthusiasts
FOOTER: October 2025 | Coffee Workshop Series
```
---
### 2. Table of Contents
**Purpose**: Show the roadmap (3-5 chapters matching first-level reasons).
**Structure**:
```
HEADING: Roadmap / What We'll Cover
CHAPTERS:
1. [First Reason/Chapter]
2. [Second Reason/Chapter]
3. [Third Reason/Chapter]
4. [Optional Fourth]
5. [Optional Fifth]
```
**Example**:
```
HEADING: Roadmap
1. Grind Size Controls Extraction Rate
2. Water Temperature Affects Flavor Balance
3. Brew Time Determines Strength
4. Simple Equipment Upgrades Improve Consistency
```
---
### 3. Problem Statement (Problem Slide)
**Purpose**: Assert why the current situation is unsatisfactory or why action is needed now.
**Structure**:
```
HEADING: [Assertion about the problem's severity or impact]
EVIDENCE:
- Key metric or statistic showing problem scale
- Real-world consequence or example
- Visual: trend chart (decline/growth) or comparison table
SOURCE: [Data citation in footer]
```
**Example**:
```
HEADING: Inconsistent home coffee wastes premium beans and disappoints drinkers daily
EVIDENCE:
- 68% of home brewers report frequent "bad cup" experiences (Source: 2024 Coffee Survey)
- Average household wastes 2 lbs of beans/year due to poor technique
- Visual: Bar chart showing #1 complaint: "Can't replicate good results"
SOURCE: National Coffee Association, 2024 Home Brewing Survey
```
---
### 4. Opportunity / Goal (Aspiration Slide)
**Purpose**: Assert what success looks like or what can be achieved.
**Structure**:
```
HEADING: [Assertion about the achievable outcome]
EVIDENCE:
- Quantified benefit or goal metric
- Success example or case study
- Visual: target state diagram or before/after comparison
SOURCE: [Citation if applicable]
```
**Example**:
```
HEADING: Mastering three simple variables delivers cafe-quality coffee at one-tenth the cost
EVIDENCE:
- Home brewing cost: $0.50/cup vs. cafe $5/cup
- 90% satisfaction rate with proper technique (vs. 32% without)
- Visual: Cost comparison bar chart + satisfaction curve
SOURCE: Coffee Economics Institute, 2025
```
---
### 5. Solution Overview (Three-Part Solution)
**Purpose**: Assert that a specific approach (typically 3 components) solves the problem.
**Structure**:
```
HEADING: [Assertion about the solution's effectiveness]
COMPONENTS:
A. [Component 1 - brief phrase]
B. [Component 2 - brief phrase]
C. [Component 3 - brief phrase]
VISUAL: Three-box diagram or process flow
```
**Example**:
```
HEADING: Three brewing variables—grind size, water temp, and time—control every cup's quality
COMPONENTS:
A. Grind Size → controls extraction rate
B. Water Temperature → affects flavor compounds
C. Brew Time → determines strength & balance
VISUAL: Three interconnected gears diagram
```
---
### 6. Evidence Slide (Type 1: Comparison)
**Purpose**: Assert that one option is superior/different from another.
**Structure**:
```
HEADING: [Assertion stating the comparison result]
EVIDENCE:
- Table or side-by-side comparison (A vs B)
- Key differentiators highlighted
- Visual: comparison table, bar chart (grouped/stacked), or Venn diagram
SOURCE: [Citation]
```
**Example**:
```
HEADING: Burr grinders produce uniform particles, while blade grinders create inconsistent sizes
EVIDENCE:
- Burr: 85% particles within 5% of target size
- Blade: Only 40% particles within target range; 30% "fines" that over-extract
- Visual: Histogram comparing particle size distribution
SOURCE: Coffee Research Institute, 2024
```
---
### 7. Evidence Slide (Type 2: Trend Over Time)
**Purpose**: Assert a trend or change over time.
**Structure**:
```
HEADING: [Assertion about the trend direction/magnitude]
EVIDENCE:
- Time-series data points
- Annotation of key events or inflection points
- Visual: line chart, area chart, or combo chart
SOURCE: [Citation]
```
**Example**:
```
HEADING: Optimal extraction occurs between 195-205°F, with quality dropping sharply outside this range
EVIDENCE:
- Peak flavor score at 200°F: 8.7/10
- Below 190°F: sour, under-extracted (score 4.2/10)
- Above 210°F: bitter, over-extracted (score 3.8/10)
- Visual: Line chart with shaded optimal zone
SOURCE: Specialty Coffee Association Temperature Study, 2023
```
---
### 8. Evidence Slide (Type 3: Process / Steps)
**Purpose**: Assert that following a sequence leads to a result.
**Structure**:
```
HEADING: [Assertion about the process outcome]
STEPS:
1. [Step 1 - action verb + brief description]
2. [Step 2]
3. [Step 3]
4. [Step 4]
VISUAL: Flowchart, numbered diagram, or timeline
```
**Example**:
```
HEADING: Four simple steps ensure consistent pour-over coffee every time
STEPS:
1. Weigh 20g coffee, grind to medium-fine (sand texture)
2. Heat water to 200°F, wet filter to remove paper taste
3. Bloom for 30 seconds with 40g water, then pour in circles to 320g total
4. Finish brew at 3:00-3:30 minutes
VISUAL: Four-panel illustrated timeline
```
---
### 9. Evidence Slide (Type 4: Data Breakdown / Composition)
**Purpose**: Assert how parts contribute to a whole.
**Structure**:
```
HEADING: [Assertion about the composition or breakdown]
EVIDENCE:
- Percentage breakdown by category
- Contribution of each component
- Visual: stacked bar/area chart, treemap, or waterfall chart
SOURCE: [Citation]
```
**Example**:
```
HEADING: Coffee flavor compounds extract in three phases, with sugars peaking at 2 minutes
EVIDENCE:
- Acids: 30% extracted in first 60 sec
- Sugars: 50% extracted at 90-150 sec (peak flavor)
- Bitter compounds: 20% extracted after 180 sec (avoid over-extraction)
- Visual: Stacked area chart showing compound % over time
SOURCE: Coffee Chemistry Lab, UC Davis, 2024
```
---
### 10. Risk & Mitigation
**Purpose**: Assert that identified risks are manageable with specific actions.
**Structure**:
```
HEADING: [Assertion that risks can be controlled/mitigated]
RISKS & MITIGATIONS:
- Risk 1: [Brief description] → Mitigation: [Action]
- Risk 2: [Brief description] → Mitigation: [Action]
- Risk 3: [Brief description] → Mitigation: [Action]
VISUAL: Risk matrix (likelihood × impact) or mitigation table
```
**Example**:
```
HEADING: Common brewing pitfalls are easily avoided with simple adjustments
RISKS & MITIGATIONS:
- Bitter coffee → Reduce water temp to 195°F or shorten brew time by 30 sec
- Weak coffee → Increase coffee dose by 2g or extend brew time by 20 sec
- Sour coffee → Raise water temp to 205°F or use finer grind
VISUAL: Troubleshooting flowchart
```
---
### 11. Case Study / Example
**Purpose**: Assert that a real-world example demonstrates the approach's effectiveness.
**Structure**:
```
HEADING: [Assertion about what the case demonstrates]
CASE DETAILS:
- Context: [Who, what, when]
- Challenge: [Problem faced]
- Action: [Solution applied]
- Result: [Quantified outcome]
VISUAL: Before/after comparison or result metrics
SOURCE: [Citation or attribution]
```
**Example**:
```
HEADING: Adjusting grind size alone improved home brewer satisfaction from 40% to 85%
CASE DETAILS:
- Context: 50-person home brewer cohort, 4-week trial
- Challenge: Inconsistent flavor, 40% satisfaction baseline
- Action: Switched from blade to burr grinder, calibrated grind size per method
- Result: Satisfaction rose to 85%, "bad cup" rate dropped from 32% to 6%
VISUAL: Before/after bar chart + satisfaction curve
SOURCE: Coffee Education Center, Seattle, 2024
```
---
### 12. Roadmap / Timeline
**Purpose**: Assert that a phased approach achieves milestones on schedule.
**Structure**:
```
HEADING: [Assertion about timeline feasibility or sequence]
PHASES:
- Phase 1: [Milestone] by [Date]
- Phase 2: [Milestone] by [Date]
- Phase 3: [Milestone] by [Date]
- Phase 4: [Milestone] by [Date]
VISUAL: Gantt chart, timeline, or milestone roadmap
```
**Example**:
```
HEADING: Four-week progression builds brewing skills from beginner to confident home barista
PHASES:
- Week 1: Master grind size (try 3 grind settings, pick best)
- Week 2: Dial in water temperature (test 195°F, 200°F, 205°F)
- Week 3: Optimize brew time (adjust by 15-sec increments)
- Week 4: Combine variables, replicate best cup 3× consistently
VISUAL: Four-week timeline with icons
```
---
### 13. Conclusion & Call to Action (CTA)
**Purpose**: Restate the main conclusion and prompt immediate action.
**Structure**:
```
HEADING: [Restatement of main conclusion]
CTA: [Specific action with deadline/next step]
SUPPORTING POINTS (optional):
- Recap key benefit 1
- Recap key benefit 2
- Recap key benefit 3
VISUAL: Summary icon or "Next Steps" checklist
```
**Example**:
```
HEADING: Mastering grind, temp, and time transforms every home cup into a cafe-quality experience
CTA: Pick one technique from today's session and try it with your next brew
KEY TAKEAWAYS:
- Grind size controls extraction rate—match it to your method
- Water temp 195-205°F unlocks balanced flavors
- Brew time fine-tunes strength and prevents bitterness
VISUAL: Three-point checklist with icons
```
---
### 14. Backup Slides
**Purpose**: Provide detailed data, methodology, or FAQs without cluttering main deck.
**Structure**:
```
HEADING: [Topic or Question]
CONTENT: Detailed table, extended data, formulas, references
NOTE: "Backup slide—not presented, available for Q&A"
```
**Example Backup Slides**:
- Detailed brewing ratio chart (1:15 to 1:18)
- Equipment comparison matrix (10 grinder models)
- Troubleshooting guide (problem → likely cause → fix)
- Methodology: How we measured extraction % and flavor scores
- References & Further Reading
---
## Micro-Templates (Quick Patterns for Specific Data Types)
### A. Comparison (A vs B)
| Feature | Option A | Option B | Winner |
|---------|----------|----------|--------|
| Cost | $X | $Y | A/B |
| Speed | Fast | Slow | A |
| Quality | Good | Excellent | B |
**Heading Example**: "Option B delivers superior quality despite higher upfront cost"
---
### B. Pyramid Summary (Key Takeaways)
```
MAIN POINT
├── Supporting Point 1
│ ├── Evidence 1a
│ └── Evidence 1b
├── Supporting Point 2
│ ├── Evidence 2a
│ └── Evidence 2b
└── Supporting Point 3
├── Evidence 3a
└── Evidence 3b
```
---
### C. Process (4 Steps)
```
1️⃣ [Step 1] → 2️⃣ [Step 2] → 3️⃣ [Step 3] → 4️⃣ [Step 4] → ✅ Result
```
---
### D. KPI Dashboard
```
┌─────────────┬─────────────┬─────────────┐
│ Metric 1 │ Metric 2 │ Metric 3 │
│ 85% ↑ │ $1.2M ↓ │ 4.2/5 → │
│ vs. 78% LY │ vs. $1.5M │ flat │
└─────────────┴─────────────┴─────────────┘
```
**Heading Example**: "Customer satisfaction rose 7 points while costs dropped 20%"
---
### E. Geographic / Regional Distribution
**Visual**: Choropleth map or bar chart by region
**Heading Example**: "West Coast accounts for 60% of premium coffee sales"
---
### F. Funnel (Conversion Process)
```
Stage 1: 1000 visitors
↓ 40% convert
Stage 2: 400 sign-ups
↓ 25% convert
Stage 3: 100 purchases
```
**Heading Example**: "10% end-to-end conversion beats industry average by 3 points"
---
### G. Pareto (80/20)
**Visual**: Bar chart (descending) + cumulative line overlay
**Heading Example**: "Top 3 issues account for 80% of customer complaints"
---
### H. Sensitivity / Scenario Analysis
| Scenario | Assumption 1 | Assumption 2 | Result |
|----------|--------------|--------------|--------|
| Best Case | High | Low | $500K |
| Base Case | Medium | Medium | $300K |
| Worst Case | Low | High | $100K |
**Heading Example**: "Base case ROI of $300K remains positive even in worst-case scenario"
---
### I. Cost Structure (Waterfall)
```
Starting Value: $1000
- Cost A: -$200
- Cost B: -$150
- Cost C: -$100
+ Revenue: +$600
= Final Value: $1150
```
**Visual**: Waterfall chart showing cumulative impact
---
### J. Contribution (Stacked Bar/Area)
**Visual**: Stacked bar or area chart showing each component's contribution to total
**Heading Example**: "Product A contributes 55% of total revenue despite being only 30% of units sold"
---
## Template Selection Decision Tree
**Use this decision tree to pick the right template**:
1. **Is this the first or last slide?**
- First → Cover Slide (Template 1)
- Last → Conclusion & CTA (Template 13)
2. **Are you introducing the structure?**
- Yes → Table of Contents (Template 2)
3. **Are you explaining why something matters?**
- Problem → Problem Statement (Template 3)
- Opportunity → Opportunity/Goal (Template 4)
4. **Are you presenting the solution approach?**
- Yes → Solution Overview (Template 5)
5. **Are you showing evidence?**
- Comparing options → Comparison (Template 6)
- Showing trend → Trend Over Time (Template 7)
- Explaining process → Process/Steps (Template 8)
- Breaking down data → Data Breakdown (Template 9)
6. **Are you addressing concerns?**
- Yes → Risk & Mitigation (Template 10)
7. **Are you showing proof?**
- Yes → Case Study (Template 11)
8. **Are you showing timeline?**
- Yes → Roadmap/Timeline (Template 12)
9. **Is this extra detail for Q&A?**
- Yes → Backup Slides (Template 14)
---
## Best Practices
1. **Consistency**: Use the same template for similar slide types throughout the deck
2. **Hierarchy**: Maintain consistent visual hierarchy (heading > subheading > body > footer)
3. **White Space**: Don't fill every pixel—leave breathing room (see STYLE-GUIDE.md)
4. **One Idea**: Each slide conveys exactly one testable assertion
5. **Evidence-First**: Body content supports the heading assertion with visuals/data, not long text
6. **Accessibility**: All templates must meet WCAG AA contrast requirements (see STYLE-GUIDE.md)
---
**Next Steps**: Once you've selected templates for all slides, proceed to Stage 4 (Evidence & Charts) in WORKFLOW.md.

446
ppt-creator/references/VIS-GUIDE.md Normal file
View File

@@ -0,0 +1,446 @@
# Data Visualization Selection & Labeling Standards
> **Purpose**: Choose the right chart type for your data and message, then label it properly for clarity and accessibility. This guide follows industry best practices from the Financial Times, Edward Tufte, and the Assertion-Evidence framework.
---
## Chart Selection Dictionary
Use this dictionary to match your **question/message** to the **best chart type**.
### 1. Change Over Time
**Question**: How has X changed over time?
**Chart Types**:
- **Line chart**: Best for continuous time series, 1-6 series max
- Use case: Daily stock prices, monthly sales, annual growth
- Avoid: >6 overlapping lines (use small multiples instead)
- **Area chart**: Emphasizes magnitude of change
- Use case: Showing volume/scale in addition to trend
- Stacked area: Show composition over time (max 4-5 categories)
- **Column/bar chart**: Discrete time periods with few data points
- Use case: Quarterly results, yearly comparisons (≤12 bars)
- Avoid: Too many bars (switch to line if >12 periods)
- **Step chart**: Values change at specific moments (not gradual)
- Use case: Policy changes, price updates, version releases
**Heading Example**: "Monthly revenue grew 35% from Jan to Oct, with sharp acceleration in Q3"
---
### 2. Comparison / Ranking
**Question**: How do categories compare to each other?
**Chart Types**:
- **Horizontal bar chart**: Best for comparing categories (especially with long labels)
- Use case: Ranking cities, products, departments by revenue/size
- Advantage: Easy to read category names, natural left-to-right reading
- **Grouped bar chart**: Compare 2-3 metrics across categories
- Use case: Revenue vs. Profit by product line
- Avoid: >3 groups (gets cluttered)
- **Dot plot**: Precise value comparisons with minimal ink
- Use case: Salary ranges, performance scores by team
- **Slope chart**: Compare two time points across categories
- Use case: "Before vs. After" for 5-10 items
**Heading Example**: "Product A outsells Product B by 2:1 across all regions"
---
### 3. Distribution
**Question**: How is data spread out? Where do most values fall?
**Chart Types**:
- **Histogram**: Show frequency distribution of continuous data
- Use case: Age distribution, income ranges, response times
- Bins: 10-20 bins for most datasets
- **Box plot (box-and-whisker)**: Show median, quartiles, outliers
- Use case: Compare distributions across groups (e.g., test scores by class)
- Advantage: Compact, shows outliers clearly
- **Violin plot**: Combines box plot with density curve
- Use case: Similar to box plot but shows shape of distribution
- **Strip plot / beeswarm**: Show individual data points
- Use case: Small datasets (n < 100) where you want to show every point
**Heading Example**: "80% of customers spend between $20-$50, with a long tail of high spenders"
---
### 4. Correlation / Relationship
**Question**: How do two variables relate to each other?
**Chart Types**:
- **Scatter plot**: Show relationship between two continuous variables
- Use case: Height vs. weight, ad spend vs. sales, price vs. demand
- Enhancement: Add trend line with R² value
- Color: Use 3rd variable for color (e.g., region, category)
- Size: Use 4th variable for bubble size (→ bubble chart)
- **Connected scatter plot**: Show how relationship changes over time
- Use case: GDP vs. life expectancy over decades
- **Heatmap**: Show correlation matrix for many variables
- Use case: Feature correlations in ML, survey question relationships
**Heading Example**: "Higher ad spend correlates strongly with sales (R² = 0.82), but returns diminish above $10K/month"
---
### 5. Part-to-Whole / Composition
**Question**: What are the parts of the whole? How do they contribute?
**Chart Types**:
- **Stacked bar chart**: Show composition across categories
- Use case: Revenue breakdown by product line, customer segments by region
- Limit: Max 4-5 segments (more gets hard to read)
- 100% stacked: Emphasize proportions instead of absolute values
- **Treemap**: Show hierarchical part-to-whole with nested rectangles
- Use case: Budget allocation, file system sizes, market share
- Advantage: Efficient use of space, shows hierarchy
- **Waterfall chart**: Show cumulative effect of sequential additions/subtractions
- Use case: Starting revenue → costs → profit, bridge from last year to this year
- **Pie chart**: **Use sparingly** (only for 2-3 slices)
- Acceptable: "52% approved, 48% rejected" (binary or near-binary)
- Avoid: >3 slices, 3D effects, exploded slices
- Better alternative: Stacked bar or treemap in most cases
**Heading Example**: "Payroll accounts for 60% of operating costs, twice the industry average"
---
### 6. Flow / Connection
**Question**: How do things move between states or groups?
**Chart Types**:
- **Sankey diagram**: Show flow quantities between nodes
- Use case: Energy flow, budget allocation, customer journey stages
- Limit: ≤10 nodes (gets messy beyond that)
- **Chord diagram**: Show connections between entities
- Use case: Trade relationships, migration patterns
- Avoid: >8 entities (overlapping connections get hard to trace)
- **Network graph**: Show relationships and clusters
- Use case: Social networks, dependency graphs, org charts
**Heading Example**: "70% of website visitors from organic search convert directly to purchase without revisiting"
---
### 7. Geographic / Spatial
**Question**: How does data vary by location?
**Chart Types**:
- **Choropleth map**: Color regions by value (e.g., states, countries)
- Use case: Sales by state, election results, disease prevalence
- Color: Use sequential scale (light to dark) for continuous data; diverging scale (red-white-blue) for pos/neg
- Avoid: Small regions with high variation (perception bias)
- **Dot density map**: Show individual occurrences as dots
- Use case: Store locations, earthquake epicenters
- **Proportional symbol map**: Circle size = quantity at location
- Use case: Population by city, sales by store location
- **Bar chart by region**: Alternative to choropleth when precise values matter
- Use case: Revenue by country (sorted bar chart)
**Heading Example**: "California and Texas account for 45% of total US sales, with sparse coverage in the Midwest"
---
### 8. Deviation / Variance
**Question**: How far is each value from a reference point (mean, target, budget)?
**Chart Types**:
- **Diverging bar chart**: Show positive and negative deviations from zero/baseline
- Use case: Above/below target, profit/loss by category
- Color: Positive = green/blue, negative = red/orange
- **Bullet chart**: Compact way to show actual vs. target with context
- Use case: KPI dashboards (actual, target, good/satisfactory/poor ranges)
- **Lollipop chart**: Similar to bar chart but with less ink
- Use case: Deviations from average or baseline
**Heading Example**: "Q3 sales exceeded target by 12%, while Q1 and Q2 underperformed by 8% and 5%"
---
### 9. Magnitude (Absolute Sizes)
**Question**: How big is each value (without comparison)?
**Chart Types**:
- **Bar chart**: Standard choice for showing sizes/quantities
- Orientation: Horizontal if category names are long; vertical for time series
- **Column chart**: Vertical bars for time-based or ordinal categories
- **Packed circles**: Alternative to bar chart (less precise but compact)
- Use case: Market share visualization, bubble chart without x/y axes
**Heading Example**: "Product A generated $2.3M in Q4, our highest single-product quarter ever"
---
### 10. Table (When Not to Visualize)
**When to use a table instead of a chart**:
- **Precision matters**: Users need exact values, not just trends
- **Lookup use case**: Users will search for specific row/column intersections
- **Many dimensions**: >3 categorical dimensions (chart would be too complex)
- **Small dataset**: 3-10 data points (chart adds no value)
- **Mixed data types**: Text + numbers + categories
**Heading Example**: "Detailed cost breakdown by department and expense category"
---
## Chart Selection Quick Reference
| Your Goal | Question Pattern | Best Chart Type |
|-----------|------------------|-----------------|
| Show trend | How has X changed over time? | Line, area |
| Compare categories | Which is bigger/better? | Horizontal bar |
| Show distribution | Where do most values fall? | Histogram, box plot |
| Show correlation | How do X and Y relate? | Scatter plot |
| Show composition | What are the parts? | Stacked bar, treemap |
| Show flow | How do things move? | Sankey, chord |
| Show location | Where is it happening? | Choropleth map |
| Show deviation | How far from target? | Diverging bar, bullet |
| Show magnitude | How big is it? | Bar chart |
| Show exact values | Need precise lookup? | Table |
---
## Labeling & Annotation Standards
### Required Elements for All Charts
1. **Chart Title / Assertion Heading**
- Use the slide's assertion sentence (not a generic "Revenue Chart")
- Example: ✅ "Q3 revenue exceeded plan by 15% despite supply chain headwinds"
- Example: ❌ "Quarterly Revenue Comparison"
2. **Axis Labels & Units**
- X-axis: Label with variable name and unit (e.g., "Month (2024)")
- Y-axis: Label with variable name and unit (e.g., "Revenue ($1000s)" or "Response Time (ms)")
- Include units in axis label OR directly on values (e.g., "$5M" on bar)
3. **Data Labels** (when helpful)
- Add value labels on bars/points if precision matters and space allows
- Format consistently: "$1.2M" not "$1,234,567"
- Avoid clutter: label only key points (e.g., first, last, min, max)
4. **Legend** (when multiple series)
- Place legend close to data (top-right or right side preferred)
- Order legend to match visual order (e.g., top-to-bottom matches line stacking)
- Consider direct labeling (labels next to lines) instead of separate legend
5. **Data Source**
- Always cite source in footer: "Source: [Organization, Year]" or "Data: [Source]"
- If internal data: "Source: Internal analysis" or "Data: Company sales database"
- If estimated/projected: "Projected values based on [methodology]"
6. **Time Range & Scope**
- Specify date range: "Jan-Dec 2024" or "FY2023-2024"
- Note exclusions: "Excluding returns and refunds" or "Top 10 markets only"
7. **Color Key** (for categorical colors)
- If using color to encode categories, provide a legend or direct labels
- Avoid relying solely on color (see Accessibility section below)
---
## Number Formatting Best Practices
### Decimal Places
- **Percentages**: 1 decimal place (e.g., "15.3%")
- Exception: Very small percentages (e.g., "0.02%") may need 2 decimals
- **Currency**: Round to nearest appropriate unit
- Small values: "$1,234.56"
- Large values: "$1.2M" or "$5.6B" (not "$5,600,000,000")
- **Scientific values**: 2-3 significant figures (e.g., "3.14 × 10⁶")
- **Counts**: No decimals (e.g., "1,543 customers" not "1,543.0")
### Consistency
- **Within a chart**: Use same decimal places for all values
- **Across charts**: Use same units and rounding for same metric type
- **In tables**: Align decimal points vertically
### Large Numbers
- Use thousands separators: "1,234,567" (US/UK) or "1 234 567" (SI)
- Use abbreviations for very large numbers:
- K = thousand (1,000)
- M = million (1,000,000)
- B = billion (1,000,000,000)
- Be consistent: Don't mix "1.2M" and "850K" with "950,000" in same chart
---
## Color & Accessibility
### WCAG 2.1 AA Contrast Requirements
**Text Contrast**:
- Normal text (< 18pt): Minimum 4.5:1 contrast ratio against background
- Large text (≥ 18pt or ≥ 14pt bold): Minimum 3:1 contrast ratio
**UI Components & Charts**:
- Chart elements (bars, lines, dots): Minimum 3:1 contrast against adjacent colors and background
- Active/inactive states: Must have 3:1 contrast difference
**Color Alone Insufficient**:
- Do NOT use color as the only way to convey information
- Add patterns, labels, or shapes for colorblind users
- Example: In a line chart with 3 series, use solid/dashed/dotted lines + color
### Colorblind-Friendly Palettes
**Safe Palettes** (work for deuteranopia, protanopia, tritanopia):
- **Categorical** (up to 5 colors):
- Blue (#2563EB), Orange (#F97316), Green (#10B981), Purple (#8B5CF6), Gray (#6B7280)
- Avoid: Red + Green together (most common colorblindness)
- **Sequential** (light to dark for continuous data):
- Blues: #EFF6FF → #1E40AF
- Greens: #ECFDF5 → #065F46
- Oranges: #FFF7ED → #9A3412
- **Diverging** (for pos/neg or two extremes):
- Blue-White-Orange: #1E40AF ↔ #FFFFFF ↔ #9A3412
- Purple-White-Green: #7C3AED ↔ #FFFFFF ↔ #059669
**Test Tools**:
- Use online simulators (e.g., Coblis, Color Oracle) to preview charts in colorblind modes
- Check contrast ratios with WebAIM Contrast Checker or browser dev tools
---
## Chart Dos and Don'ts
### DO
✅ Start Y-axis at zero for bar/column charts (shows proportions honestly)
✅ Use horizontal bars when category names are long (easier to read)
✅ Sort bars by value (descending or ascending) unless there's a meaningful order (e.g., time, ranking)
✅ Annotate key data points (peaks, troughs, inflection points)
✅ Use a reference line or shaded area to show targets, benchmarks, or context
✅ Combine chart types when appropriate (e.g., bar + line combo for actuals + trend)
✅ Use small multiples for comparing many series (instead of overlapping 10+ lines)
### DON'T
❌ Use 3D effects, drop shadows, or gratuitous decoration (Tufte's "chartjunk")
❌ Use pie charts for >3 slices or when precise comparison matters (human eye bad at angles)
❌ Truncate Y-axis to exaggerate small differences (unless clearly marked)
❌ Use dual Y-axes unless absolutely necessary (confusing; prefer indexed scales)
❌ Overload with grid lines (use sparingly, light gray at most)
❌ Use default Excel/PowerPoint colors (often poor contrast and not colorblind-friendly)
❌ Put more than 5-7 series on one chart (use small multiples or filter to top N)
---
## Assertion-Evidence Chart Writing
**Principle**: The slide heading states the **conclusion** (assertion), and the chart provides the **evidence** to support it.
### Example Workflow
**Data**: Monthly sales Jan-Dec 2024 (trend upward)
**Bad Slide**:
- Heading: "Monthly Sales 2024"
- Chart: Line chart with no annotation
- Problem: Heading is a topic label, not a testable claim
**Good Slide**:
- Heading: "Monthly sales grew 35% in 2024, with sharp acceleration in Q3"
- Chart: Line chart with:
- Jan-Dec 2024 on X-axis
- Revenue ($1000s) on Y-axis
- Annotation: "Q3 spike: +18% MoM" with arrow
- Source footer: "Source: Internal sales database"
- Why it works: Heading makes a claim; chart proves it with specific visual evidence
---
## Advanced: When to Use Specialized Charts
### Waterfall Chart
**Use when**: Showing cumulative effect of sequential additions/subtractions
**Example**: "Starting revenue $1M → -$200K costs → -$100K returns → +$400K upsells = $1.1M final"
**Heading**: "Upsells and renewals offset a $300K loss from returns and operational costs"
---
### Sankey Diagram
**Use when**: Showing flow quantities between stages/categories
**Example**: Website traffic sources → landing pages → conversion outcomes
**Heading**: "Organic search drives 60% of traffic but only 30% of conversions, while email drives 15% of traffic but 40% of conversions"
**Limit**: ≤10 nodes (more gets visually overwhelming)
---
### Small Multiples (Faceted Charts)
**Use when**: Comparing the same chart across many categories or time periods
**Example**: Monthly sales trend for each of 12 regions (12 mini line charts in a grid)
**Heading**: "All regions show positive growth, but West and South outpace East and Midwest by 2×"
**Advantage**: Easier to compare than 12 overlapping lines on one chart
---
## Placeholder Charts (When Data Is Missing)
If user doesn't provide data, create a **placeholder description** with:
1. **Chart type**: "Line chart" / "Stacked bar chart" / "Scatter plot"
2. **Axes & variables**: "X-axis: Month (Jan-Dec), Y-axis: Revenue ($)"
3. **Expected pattern**: "Upward trend with Q3 spike"
4. **Required data fields**: "Need: month, revenue_usd, optional: target_revenue"
5. **Annotation points**: "Label Q3 peak, show +35% YoY growth"
**Example**:
```
PLACEHOLDER: Line chart
- X-axis: Month (Jan-Dec 2024)
- Y-axis: Monthly Revenue ($1000s)
- Pattern: Steady growth Jan-Aug, sharp spike in Sep-Oct, plateau Nov-Dec
- Data required: month (date), revenue (numeric, USD)
- Annotations: Highlight Sep-Oct spike with "+18% MoM" label
- Source: [To be provided by user]
```
---
## References & Further Learning
1. **Financial Times Visual Vocabulary**
- Comprehensive chart selection guide for journalism and business
- https://github.com/Financial-Times/chart-doctor/tree/main/visual-vocabulary
2. **Edward Tufte: The Visual Display of Quantitative Information**
- Classic text on data visualization principles (minimize chartjunk, maximize data-ink ratio)
3. **Assertion-Evidence Framework** (Michael Alley)
- Research-backed method for scientific and technical presentations
- https://www.assertion-evidence.com/
4. **WCAG 2.1 Contrast Guidelines**
- Web Content Accessibility Guidelines for color contrast
- https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
5. **ColorBrewer / Coblis Colorblind Simulator**
- Tools for selecting colorblind-friendly palettes
- https://colorbrewer2.org / https://www.color-blindness.com/coblis-color-blindness-simulator/
---
**Next Steps**: Once you've selected chart types using this guide, proceed to Stage 5 (Layout & Accessibility) in WORKFLOW.md to finalize visual style.

573
ppt-creator/references/WORKFLOW.md Normal file
View File

@@ -0,0 +1,573 @@
# PPT Creation Workflow
> **From Simple Topic to Presentation-Ready Output**
>
> This workflow guides you through 10 stages, from gathering user intent to packaging final deliverables. Each stage has clear inputs, actions, and outputs. Follow this sequence to ensure consistent, high-quality results.
---
## Stage 0: Archive Input
**Goal**: Capture the raw user request and document all assumptions.
**Actions**:
1. Record the user's original request verbatim
2. Document which intake questions were answered vs. defaulted
3. List all assumptions made (from INTAKE.md defaults)
4. Note any data files or assets provided
5. Create a `/output/` directory for all deliverables
**Output**:
- `archive.txt` containing:
- Original user request
- Answered questions (with values)
- Defaulted questions (with safe defaults applied)
- Assumptions and limitations
**Example**:
```
ORIGINAL REQUEST: "Make me a presentation about coffee"
ANSWERED QUESTIONS:
- Audience: coffee enthusiasts
- Duration: 10 minutes
- Goal: improve home brewing
- Data available: none
DEFAULTED QUESTIONS:
- Tone: professional, clear, friendly (default)
- Format: slides.md + charts (default)
- Scope: coffee brewing + 1 layer related (default)
ASSUMPTIONS:
- No brand constraints → using neutral theme
- No specific CTA → using "try new methods at home"
```
---
## Stage 1: Structure Goals
**Goal**: Transform vague objectives into a clear, actionable CTA.
**Actions**:
1. Identify the **audience** (who)
2. Define the **action** (what they should do)
3. Specify the **timing** (when/by when)
4. Combine into a one-sentence goal: "After this presentation, [audience] will [action] by [timing]"
**Output**:
- One-sentence goal statement
- Clear call-to-action (CTA) for the final slide
**Example**:
```
INPUT: "I want them to improve their home brewing"
OUTPUT: "After this presentation, coffee enthusiasts will try at least one new brewing technique within the next week."
CTA: "Pick one technique from today's session and try it with your next cup."
```
---
## Stage 2: Storyline (Pyramid Principle)
**Goal**: Structure the argument using the Pyramid Principle: one top-level conclusion supported by 3-5 first-level reasons, each backed by evidence.
**Actions**:
1. Write the **one-sentence conclusion** (top of pyramid)
2. Identify **3-5 first-level reasons** that support the conclusion
3. For each reason, list **2-3 pieces of evidence** (data, examples, case studies, diagrams)
4. Ensure logical flow: conclusion → reasons → evidence
**Output**:
- Pyramid structure diagram
- Story spine summary
**Example**:
```
CONCLUSION: Mastering three variables—grind size, water temperature, and brew time—unlocks consistently great coffee at home.
REASON 1: Grind size controls extraction rate
- Evidence 1a: Finer grind = more surface area = faster extraction
- Evidence 1b: Diagram showing grind sizes from espresso to French press
- Evidence 1c: Over-extracted (bitter) vs. under-extracted (sour) flavor profiles
REASON 2: Water temperature affects solubility
- Evidence 2a: 195-205°F extracts balanced flavors
- Evidence 2b: Chart showing temperature vs. extraction compounds
- Evidence 2c: Cold brew example (low temp, long time)
REASON 3: Brew time determines strength and flavor balance
- Evidence 3a: Pour-over: 2-4 min; French press: 4 min; espresso: 25-30 sec
- Evidence 3b: Timeline diagram of brewing methods
- Evidence 3c: Case study: adjusting brew time to fix weak/bitter coffee
SUPPORTING REASON 4: Simple equipment upgrades improve consistency
- Evidence 4a: Burr grinder vs. blade grinder
- Evidence 4b: Kitchen thermometer for precise temperature
- Evidence 4c: Digital scale for consistent ratios
```
---
## Stage 3: Outline & Slide Titles (Assertion-Style)
**Goal**: Convert the pyramid structure into a 12-15 slide outline with assertion-style headings.
**Actions**:
1. Start with **cover slide** (title = main conclusion)
2. Add **table of contents** (3-5 chapters matching first-level reasons)
3. For each reason, create **2-3 slides** with assertion headings (complete sentences, not topic labels)
4. Add **conclusion & CTA slide**
5. Optionally add **backup slides** for extra details
**Output**:
- Slide-by-slide outline with assertion headings
- Estimated timing per slide (45-60 seconds each)
**Assertion Heading Rules**:
- ✅ "Finer grind size extracts flavors faster and more completely"
- ❌ "Grind Size" (topic label)
- ✅ "Water between 195-205°F produces balanced, full-bodied coffee"
- ❌ "Temperature Control" (topic label)
**Example Outline**:
```
1. COVER: Mastering Three Variables Unlocks Consistently Great Coffee at Home
2. TABLE OF CONTENTS: Grind Size • Water Temperature • Brew Time • Equipment
3. PROBLEM: Inconsistent home coffee wastes beans and disappoints drinkers
4. Finer grind size extracts flavors faster and more completely
5. Grind size must match your brewing method to avoid over- or under-extraction
6. Water between 195-205°F produces balanced, full-bodied coffee
7. Cold brew demonstrates how low temperature requires extended time
8. Brew time determines coffee strength and flavor balance
9. Each brewing method has an optimal time window for best results
10. Adjusting brew time fixes common problems like bitterness and weakness
11. Simple equipment upgrades—burr grinder, thermometer, scale—ensure consistency
12. CONCLUSION & CTA: Pick one technique from today and try it with your next cup
13. BACKUP: Detailed brewing ratio chart (1:15 to 1:18)
14. BACKUP: Troubleshooting guide (problem → likely cause → fix)
```
---
## Stage 4: Evidence & Charts
**Goal**: Select the best chart type for each piece of evidence and generate visuals (or placeholders).
**Actions**:
1. For each slide, identify the **evidence type** (comparison, trend, distribution, process, etc.)
2. Use **VIS-GUIDE.md Chart Selection Dictionary** to pick the chart type
3. If **data is available**, call `chartkit.py` to generate PNG charts
4. If **no data**, create a **placeholder description** + list of required data fields
5. Ensure all charts have:
- Axis labels and units
- Data source citation
- Accessible color contrast (WCAG AA)
**Output**:
- Chart specifications for each slide
- PNG files in `/output/assets/` (if data available)
- Placeholder descriptions (if no data)
**Example**:
```
SLIDE 4: "Finer grind size extracts flavors faster and more completely"
EVIDENCE: Diagram showing grind sizes from espresso to French press
CHART TYPE: Horizontal scale with icons and labels
DATA REQUIRED: [none—illustrative diagram]
ACTION: Create placeholder diagram description
PLACEHOLDER: "Horizontal scale showing 5 grind sizes: espresso (fine powder) → pour-over (sand) → drip (table salt) → French press (coarse salt) → cold brew (peppercorns). Each labeled with particle size range."
SLIDE 6: "Water between 195-205°F produces balanced, full-bodied coffee"
EVIDENCE: Chart showing temperature vs. extraction compounds
CHART TYPE: Stacked area chart (temperature on x-axis, compounds on y-axis)
DATA REQUIRED: Temperature (°F), extraction % for acids, sugars, bitter compounds
ACTION: If data provided → chartkit.py; else → placeholder
PLACEHOLDER: "Stacked area chart: X-axis 160-212°F, Y-axis compound %. Three layers: acids (peak 185°F), sugars (peak 200°F), bitter compounds (peak 210°F). Optimal zone highlighted 195-205°F."
```
---
## Stage 5: Layout & Accessibility
**Goal**: Apply consistent visual style and ensure WCAG AA accessibility.
**Actions**:
1. Apply **STYLE-GUIDE.md** specifications:
- Canvas: 16:9, safe margins ≥ 48px
- Fonts: Heading 34-40pt, Body 18-22pt
- Line spacing: Heading 1.1, Body 1.3
- Colors: Dark ink #1F2937, Accent #2563EB, Emphasis #DC2626
2. Check **contrast ratios** (text ≥ 4.5:1, UI elements ≥ 3:1)
3. Add **alt text** for all charts and images
4. Ensure **page density** ≤ 70 words per slide (excluding captions)
5. Unify **units and decimal places** across all data
**Output**:
- Visual style specification document
- Accessibility checklist (checked)
**Example**:
```
SLIDE 4 LAYOUT:
- Heading: "Finer grind size extracts flavors faster and more completely" (36pt, #1F2937, Source Han Sans)
- Body: Horizontal grind scale diagram (alt text: "Five coffee grind sizes from fine espresso powder to coarse cold brew peppercorns")
- Footer: Source citation in 14pt, #6B7280
- Word count: 18 words (within 70-word limit)
- Contrast: Heading on white background = 16.1:1 ✓
```
---
## Stage 6: Speaker Notes
**Goal**: Write 45-60 second speaker notes for each slide.
**Actions**:
1. Follow this structure for each slide:
- **Opening** (5-10 sec): Hook or transition from previous slide
- **Core Assertion** (10-15 sec): Restate the slide heading in conversational language
- **Evidence Explanation** (20-30 sec): Walk through the chart/diagram/data
- **Transition** (5-10 sec): Bridge to next slide
2. Use **natural, spoken language** (not written prose)
3. Include **timing cues** (e.g., "[PAUSE]", "[CLICK to next slide]")
4. Anticipate **common questions** and address them
**Output**:
- Speaker notes for each slide in `/output/notes.md`
- Total script timing estimate
**Example**:
```
SLIDE 4 SPEAKER NOTES (60 seconds):
[OPENING—10 sec]
"Now that we've seen the problem with inconsistent coffee, let's dive into the first variable: grind size. [CLICK]
[CORE ASSERTION—15 sec]
The key insight here is that finer grind size extracts flavors faster and more completely. Think of it like dissolving sugar: powdered sugar dissolves instantly, while sugar cubes take forever.
[EVIDENCE EXPLANATION—25 sec]
This diagram shows five common grind sizes. On the left, espresso grind looks like fine powder—tons of surface area, so water can extract flavors in just 25-30 seconds. On the right, cold brew grind is like peppercorns—much less surface area, so you need 12-24 hours to extract the same flavors. Pour-over is right in the middle: looks like sand, brews in 3-4 minutes. [PAUSE]
[TRANSITION—10 sec]
But here's the catch: you can't just use any grind size with any method. Let's see why matching grind to method is critical. [CLICK]"
```
---
## Stage 7: Self-Check & Scoring
**Goal**: Evaluate the draft presentation using CHECKLIST.md and RUBRIC.md; refine if score < 75.
**Actions**:
1. Run **CHECKLIST.md** to verify all required elements are present
2. Score using **RUBRIC.md** (10 items, 0-10 points each, total 100)
3. Identify **top 3 lowest-scoring items** and write improvement actions
4. If **total score < 75**, apply improvements and re-score (max 2 iterations)
5. If **score ≥ 75**, proceed to Stage 8
**Output**:
- Completed checklist
- Rubric scorecard with item-by-item scores
- Improvement action log (if score < 75)
**Example**:
```
ITERATION 1 SCORECARD:
1. Goal Clarity: 9/10 ✓
2. Story Structure: 8/10 ✓
3. Slide Assertions: 6/10 ⚠️ (some headings still topic-labels)
4. Evidence Quality: 7/10 ⚠️ (missing data sources)
5. Chart Fit: 8/10 ✓
6. Visual & Accessibility: 9/10 ✓
7. Coherence & Transitions: 7/10 ⚠️ (abrupt jump between slides 7-8)
8. Speakability: 8/10 ✓
9. Deliverables Complete: 9/10 ✓
10. Robustness: 8/10 ✓
TOTAL: 79/100 ✓ (≥75, ready to deliver)
If score was 72/100:
TOP 3 WEAKNESSES:
- Item 3 (Slide Assertions): Convert remaining topic-label headings to assertion sentences
- Item 4 (Evidence Quality): Add source citations to all charts
- Item 7 (Coherence): Add transition slide between temperature and time sections
IMPROVEMENT ACTIONS:
1. Revise slides 5, 9, 11 headings to full assertion sentences
2. Add footer citations to all charts (e.g., "Source: National Coffee Association, 2023")
3. Insert transition slide: "Now that we've mastered grind and temperature, let's tackle the third variable: time"
RE-SCORE after improvements → 78/100 ✓ (ready to deliver)
```
---
## Stage 8: Package Deliverables
**Goal**: Generate all final output files in `/output/` directory. If orchestration mode is active, automatically coordinate data synthesis, chart generation, PPTX creation, and chart insertion to deliver a complete presentation-ready PowerPoint file.
### Stage 8a: Package Markdown Deliverables (Baseline)
**Actions**:
1. Create `/output/slides.md`:
- Markdown slides with YAML frontmatter for Marp/Reveal.js
- Assertion-style headings
- Bullet points and chart placeholders
- Speaker notes in HTML comments `<!-- NOTES: ... -->`
2. Create `/output/notes.md`:
- Full speaker script with timing
- Assumptions & limitations section
- Troubleshooting Q&A
3. Create `/output/refs.md`:
- All data sources and citations
- Chart data specifications (for synthesis or user reference)
- External references and further reading
4. Create `/output/README.md`:
- File structure explanation
- Conversion instructions (if manual mode)
- Customization guide
**Output**: Markdown deliverables ready for manual conversion or orchestration processing
---
### Stage 8b: Synthesize Data (Orchestration Mode Only)
**Condition**: Activate if:
- Orchestration mode is ON
- refs.md specifies data requirements (chart data specs present)
- User did NOT upload data files
**Actions**:
1. Parse `/output/refs.md` for data specifications:
- Example: "Solar LCOE: $0.38/kWh (2010) → $0.05/kWh (2024), -87% decline"
2. Generate synthetic CSV files matching specs:
- Use realistic trends (linear/exponential/step function)
- Add noise (±3-5%) for authenticity
- Follow authoritative source calibration (IRENA/IEA/IPCC/WHO)
3. Save to `/output/data/*.csv`
4. Document synthesis methodology in `/output/data/README.md`
**Output**: `/output/data/*.csv` files ready for chart generation
**Fallback**: If pandas unavailable, skip to Stage 8c with user-provided data only
---
### Stage 8c: Generate Charts (Orchestration Mode Only)
**Condition**: Activate if orchestration mode is ON
**Actions**:
1. Create comprehensive `generate_charts.py` script:
- Read CSV data from `/output/data/` or user-provided files
- Generate all PNG charts using matplotlib
- Apply STYLE-GUIDE.md color palette and fonts
- Save to `/output/assets/*.png` (180 DPI, optimized)
2. Execute chart generation:
```bash
cd /output
uv run --with pandas --with matplotlib generate_charts.py
```
3. Verify all chart files exist and meet quality standards:
- File size: 40-150KB per chart
- Dimensions: ~10×6 inches
- Labels readable, colors distinct
**Output**: `/output/assets/*.png` (8-12 charts, publication-quality)
**Fallback**: If matplotlib unavailable, deliver PPTX with text placeholders + standalone script + installation instructions
---
### Stage 8d: Dual-Path PPTX Creation (Orchestration Mode Only)
**Condition**: Activate if orchestration mode is ON
**Strategy**: Launch TWO parallel sub-agents to generate PPTX using different technologies:
- **Path A (Marp CLI)**: Native Marp export, preserves Marp themes/directives
- **Path B (document-skills:pptx)**: Anthropic's PowerPoint skill, reveal.js-based
**Why Dual-Path?** slides.md contains Marp-specific syntax that document-skills:pptx cannot parse. Running both paths ensures compatibility and gives users styling choice.
**Actions**:
1. **Launch Path A** (Marp CLI export) via Task tool:
- Check/install Marp CLI: `npm install -g @marp-team/marp-cli`
- Export: `marp slides.md -o presentation_marp.pptx --allow-local-files --html`
- Output: `/output/presentation_marp.pptx` (Marp-styled, 200-500KB)
2. **Launch Path B** (document-skills:pptx) via Task tool (parallel):
- Pre-process slides.md: strip Marp YAML frontmatter and directives
- Convert to PPTX using document-skills:pptx
- Output: `/output/presentation_pptx.pptx` (reveal.js-styled, 200-300KB)
3. **Parallel execution**: Send single message with TWO Task calls
4. Quality checks (per path):
- File exists and opens correctly
- Slide count matches slides.md
- Speaker notes embedded
**Output**:
- Best case: Both PPTX files (user chooses preferred styling)
- Partial: One PPTX + failure documentation
- Fallback: Markdown + pandoc conversion instructions
**Detailed specs**: See `references/ORCHESTRATION_PPTX.md` Stage 8d
---
### Stage 8e: Dual-Path Chart Insertion (Orchestration Mode Only)
**Condition**: Activate if orchestration mode is ON and at least one PPTX from Stage 8d exists
**Strategy**: Insert PNG charts into existing PPTX file(s) using path-specific methods
**Actions**:
1. **Path A chart insertion** (if presentation_marp.pptx exists):
- Method: python-pptx library direct manipulation
- Script: `insert_charts_marp.py` (auto-generated)
- Output: `/output/presentation_marp_with_charts.pptx`
2. **Path B chart insertion** (if presentation_pptx.pptx exists):
- Method: document-skills:pptx editing via Task tool
- Insert 8 charts at standard positions (5.5", 2.0", width 4.0")
- Output: `/output/presentation_pptx_with_charts.pptx`
3. **Parallel execution**: If both PPTX files exist, launch both insertion tasks simultaneously
4. Chart-to-slide mapping:
- Parse slides.md for placeholders (`**[占位图表]**:`)
- Map to slide numbers (typically slides 3-10)
- Standard positioning: right column layout
5. Final quality checks:
- File size increase: 300-600KB per PPTX (charts embedded)
- Visual verification: all charts visible, no overlaps
**Output**:
- Best case: `presentation_marp_with_charts.pptx` + `presentation_pptx_with_charts.pptx` ✓ **BOTH COMPLETE**
- Partial: One complete PPTX + one with placeholders + manual instructions
- Fallback: Base PPTX + separate chart files + assembly guide
**Detailed specs**: See `references/ORCHESTRATION_PPTX.md` Stage 8e
---
### Output Examples
**Manual Mode** (`/output/` structure):
```
/output/
├── slides.md (Markdown deck, 165 lines)
├── notes.md (Speaker script, 1200 words)
├── refs.md (Citations and data specs)
└── README.md (conversion instructions)
```
**Orchestration Mode - Dual-Path** (`/output/` structure):
```
/output/
├── slides.md (Markdown source, Marp-formatted, backup)
├── notes.md (Speaker script with assumptions)
├── refs.md (Citations and data sources)
├── data/
│ ├── cost_trend.csv (synthetic data)
│ ├── capacity_growth.csv
│ └── README.md (synthesis methodology)
├── assets/
│ ├── cost_trend.png (180 DPI)
│ ├── capacity_growth.png
│ └── employment.png (8-12 charts total)
├── presentation_marp.pptx (intermediate, 210KB)
├── presentation_marp_with_charts.pptx ✓ FINAL A (557KB, Marp-styled)
├── presentation_pptx.pptx (intermediate, 200KB)
├── presentation_pptx_with_charts.pptx ✓ FINAL B (543KB, document-skills styled)
├── generate_charts.py (chart generation script)
├── insert_charts_marp.py (Marp insertion script)
└── README.md (usage guide + styling comparison)
```
**Note**: Both FINAL files contain identical content with different styling. Users can choose their preferred version or compare both.
**Note**: For orchestration implementation details, see:
- Overview and activation logic: `references/ORCHESTRATION_OVERVIEW.md`
- Data synthesis & chart generation: `references/ORCHESTRATION_DATA_CHARTS.md`
- PPTX creation & chart insertion: `references/ORCHESTRATION_PPTX.md`
---
## Stage 9: Reuse Instructions
**Goal**: Empower users to customize and extend the presentation.
**Actions**:
1. Append "5-Step Reuse Guide" to `/output/notes.md`:
- **Step 1**: Replace placeholder charts with your own data (use chartkit.py)
- **Step 2**: Customize color palette in STYLE-GUIDE.md (find/replace hex codes)
- **Step 3**: Add your logo to cover slide and footer
- **Step 4**: Adjust speaker notes for your personal style
- **Step 5**: Export to your preferred format (PPTX, PDF, Google Slides)
2. Include **chartkit.py usage examples** for common chart types
3. Provide **Markdown-to-PPTX conversion commands** (if PPTX wasn't auto-generated)
**Output**:
- Enhanced `/output/notes.md` with reuse guide
- Example commands for customization
**Example Reuse Guide**:
```
## 5-Step Guide: Customize This Presentation
### Step 1: Replace Placeholder Charts with Your Data
If you have real data, use chartkit.py to generate updated charts:
```bash
python scripts/chartkit.py \
--data your_data.csv \
--type line \
--x month \
--y revenue profit \
--out output/assets \
--filename revenue_trend.png \
--title "Monthly Revenue & Profit"
```
### Step 2: Customize Colors
Open STYLE-GUIDE.md and replace these hex codes:
- Accent: #2563EB → your brand blue
- Emphasis: #DC2626 → your brand red
Then find/replace in slides.md
### Step 3: Add Your Logo
Insert logo file in `/output/assets/logo.png`
Add to slides.md cover slide: `![Logo](assets/logo.png)`
### Step 4: Personalize Speaker Notes
Edit `/output/notes.md` to match your speaking style
Add personal anecdotes or examples
### Step 5: Export to PowerPoint
If python-pptx is available:
```bash
python -m pypandoc slides.md -o presentation.pptx
```
Or use online converters: https://www.marp.app/
```
---
## Workflow Summary Checklist
Use this checklist to track progress through all 9 stages:
- [ ] **Stage 0**: Archive input (original request, assumptions, defaults)
- [ ] **Stage 1**: Structure goals (one-sentence goal + CTA)
- [ ] **Stage 2**: Storyline (pyramid structure: conclusion → reasons → evidence)
- [ ] **Stage 3**: Outline & slide titles (12-15 slides with assertion headings)
- [ ] **Stage 4**: Evidence & charts (chart selection + chartkit.py or placeholders)
- [ ] **Stage 5**: Layout & accessibility (STYLE-GUIDE + WCAG AA compliance)
- [ ] **Stage 6**: Speaker notes (45-60 sec per slide, natural language)
- [ ] **Stage 7**: Self-check & scoring (CHECKLIST + RUBRIC, score ≥ 75)
- [ ] **Stage 8**: Package deliverables (slides.md, notes.md, refs.md, assets/)
- [ ] **Stage 9**: Reuse instructions (5-step customization guide)
---
**Next Steps**: After completing all stages, proceed to final validation with CHECKLIST.md and delivery to user.

115
ppt-creator/scripts/chartkit.py Executable file
View File

@@ -0,0 +1,115 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
chartkit.py - Minimal chart renderer for ppt-creator
Usage:
python resources/scripts/chartkit.py \
--data path/to/data.csv \
--type line \
--x date \
--y sales profit \
--out output/assets \
--filename kpi_trend.png \
--title "Monthly KPIs"
Notes:
- Requires: pandas, matplotlib
- Fallback: If packages are unavailable, print an instruction message and exit(0)
- Does not set brand-specific colors; relies on matplotlib defaults to remain readable.
"""
import argparse, sys, os
def _lazy_imports():
try:
import pandas as pd # noqa: F401
import matplotlib.pyplot as plt # noqa: F401
return True
except Exception as e:
sys.stdout.write(f"[chartkit] Missing dependency: {e}\n")
sys.stdout.write("[chartkit] Fallback: describe chart spec in text instead of rendering PNG.\n")
return False
def _read_data(path):
import pandas as pd
if path.lower().endswith(".csv"):
return pd.read_csv(path)
elif path.lower().endswith((".json", ".ndjson")):
return pd.read_json(path, lines=path.lower().endswith(".ndjson"))
else:
raise ValueError("Only CSV/JSON supported")
def _ensure_outdir(p):
os.makedirs(p, exist_ok=True)
def render_chart(df, chart_type, x, y_cols, title, out_path):
import matplotlib.pyplot as plt
fig = plt.figure()
ax = fig.gca()
if chart_type in ("line", "area"):
for col in y_cols:
ax.plot(df[x], df[col], label=str(col))
if chart_type == "area":
ax.fill_between(df[x], df[y_cols[0]], alpha=0.2)
elif chart_type in ("bar", "barh"):
import numpy as np
idx = np.arange(len(df[x]))
width = 0.8/ max(1, len(y_cols))
for i, col in enumerate(y_cols):
if chart_type == "bar":
ax.bar(idx + i*width, df[col], width, label=str(col))
else:
ax.barh(idx + i*width, df[col], width, label=str(col))
ax.set_xticks(idx + width*(len(y_cols)-1)/2)
ax.set_xticklabels(df[x], rotation=0, ha="center")
elif chart_type == "scatter":
for col in y_cols:
ax.scatter(df[x], df[col], label=str(col))
elif chart_type == "hist":
ax.hist(df[y_cols[0]], bins=20)
elif chart_type == "waterfall":
# Simple waterfall for a single series
import numpy as np
vals = df[y_cols[0]].values
cum = np.cumsum(vals) - vals
ax.bar(df[x], vals, bottom=cum)
ax.plot(df[x], cum + vals, marker="o")
else:
raise ValueError(f"Unsupported chart type: {chart_type}")
ax.set_title(title if title else "")
ax.legend(loc="best")
ax.grid(True, alpha=0.2)
fig.tight_layout()
fig.savefig(out_path, dpi=180)
plt.close(fig)
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--data", required=True)
ap.add_argument("--type", required=True, choices=["line","area","bar","barh","scatter","hist","waterfall"])
ap.add_argument("--x", required=True)
ap.add_argument("--y", nargs="+", required=True)
ap.add_argument("--out", required=True)
ap.add_argument("--filename", required=True)
ap.add_argument("--title", default="")
args = ap.parse_args()
if not _lazy_imports():
# Soft fail: print instructions for textual fallback
sys.stdout.write(f"[chartkit] Would have rendered {args.type} chart to {args.out}/{args.filename}\n")
return 0
import pandas as pd
df = _read_data(args.data)
if args.x not in df.columns:
raise SystemExit(f"[chartkit] Missing x column: {args.x}")
for c in args.y:
if c not in df.columns:
raise SystemExit(f"[chartkit] Missing y column: {c}")
_ensure_outdir(args.out)
out_path = os.path.join(args.out, args.filename)
render_chart(df, args.type, args.x, args.y, args.title, out_path)
sys.stdout.write(f"[chartkit] Saved {out_path}\n")
return 0
if __name__ == "__main__":
sys.exit(main())