Visual Asset Workflow

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.