slide-qa · diff
git:20260916.1aaf719 to git:20260916.2f4b343
5 added, 6 removed. Audit A to A.
---
name: slide-qa
description: >-
- Visual QA of a generated deck from thumbnails: fetch every page as PNG, inspect
- against a defect checklist (overflow, overlaps, wrong connectors, weak
- contrast), drive the fix-and-regenerate loop, and clean up the local QA files.
- The generation skills invoke it when the user opts in (the default); it also
- runs standalone on any deck URL.
+ Visual QA of a generated deck from thumbnails: inspect every page against a
+ defect checklist (overflow, overlaps, wrong connectors, weak contrast) and
+ drive the fix-and-regenerate loop. The generation skills invoke it when the
+ user opts in (the default); it also runs standalone on any deck URL.
Use for: スライドを検証して, デッキを QA して, サムネイルで確認して, visual QA.
Not: pre-generation offline checks (--dry-run / validate_layout.py stay in the
generation skills); content fact-checking; PPTX files (pptx-export).
---
*[日本語](SKILL.ja.md)*
# 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
| Task | Command |
|------|---------|
| Fetch thumbnails | `.venv/bin/python scripts/fetch_thumbnails.py <URL or ID> --out out/qa --size LARGE` |
| Restrict pages (split QA) | `--pages 3,8,12,20` / `--pages 9-16` |
| Delete local QA files (always, at the end) | `.venv/bin/python scripts/cleanup_qa.py` (`--dry-run` to preview) |
- | Full checklist, fix loop, reporting rules | `references/validation.md` (Gate 2) |
+ | The fix for a defect the checklist flagged, plus reporting rules | `references/validation.md` (Gate 2) — the checklist below is self-contained, so open this only when a specific defect needs its fix |
| Splitting QA when images crowd context | `references/parallel-generation.md` §6 |
| Delete a superseded deck from Drive | `drive.files().delete(fileId=…)` (or move to trash) |
---
## Phase 1: Fetch thumbnails
```bash
.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:
```bash
.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.