visual-asset-workflow

# Visual Asset Workflow Skill

## Context & Problem

Educational visual generation converges toward generic infographics with technical specifications ("44pt Roboto Bold, 250px box") that activate prediction mode instead of reasoning mode. This produces bland, PowerPoint-default aesthetics instead of distinctive, pedagogically effective visuals.

This skill provides professional creative brief methodology to activate Gemini 3's reasoning capabilities.

---

## Core Principles

1. **Story activates reasoning** - Narrative intent produces distinctive visuals; technical specs produce generic ones
2. **Proficiency dictates complexity** - A2 students need <5 sec grasp; C2 professionals handle dense information
3. **Prerequisites gate content** - Visuals cannot assume knowledge students don't have yet
4. **Pedagogy drives hierarchy** - Visual weight teaches importance, not arbitrary aesthetics

---

## Dimensional Guidance

### Planning Before Execution

**Avoid:** Jumping into visual analysis without context
**Prefer:** Strategic planning phase (Q0)

Read FIRST:
- `apps/learn-app/docs/chapter-index.md` → Extract part, proficiency (A2/B1/C2), prerequisites
- `apps/learn-app/docs/[part]/[chapter]/README.md` → Understand lesson structure

Detect conflicts BEFORE work:
- Proficiency-complexity mismatch (complex visual for A2 beginners)
- Prerequisite violations (Python code when students haven't learned it)
- Pedagogical layer incoherence (Layer 1 content using Layer 4 approaches)

Output strategic plan, WAIT for approval before proceeding.

**Principle:** Plan prevents wasted work (Chapter 9 failure: 5 wrong lessons from skipping planning)

---

### Prompt Structure: Professional Creative Briefs

**Avoid:** Technical specifications
```
❌ "Title: 44pt Roboto Bold at (50, 20)"
❌ "Box: 250px × 90px, #aaaaaa, 8px corners"
❌ "Shadow: 4px offset, 8px blur"
```

**Prefer:** Story + Intent + Metaphor
```
✅ The Story: [1-2 sentence narrative of what's visualized]
✅ Emotional Intent: Should feel [exponential growth, surprising magnitude]
✅ Visual Metaphor: [Multiplication cascade - like compound interest]
✅ Key Insight: [ONE thing students must grasp]
✅ Color Semantics: Blue (#2563eb) = Authority (teaches governance concept)
✅ Typography Hierarchy: Largest = Key insight (not arbitrary sizing)
✅ Pedagogical Reasoning: Why these choices serve teaching
```

**Principle:** Creative briefs activate reasoning mode; specifications activate prediction mode

**Why it matters:** Gemini 3 reasons about HOW to achieve intent → Distinctive visuals instead of generic

---

### Token Conservation Strategy

**When:** Batch mode with >8 visuals OR continuation session

**Apply condensation while preserving reasoning activation:**

**ALWAYS KEEP:**
- Story (1-2 sentence narrative)
- Emotional Intent (what it should FEEL like)
- Visual Metaphor (universal concept)
- Key Insight (ONE thing students must grasp)
- Color semantics with hex codes (#2563eb)
- Pedagogical reasoning (why these choices)

**CONDENSE:**
- Long examples → Short labels
- Verbose descriptions → Bullet points
- Repeated patterns → Compact notation

**NEVER REMOVE:**
- Narrative elements
- Intent statements
- Reasoning explanations

**Example:**
```
FULL: "Top Layer shows the Coordinator at center top with label..."
CONDENSED: "Top Layer - Coordinator: Center top: 'Orchestrator'..."
```

**Target:** 60-70% token reduction, 100% reasoning activation preserved

**Principle:** Efficiency through compression, not through elimination of reasoning triggers

---

### Proficiency-Complexity Alignment

**Avoid:** One-size-fits-all complexity

**Prefer:** Proficiency-gated constraints

**A2 Beginner** (Non-negotiable limits):
- Max 5-7 elements
- <5 second grasp
- Static only (no interactive)
- Max 2×2 grids
- Clear hierarchy (largest = most important)

**B1 Intermediate**:
- Max 7-10 elements
- <10 second grasp
- Interactive Tier 1 OK (tap-to-reveal)
- Max 3×3 grids

**C2 Professional**:
- No artificial limits
- Dense infographics OK
- Full interactive architecture
- Production complexity

**Principle:** Overwhelming A2 students = learning failure; artificial simplicity for C2 = patronizing

---

### Prerequisite Validation Gate

**Avoid:** Assuming knowledge students don't have

**Prefer:** Validate against chapter prerequisites

**Detection:**
- Check Part number: Part 1-2 = no programming, Part 3 = markdown/prompts, Part 4+ = Python
- Check prerequisite list from chapter-index.md

**Example Violations:**
- ❌ Python code in Chapter 9 (Part 3 - students haven't learned it)
- ❌ Git commands in Part 2 (students haven't learned CLI)

**Exception:** Meta-level teaching OK
- ✅ Teaching "markdown code block syntax" by showing Python code block (teaches markdown, not Python)

**Principle:** Visual cannot require unknown knowledge

---

### Constitutional Alignment

**Avoid:** Decorative visuals without pedagogical purpose

**Prefer:** Every visual serves specific learning objective

**Principle 3 (Factual Accuracy):**
- Verify all statistics, dates, technical specs
- Enable Google Search grounding for factual claims
- Cite sources for data

**Principle 7 (Minimal Content):**
- Reject "let's add a visual for variety"
- Every element must teach something
- Remove non-teaching decoration

**Principle:** Visual decisions align with project constitution

---

### Pedagogical Layer Coherence

**Avoid:** Layer mismatch

**Prefer:** Visual approach matches chapter's pedagogical layer

**L1 (Manual Foundation):**
- Step-by-step diagrams
- Concrete examples
- Clear labeling (building vocabulary)

**L2 (AI Collaboration):**
- Before/after comparisons
- Iteration flows
- Three Roles Framework INVISIBLE (no role labels)

**L3 (Intelligence Design):**
- Architecture diagrams
- Reusable pattern illustrations

**L4 (Spec-Driven):**
- Specification → implementation flow
- Component composition diagrams

**Principle:** Visual design reinforces pedagogical approach

---

### Duplicate Prevention Protocol

**Avoid:** Generating different prompts that produce the same visual

**Prevent BEFORE generation:**

1. **Review existing visuals in chapter:**
   - List all `*.png` files in target chapter directory
   - Read corresponding `*.prompt.md` files
   - Identify visual patterns already used

2. **Validate prompt distinctiveness:**
   - Does this prompt's intent differ clearly from existing prompts?
   - Example conflicts to detect:
     - ❌ Timeline + Graph → Both might render as timeline
     - ❌ Architecture + Workflow → Both might render as hierarchy
     - ❌ Same metaphor, different names → Same visual result

3. **Differentiation strategy:**
   - Make visual type explicit in story ("GRAPH showing exponential growth" not just "showing growth")
   - Use distinct metaphors (cascade vs tree vs timeline vs curve)
   - Specify unique structural elements (2D axes vs linear flow vs hierarchical pyramid)

**Detect AFTER generation (in image-generator):**
- Visual comparison with existing chapter images
- Prompt alignment check (does output match brief intent?)

**Principle:** Prevention cheaper than rework

---

## Anti-Patterns

**Never:**
- Generate visuals without reading chapter-index.md first (skipping context)
- Use pixel specifications, font sizes, coordinates in prompts (kills reasoning)
- Assume knowledge not in prerequisites (prerequisite violation)
- Create decorative visuals without learning objective (Principle 7 violation)
- Apply same complexity to A2 and C2 students (proficiency mismatch)
- Create prompts without checking for duplicate visual patterns (causes rework)

**Even if it seems reasonable:**
- Don't use Python examples in Part 3 (students don't know Python yet)
- Don't create complex multi-step visuals for A2 (cognitive overload)
- Don't specify "44pt Roboto Bold" (removes Gemini's judgment)
- Don't skip distinctiveness validation "because they have different filenames" (names differ, visuals might not)

---

## Creative Variance

You tend to default to comparison diagrams even with story-driven prompts. Vary visual types:

- **Timeline progressions** (evolution over time)
- **Multiplication cascades** (compound growth visualization)
- **Hierarchical authority flows** (governance models)
- **Transformation sequences** (before → after → impact)
- **Conceptual metaphors** (abstract → concrete mapping)

Match visual type to story, not habit.

---

## Post-Generation Reflection

After batch completion, analyze systematically (Q8):

**Success patterns:**
- Quality gate performance (which caught most issues?)
- Average iterations (efficiency indicator)
- Time vs estimate (planning accuracy)

**Failure analysis:**
- Deferred visuals root causes (layout? spelling? concept mismatch?)
- Guardrail gaps (what principle would have prevented this?)
- Planning effectiveness (conflicts caught early vs missed?)

**Continuous improvement:**
- Pattern-based updates (not one-off fixes)
- New guardrails from learnings
- Prompt template refinements

Document in: `history/visual-assets/reflections/chapter-{NN}-reflection.md`

**Principle:** Systematic reflection → Improved future performance

---

## Success Indicators

You'll know this skill is working when:

- ✅ Zero pixel specifications in prompts (creative briefs only)
- ✅ Strategic plan created before visual analysis (Q0 complete)
- ✅ Proficiency conflicts detected early (A2 limits enforced)
- ✅ Prerequisite violations prevented (no unknown concepts)
- ✅ Story/Intent/Metaphor in every prompt (reasoning activated)
- ✅ Token conservation applied in batch mode (60-70% reduction)
- ✅ Duplicate prevention validation passed (zero duplicate visuals)
- ✅ Visuals feel distinctive and compelling (not generic PowerPoint)
- ✅ Reflection document created after batch (systematic learning)

**Result:** Professional-quality visuals that teach effectively, generated efficiently through planning, with zero duplicates requiring rework.