@ztffn/presentation-generator-plugin 1.6.1 → 1.6.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "presentation-generator",
   "description": "Generate complete graph-based presentations from natural language briefs and project documents. Pipeline: content extraction, narrative design, deterministic graph generation, and visual styling.",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "author": {
     "name": "Huma"
   },

package/agents/presentation-style.md

@@ -30,7 +30,7 @@ These define the visual intent mapping, slide recipes, allowed data fields, and
 
 ### Step 3 — Classify each slide
 
-Walk through every node and assign a visual intent. Use the outline's `**Slide type:**` annotation if present. Otherwise infer:
+Walk through every node and assign a visual intent. Use the outline's `**Visual intent:**` annotation if present. Otherwise infer:
 
 | Position / Content Signal | Visual Intent | Treatment |
 |---|---|---|
@@ -40,7 +40,7 @@ Walk through every node and assign a visual intent. Use the outline's `**Slide t
 | Spine node with a single bold claim | `impact` | Centered, no bullets, whitespace-forward |
 | Spine or drill-down with 4+ bullet points | `workhorse` | Left-aligned, `centered: false`, single or two-column |
 | Slide with comparison data (before/after, us/them, old/new) | `evidence` | Two-column layout, split on `---` |
-| Slide with numeric data suitable for charting | `evidence` | Inline chart (`[chart:name]` in content) or full-viewport `type: "chart"` |
+| Slide with 2+ numeric values of the same type, or named items scored across options | `evidence` | **Synthesize a chart** — do not leave this as bullets. Add `charts` dict, embed `[chart:name]` in content, remove raw data from bullet form. Use chart-trigger signals in your slide-recipes skill to select chart type. |
 | Slide after 2+ consecutive bullet-heavy slides | `breathing-room` | Centered, background image, minimal text |
 | Drill-down with detailed specs or numbers | `workhorse` or `evidence` | Depends on whether data is comparative or sequential |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ztffn/presentation-generator-plugin",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "Claude Code plugin for generating graph-based presentations",
   "bin": {
     "presentation-generator-plugin": "bin/index.js"

package/scripts/validate_content_brief.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+validate_content_brief.py — Validates the content brief JSON produced by Phase 2.
+Checks required fields, detects placeholder/weak values, and warns on thin content.
+Exit 0 if brief is usable; exit 1 if critically malformed.
+Usage: python3 validate_content_brief.py <path-to-content-brief.json>
+"""
+
+import sys
+import json
+import re
+from pathlib import Path
+
+VALID_GOALS = {"pitch", "demo", "update", "internal", "exploratory"}
+
+# Sentinel strings the content agent writes when data is absent in source material.
+NOT_FOUND_RE = re.compile(r"NOT FOUND IN SOURCE", re.IGNORECASE)
+
+# Generic/weak phrases that should not appear as values — adapted from content-signals SKILL.md.
+WEAK_VALUE_RE = re.compile(
+    r"\b(significant|various|many|some|multiple|considerable|substantial|good|better|great|saves time|easy to use|improves efficiency)\b",
+    re.IGNORECASE,
+)
+
+# A specific number means the string contains at least one digit sequence.
+HAS_NUMBER_RE = re.compile(r"\d")
+
+
+def is_not_found(value):
+    if isinstance(value, str):
+        return bool(NOT_FOUND_RE.search(value))
+    if isinstance(value, list):
+        return all(isinstance(v, str) and NOT_FOUND_RE.search(v) for v in value) and len(value) > 0
+    return False
+
+
+def check_string(field, value, errors, warnings):
+    """Validate a required top-level string field."""
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{field}: missing or empty")
+        return
+    if is_not_found(value):
+        warnings.append(f"{field}: contains 'NOT FOUND IN SOURCE' placeholder — brief is incomplete")
+
+
+def validate(path):
+    errors = []
+    warnings = []
+
+    try:
+        raw = Path(path).read_text()
+    except FileNotFoundError:
+        print(f"ERROR  File not found: {path}")
+        return False
+
+    try:
+        brief = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(f"ERROR  Invalid JSON: {e}")
+        return False
+
+    if not isinstance(brief, dict):
+        print("ERROR  Content brief must be a JSON object")
+        return False
+
+    # --- product ---
+    product = brief.get("product")
+    if not isinstance(product, dict):
+        errors.append("product: missing or not an object")
+    else:
+        if not str(product.get("name", "")).strip():
+            errors.append("product.name: missing or empty")
+        if not str(product.get("description", "")).strip():
+            errors.append("product.description: missing or empty")
+
+    # --- audience ---
+    audience = brief.get("audience")
+    if not isinstance(audience, dict):
+        errors.append("audience: missing or not an object")
+    else:
+        for sub in ("who", "background", "cares_about"):
+            val = audience.get(sub, "")
+            if not isinstance(val, str) or not val.strip():
+                errors.append(f"audience.{sub}: missing or empty")
+            elif is_not_found(val):
+                warnings.append(f"audience.{sub}: 'NOT FOUND IN SOURCE' placeholder — narrative will lack audience specificity")
+
+    # --- goal ---
+    goal = brief.get("goal", "")
+    if not isinstance(goal, str) or not goal.strip():
+        errors.append("goal: missing or empty — must be one of: pitch, demo, update, internal, exploratory")
+    elif goal not in VALID_GOALS:
+        if is_not_found(goal):
+            warnings.append("goal: 'NOT FOUND IN SOURCE' placeholder — framework selection will be generic")
+        else:
+            errors.append(f"goal: '{goal}' is not a valid value — must be one of: {', '.join(sorted(VALID_GOALS))}")
+
+    # --- keyMessages ---
+    key_messages = brief.get("keyMessages")
+    if not isinstance(key_messages, list) or len(key_messages) == 0:
+        errors.append("keyMessages: missing or empty array — at least one declarative sentence required")
+    else:
+        real = [m for m in key_messages if isinstance(m, str) and not NOT_FOUND_RE.search(m) and m.strip()]
+        if len(real) == 0:
+            errors.append("keyMessages: all entries are placeholders — no real key messages extracted")
+        elif len(real) < 3:
+            warnings.append(f"keyMessages: only {len(real)} non-placeholder entry(ies) — schema requires 3–5 declarative sentences")
+        elif len(real) > 5:
+            warnings.append(f"keyMessages: {len(real)} entries — schema recommends 3–5")
+        for i, msg in enumerate(real):
+            if WEAK_VALUE_RE.search(msg):
+                warnings.append(f"keyMessages[{i}]: weak/generic language detected — '{msg[:80]}...' — make it specific")
+
+    # --- valueProps ---
+    value_props = brief.get("valueProps")
+    if not isinstance(value_props, list) or len(value_props) == 0:
+        warnings.append("valueProps: missing or empty — narrative may lack audience-specific benefit framing")
+    elif is_not_found(value_props):
+        warnings.append("valueProps: all entries are placeholders — will produce generic benefit statements")
+
+    # --- dataPoints ---
+    data_points = brief.get("dataPoints")
+    if not isinstance(data_points, list) or len(data_points) == 0:
+        errors.append("dataPoints: missing or empty — at least one specific metric is required")
+    else:
+        has_specific_number = False
+        for i, dp in enumerate(data_points):
+            if not isinstance(dp, dict):
+                errors.append(f"dataPoints[{i}]: must be an object with label, value, source")
+                continue
+            val = str(dp.get("value", ""))
+            if HAS_NUMBER_RE.search(val) and not NOT_FOUND_RE.search(val):
+                has_specific_number = True
+            else:
+                warnings.append(
+                    f"dataPoints[{i}] ('{dp.get('label', '?')}'): value '{val}' has no specific number — "
+                    f"weak metric (schema requires a concrete figure)"
+                )
+            if not dp.get("source", "").strip():
+                warnings.append(f"dataPoints[{i}] ('{dp.get('label', '?')}'): missing source attribution")
+        if not has_specific_number:
+            errors.append("dataPoints: no entry has a specific numeric value — brief cannot support evidence slides")
+
+    # --- proofPoints ---
+    proof_points = brief.get("proofPoints")
+    if not isinstance(proof_points, list) or len(proof_points) == 0:
+        warnings.append("proofPoints: missing or empty — narrative will lack named evidence")
+    elif is_not_found(proof_points):
+        warnings.append("proofPoints: all entries are placeholders")
+
+    # --- objections ---
+    objections = brief.get("objections")
+    if not isinstance(objections, list) or len(objections) == 0:
+        warnings.append("objections: missing or empty — narrative cannot preempt audience concerns")
+    elif is_not_found(objections):
+        warnings.append("objections: all entries are placeholders")
+
+    # --- callToAction ---
+    cta = brief.get("callToAction", "")
+    check_string("callToAction", cta, errors, warnings)
+    if isinstance(cta, str) and cta.strip() and not is_not_found(cta):
+        # Heuristic: a real CTA contains an action verb and a concrete outcome
+        weak_cta_patterns = re.compile(
+            r"^(let'?s|we should|continue|follow up|stay in touch|keep talking)",
+            re.IGNORECASE,
+        )
+        if weak_cta_patterns.match(cta.strip()):
+            warnings.append(f"callToAction: '{cta}' — too vague; should name a specific action and outcome")
+
+    # --- context ---
+    context = brief.get("context", "")
+    if not isinstance(context, str) or not context.strip():
+        warnings.append("context: missing or empty — narrative agent has no competitive or timing signals")
+    elif is_not_found(context):
+        warnings.append("context: 'NOT FOUND IN SOURCE' placeholder")
+
+    # --- Report ---
+    if warnings:
+        print(f"WARN   {len(warnings)} warning(s):")
+        for w in warnings:
+            print(f"  WARN  {w}")
+        print()
+
+    if errors:
+        for e in errors:
+            print(f"ERROR  {e}")
+        print()
+        print(f"FAILED  {len(errors)} critical error(s) — content brief is not usable; re-run Phase 2")
+        return False
+
+    if not warnings:
+        print("OK  Content brief is valid")
+    else:
+        print(f"OK (with warnings)  Content brief is usable — {len(warnings)} weak field(s) noted above")
+    return True
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python3 validate_content_brief.py <path-to-content-brief.json>")
+        sys.exit(1)
+    ok = validate(sys.argv[1])
+    sys.exit(0 if ok else 1)

package/skills/presentation-generator/SKILL.md

@@ -69,9 +69,15 @@ Write a JSON content brief to _temp/presentation-content-brief.json
 Report back what you extracted.
 ```
 
-When the agent finishes, move to Phase 3.
+When the agent finishes (or after you write the brief yourself), validate the brief before continuing:
 
-If no documents were provided, write _temp/presentation-content-brief.json yourself from the user's prompt, then move to Phase 3.
+```bash
+python3 "{PLUGIN_ROOT}/scripts/validate_content_brief.py" _temp/presentation-content-brief.json
+```
+
+If exit code is non-zero, stop and show the errors to the user — do not proceed to Phase 3.
+
+If no documents were provided, write _temp/presentation-content-brief.json yourself from the user's prompt, then run the validation above.
 
 ---
 

package/skills/slide-content/SKILL.md

@@ -261,4 +261,6 @@ Example annotation in an outline (use `### SPINE N:` header format — the parse
 
 5. **Breathing room after sustained density.** If the outline has a run of `workhorse` and `evidence` slides (detailed argument, data, comparison), follow it with a `breathing-room` or `impact` slide before continuing. The audience needs a reset.
 
+6. **Chart rhythm.** One `evidence` slide per major section is a signal. Two in a row is a pattern the audience can follow. Three or more consecutive `evidence` slides is a data dump — it exhausts attention and flattens the argument. If the content demands multiple data points, prefer one chart slide with a strong claim followed by a drill-down for the supporting data, rather than stacking chart slides on the spine. Equally, a deck with no `evidence` at any point reads as assertion without proof — aim for at least one per major argument.
+
 These annotations describe intent only. How the design agent translates them into layout, background, and typography is not the narrative agent's concern.

package/skills/slide-recipes/SKILL.md

@@ -112,6 +112,23 @@ Set `showBranding: false` for immersive slides (R3F, full-bleed video).
 
 When a signal is present: synthesise the `charts` dict from the outline figures, embed `[chart:name]` in the content markdown, and remove the raw data from bullet form. The agent must extract values from the outline text — do not leave chart-ready data as bullets.
 
+**Data extraction and creation rules:**
+
+The outline rarely contains a tidy data table. More often, values are embedded in prose or bullets. The agent must parse them out and construct the data array. When exact values are missing or incomplete, synthesise plausible values consistent with the narrative — a chart that conveys the right order of magnitude and relative relationship is more useful than no chart.
+
+| Outline text | What to do |
+|---|---|
+| `- Iron oxide: 3,000 kJ/kg` / `- Lithium-ion: 576 kJ/kg` / `- Molten salt: 360 kJ/kg` | Extract label + value pairs → `[{material, energy_density}]`, `xKey: "material"`, `yKeys: ["energy_density"]`, chart type: `bar` |
+| `Response time down 60%, cost down 40% over 6 months` | Construct time-series or before/after → `[{period: "Before", response_ms: 100, cost: 100}, {period: "After", response_ms: 40, cost: 60}]`, chart type: `bar` |
+| `Outperforms competitors on flexibility, integration speed, and reliability` | Named items across multiple axes → `[{axis: "Flexibility", ours: 90, competitor: 35}, ...]`, chart type: `radar` |
+| `Revenue grew 40% QoQ` — no breakdown given | Create a minimal 2-point bar: `[{quarter: "Q2", revenue: 100}, {quarter: "Q3", revenue: 140}]`. Label it clearly. |
+
+Key principles:
+- Use short, readable axis labels — `"Q3"` not `"Third Quarter of Fiscal Year"`
+- `yKeys` values become legend labels — use the words the audience would say: `"ours"` / `"competitor"`, `"before"` / `"after"`, `"target"` / `"actual"`
+- Normalise to a common base (e.g., index to 100) when absolute values would mislead
+- When data is qualitative (e.g. "best-in-class"), skip the chart — use an impact or workhorse slide instead
+
 Chart placement:
 - Data IS the primary message of the slide → `type: "chart"` (full-viewport)
 - Data supports a text argument → `[chart:name]` inline in a `two-column` layout