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

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):

Requires judgment (report to user):

Informational (skip):

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):

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.