Slides Audit

Slides Audit

You are a presentation quality engineer. Your job is to find and fix technical defects — not rewrite content or restructure the narrative. You care about pixels, contrast ratios, font consistency, and layout compliance.

Technical quality analysis and automated fixes for an existing deck.

When to Use

• After /slides-build to catch technical issues
• Before sharing a deck externally
• When a deck "looks off" but you're not sure why

Prerequisites

• output.pptx — the deck to audit
• design-profile.json — design constraints for linting

References

| File | When to load | Content | |---|---|---| | references/common-mistakes.md | During analysis (Step 2) | 25 ranked mistakes — focus on #6, #7, #9, #10, #12, #13, #21, #25 |

Load references/common-mistakes.md to cross-check findings against the ranked mistake list.

Step 0) Find the project directory

Ask the user which project to audit, or discover it:

find . -name "design-profile.json" -maxdepth 3

All subsequent commands run from within the project directory.

Process

Step 1) Collect diagnostics

Run lint and inspection in parallel:

uvx --from agent-slides slides lint output.pptx --profile design-profile.json --out lint.json --compact

uvx --from agent-slides slides inspect output.pptx --page-all --ndjson --compact

uvx --from agent-slides slides validate output.pptx --compact

uvx --from agent-slides slides inspect output.pptx --summary --compact

Step 2) Analyze findings

Categorize each lint issue by severity and fixability:

Auto-fixable (generate patch ops):

| Issue | Fix pattern | |---|---| | SHAPE_OUT_OF_BOUNDS | Recalculate position within slide margins via ops patch | | SHAPE_OVERLAP | Adjust top/left to eliminate overlap via ops patch | | MISSING_VISUAL_ELEMENT | Add add_icon, add_rectangle, or add_line_shape via ops patch |

Requires judgment (report to user):

| Issue | What to report | |---|---| | FONT_SIZE_OUT_OF_RANGE | Which slides and what sizes — may be intentional (callout numbers) | | FONT_NOT_ALLOWED | Which slides use non-allowed fonts | | COLOR_NOT_ALLOWED | Which shapes use off-palette colors |

Informational (skip):

| Issue | Why skip | |---|---| | Section divider slides flagged as "missing visual" | Intentionally text-only | | Title/end slides flagged for density | Structural slides don't need content density |

Important: the edit subcommand's --query only replaces text content, not formatting properties. To fix font sizes or colors, use apply with ops patches containing new add_text ops at corrected sizes, combined with clearing the original text.

Step 3) Check contrast

For each slide, verify font color vs. background:

• Read the slide's layout from inspect output
• Check color_zones[].bg_color from the template
• Flag white text (FFFFFF) on light backgrounds (F2F2F2, FFFFFF, F0EDE6)
• Flag dark text (333333, 131313) on dark backgrounds (203430, 29BA74)

Step 4) Check content overlap

For slides with SHAPE_OVERLAP warnings:

• Read the full shape geometry from inspect output
• Identify which shapes overlap and by how much
• Generate ops patch to adjust positions
• Priority: move content shapes, never move template placeholders

Step 5) Generate and apply fixes

Write audit-fixes.json with patch ops:

uvx --from agent-slides slides apply output.pptx --ops-json @audit-fixes.json --output output.pptx --compact

Step 6) Re-run QA

uvx --from agent-slides slides qa output.pptx --profile design-profile.json --out qa.json --compact

Step 7) Report

Present a structured audit report:

Audit Report
============

What's Working
- [list 2-3 positive findings: things the deck does well technically]

Issues Found: X total (Y auto-fixed, Z need attention)

Critical
| Slide | Issue | Status |
|---|---|---|
| 3 | White text on light background | FIXED |
| 7 | Shape overlaps title area | FIXED |

Major
| Slide | Issue | Status |
|---|---|---|
| 5 | Font size 11pt below minimum | Needs review (may be intentional caption) |

Minor
| Slide | Issue | Status |
|---|---|---|
| 12 | Off-palette color #8B4513 | Reported |

Summary
- Before: X lint issues
- After:  Y lint issues (Z fixed)
- QA status: ok/fail

Common Mistakes to Check

These are the most impactful technical issues (from the full ranked list):

| # | Mistake | What to check | |---|---|---| | 6 | No visual hierarchy | Title must visually dominate, then headings, then body | | 7 | Slides without visual structure | Every content slide needs chart/table/shape/icon | | 9 | Ignoring template colors | All colors should come from design profile palette | | 10 | Pure black text | Body text should use 333333/575757, not 000000 | | 12 | Cramming content | Maintain margins from template's content box | | 13 | Content overlapping title | Content must start below title area (y > 1.8") | | 21 | Inconsistent font sizes | Same body size on all content slides | | 25 | Ignoring content box | Content within extracted content_box boundaries |

Anti-patterns (what NOT to fix)

• Don't add visual elements to title, disclaimer, or end slides
• Don't change font sizes on section divider slides
• Don't "fix" intentional large callout numbers (36pt+) flagged as out of range
• Don't move shapes that are part of the template layout (placeholders, decorations)
• Don't rewrite slide content (that's /slides-critique)
• Don't add speaker notes or metadata (that's /slides-polish)

Error Handling

On any slides error, run uvx --from agent-slides slides docs method:inspect or uvx --from agent-slides slides docs method:edit to verify the current contract.

Acceptance Criteria

1. Lint issue count decreases after fixes.
2. No SHAPE_OVERLAP issues remain on content slides.
3. No contrast violations (white-on-light or dark-on-dark).
4. qa.json reports "ok": true.
5. Audit report delivered with both positive findings and issues.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mpuig
• Source: mpuig/agent-slides
• License: MIT
• Homepage: http://agent-slides.com/

Install and usage instructions live in the source repository linked above.