日本語

Visual QA for Generated Slides (thumbnail-based)

Follow the QA scope in references/workflow-contract.md. The first pass is a complete visual inspection; repair passes are impact-scoped.

Important

• Scope: post-generation visual verification only. The offline coordinate gate (Gate 1: build_deck.py --dry-run / validate_layout.py) belongs to the generation skills and runs before generation; this skill is Gate 2 (references/validation.md has the full two-gate rationale).
• Run every command from the slide-forge root as cwd — ${CLAUDE_PLUGIN_ROOT} when running from an installed plugin, /path/to/slide-forge on a local clone. Auth and the venv are shared at the repo root (config/, .venv).
• Whether to run QA is settled at generation time. The generation skills ask during intake (default: run — recommend it; a clean API response cannot show overflowing text or a misattached arrow). When the user skipped QA, the generation skill says so in its report and offers this skill as a follow-up.
• Fixes happen in the source, not the artifact. On any defect, fix the spec / deck module in the originating skill's flow and regenerate. Never patch a generated deck in place.
• Always clean up when done. The thumbnails exist only for this verification and are re-fetchable at any time. Delete them with scripts/cleanup_qa.py before reporting — even when QA is aborted midway. Superseded decks created during the fix loop are deleted from Drive too.

Quick Reference

Phase 1: Fetch thumbnails

.venv/bin/python scripts/fetch_thumbnails.py "<deck URL>" --out out/qa --size LARGE

• Judge with --size LARGE. SMALL is only for the squint test.
• Delegate the first pass by default. Split it into 6–8-slide ranges and give each range to a sub-agent that opens the PNGs itself and returns only its findings as text. At --size LARGE one page costs ~1,850 image tokens, so opening an 18-slide deck in the main context pulls in ~33k tokens — and a master, theme, or footer fix mandates a full re-inspection (Phase 3) at the same price. The findings text costs a few hundred bytes.
• Inspect in the main context only when the host or session does not permit sub-agents, or when the deck fits in a single range (roughly ≤8 pages). For the sequential Codex fallback see references/parallel-generation.md §6.
• When several decks are QA'd in one session, keep them apart with --out out/<deck>/qa — cleanup_qa.py sweeps both conventions.

Phase 2: Inspect

Open the PNGs with the Read tool — inside the delegated range agent by default, in the main context only for the cases named in Phase 1. Every page is inspected on the first QA pass; sampling is not a substitute. Within a range, prioritize the viewing order:

1. The page with the most elements (overlaps show up there first)
2. The page with the most complex figure (swimlanes, branching flows, multi-panel)
3. Pages with tables (rows grow and overflow downward)
4. The first page of each section (how the structure reads)
5. Cover, section dividers, closing (master decorations vs. your own drawing)

Minimum checklist (the full table with fixes is in references/validation.md):

• No text overflows or is truncated in any placeholder or box
• No text overlaps the template's decorations (bands, shapes, logos)
• Page numbers appear, not clipped even at 2 digits
• Logos and footers are not drawn twice
• The intended layouts were used (no Proposal/Presentation family mix-up)
• No single trailing character wraps to its own line ("〜へ", "〜出")
• Arrows do not cross unrelated shapes and each attaches to the semantically correct shape — coordinate audits cannot judge meaning
• Labels do not overlap arrows or rules; body-text contrast ≥ 4.5:1
• Labels next to markers (●, ◆, bar ends) have visible breathing room — cramped vertical spacing is invisible to the coordinate audits
• Table column alignment matches the content: short uniform values (年, 年月, ID) centered, numbers right, sentences left
• Squint test: the first thing that draws the eye is the page's main message; otherwise the emphasis (fill, bold, color) is wrong

Phase 3: The fix loop

identify defects → fix the spec / deck module (originating skill)
  → offline check (free) → regenerate → re-fetch only the affected pages → confirm

• For decks generated as new presentations, regeneration creates a new presentation and URL. Delete the superseded version from Drive first — the user holds exactly one URL, the latest.
• Exception — in-place (--into) decks. For a page-local fix, use --into <deck> --update-slides <pages> and fetch the changed pages plus their neighbors. Decks whose contract is a stable URL — the scalar-account-plan activity plan, the two scalar-account-planning-session decks, and Spreadsheets updated via the spreadsheets skill — are fixed by regenerating into the same deck (bare build_deck.py --into only for an approved full rebuild), after scripts/snapshot_version.py records the pre-edit revision. Never delete a deck whose URL has been shared — the URL is the deliverable, and deleting it breaks every link the user has handed out.
• Never patch the artifact; fix the source and rebuild (faster, reproducible).
• After a local page fix, re-fetch that page and its adjacent pages. After a shared layout/component fix, re-fetch every page using it. Re-fetch the entire deck after a master, theme, footer, or page-number change.
• Delete intermediate decks created during verification from Drive as well (this too applies only to new-presentation decks, never to --into targets).

Phase 4: Clean up and report

This phase is not optional. Before presenting results:

.venv/bin/python scripts/cleanup_qa.py            # removes out/qa, out/qa-*, out/*/qa
.venv/bin/python scripts/cleanup_qa.py --dry-run  # preview first if unsure

The script only touches directories under out/ (all gitignored, all re-fetchable), so it is safe to run unconditionally. Pass explicit paths for a non-standard --out location.

Then report, following references/validation.md:

• For anything fixed: what was wrong and how it was fixed ("fixed" alone cannot be verified). For anything not fixed: say so explicitly.
• State that QA passed, which pages were inspected (all, or the ranges), and that local QA files were cleaned up.
• Hand back to the generation skill's post-generation confirmation (references/interactive-intake.md §4) when invoked from one.