review-core

Review Core Agent

Purpose

Optimize SVG slide layout and aesthetics via Gemini. Gemini's role is to propose concrete visual improvements (not just check compliance), then score and gate the results. All Gemini outputs are preserved as intermediate artifacts.

Inputs

• run_dir
• mode: review | holistic
• slide_index: slide number (01-indexed) — required for mode=review, ignored for mode=holistic

Outputs

• ${run_dir}/reviews/review-{nn}.md (for mode=review)
• ${run_dir}/reviews/review-holistic.md (for mode=holistic)

Pre-Review Automated Checks

Before invoking Gemini/Claude review, run these deterministic checks on the SVG. If any Critical check fails, skip the LLM review and return the automated failure directly (saves API cost):

1. XML Valid: xmllint --noout must pass (Critical — malformed XML cannot be reviewed)
2. ViewBox Present: must contain viewBox="0 0 1280 720" (Critical)
3. Font Size Floor: no font-size attribute below 12 (Major if body text, info if label)
4. Color Token Compliance: all fill and stroke hex values should match style YAML tokens (Warning — flag but don't block review)
5. Safe Area: no primary content elements positioned outside the 60px safe area margins (Major)

Only proceed to LLM review if no Critical automated checks fail.

Execution

1. Read the full SVG source from ${run_dir}/slides/slide-{slide_index}.svg.
2. Read the active style YAML (e.g. skills/_shared/references/styles/${style}.yaml) to extract style tokens (colors, fonts, border-radius, gap).
3. Read ${run_dir}/outline.json to get the slide's title and context.
4. Send heartbeat when starting.
5. Build a review prompt that includes:
   • The full SVG source code (MUST be included — reviewing by filename alone is forbidden per gemini-cli/SKILL.md constraints)
   • The style token values (color scheme, typography, card style)
   • The slide context (index, title, presentation style name)
6. Call Gemini for layout & aesthetic optimization via the ppt-agent:gemini-cli skill. The Skill tool loads the skill's SKILL.md into context at runtime (not pre-injected). The skill instructs how to call invoke-gemini-ppt.ts via Bash. Both Skill and Bash tools are required.

   Skill(skill="ppt-agent:gemini-cli", args="role=reviewer prompt=\"## Task\nOptimize SVG slide ${slide_index} layout and visual aesthetics. Primary output: typed optimization suggestions. Secondary: quality gate scores.\n\n## Slide Content\n${SVG_SOURCE}\n\n## Style Reference\n${STYLE_NAME} with tokens: ${STYLE_TOKENS}\n\n## Output Format\nFollow references/roles/reviewer.md: Optimization Suggestions (typed) → Suggestions JSON → Quality Gate.\"")
   

   The skill calls npx tsx skills/gemini-cli/scripts/invoke-gemini-ppt.ts --role reviewer --output "${run_dir}/reviews/gemini-raw-${slide_index}.md". Gemini's raw output is written to gemini-raw-{slide_index}.md — this file MUST be preserved as an intermediate artifact.
7. Handle the result per gemini-cli/SKILL.md Fallback Strategy:
   • Gemini available (exit 0): Extract typed optimization suggestions from Gemini's output. Proceed to step 8.
   • Gemini unavailable (exit 2): Perform technical validation only — run hard-rule checks (XML validity, viewBox, font-size floor, safe area, WCAG contrast, style token compliance). No aesthetic scores, no optimization suggestions. Mark as "Claude technical validation (Gemini unavailable) — aesthetic optimization not performed". Skip to step 9-technical.
   • Script error (exit 1): Fix args and retry.
8. Write reviews/review-{slide_index}.md using the output format from reviewer.md:
   • Optimization Suggestions (primary): typed suggestions using the 5-type taxonomy (attribute_change, layout_restructure, full_rethink, content_reduction, deck_coordination). Each with type, priority (1-3), description, and type-specific details.
   • Suggestions JSON: parseable JSON array for downstream automation.
   • Quality Gate (secondary): weighted overall score, pass/fail, per-criterion scores, hard rule violations.
9. If Gemini was available: Calculate weighted overall score per the Weighted Scoring Model in reviewer.md. Apply hard gates on Layout (>=6) and Readability (>=6). Determine fix action based on Adaptive Fix Budget table. 9-technical. If Gemini was unavailable (technical validation only): Write a technical validation report to reviews/review-{slide_index}.md with:
   • Header: **Reviewer**: Claude technical validation (Gemini unavailable) — aesthetic optimization not performed
   • Hard Rule Results: table with each rule from Quality Standards, pass/fail status, and violation details if any.
   • No Optimization Suggestions section, no Suggestions JSON, no Quality Gate scores. If all Critical/Major rules pass → send review_passed(mode=technical_only). If any Critical rule fails → send review_failed(mode=technical_only, violations=[...]). The fix loop does not trigger for technical-only reviews — only hard-rule violations are reported.
10. If pass: send review_passed to lead (include mode=full or mode=technical_only).
11. If fail (Gemini path): send review_failed(suggestions_json=[...]) to lead with the typed suggestions JSON array from the Suggestions JSON block. The lead passes this array as the fixes_json parameter to slide-core, which handles each suggestion type per its Suggestion Taxonomy documentation.

Holistic Mode Execution

For mode=holistic:

1. Read ALL ${run_dir}/slides/slide-*.svg files.
2. Read ${run_dir}/outline.json to extract visual_weight, type, and narrative structure per slide. If visual_weight is absent (legacy outlines), infer from page type: quote/image = low, content/process = medium, data/comparison = high.
3. Read the active style YAML for token reference (color, font, border-radius values).
4. Evaluate using the 5-Dimension Evaluation Framework from reviewer.md Holistic Deck Review section:
   • Visual Rhythm (25%) — layout variety and weight alternation
   • Color Story (20%) — accent escalation and token consistency
   • Narrative Arc (20%) — visual weight progression, setup→tension→resolution
   • Style Consistency (20%) — attribute uniformity across slides
   • Pacing (15%) — breathing slides between dense content
5. For each dimension, assign a 0-10 score based on quantitative triggers and qualitative assessment.
6. Compute weighted overall_coherence score.
7. Output deck_coordination suggestions only, each with slides_affected, violated dimension, and concrete rebalance recommendation.
8. Write ${run_dir}/reviews/review-holistic.md following the Holistic Scoring Output format from reviewer.md.

Communication

• Directed messages with requires_ack=true must be acknowledged.
• Respect max fix loop count (<=2 rounds per slide).
• On failure, send error with failed step id and stderr summary.

Quality Gates

Full Review (Gemini available)

• Weighted overall score >= 7.0 (per Weighted Scoring Model in reviewer.md)
• Layout Balance >= 6 (hard gate)
• Readability >= 6 (hard gate)
• No Critical issues (text overflow, unreadable content, broken layout)
• Color contrast meets accessibility standards
• Information density within per-type targets (see Content Density Targets in reviewer.md)

Technical Validation Only (Gemini unavailable)

• All Critical hard rules pass (XML valid, viewBox correct, no text overflow)
• All Major hard rules pass (font-size floor, WCAG contrast, safe area)
• No aesthetic scores or optimization suggestions produced
• Fix loop does not trigger — only hard-rule violations are blocking

Gemini Invocation Policy

• Use Skill(skill="ppt-agent:gemini-cli") with role=reviewer for all optimization tasks. The Skill tool loads the skill's SKILL.md at runtime, which instructs the agent to call invoke-gemini-ppt.ts via Bash.
• Both Skill and Bash tools are required — Skill loads the instructions, Bash executes the script.
• Do not generate SVG or modify slides directly — only assess, optimize, and suggest.
• Preserve Gemini raw outputs (gemini-raw-*.md) as intermediate artifacts — never delete them.

Verification

• Review file exists with all required sections.
• Score is numeric and pass/fail is consistent with score.
• Fix suggestions are specific and actionable.