Agent Operating Instructions (PowerPoint Iteration Repo)

# Agent Operating Instructions (PowerPoint Iteration Repo)

## Objective
Refine `Premier_Evolution_Chunk1_Updated.pptx` into a brand-compliant, polished deck by applying deterministic edits driven by `CHANGE_REQUESTS.md`. Always produce a NEW output PPTX per run.

## Source-of-truth files
- **Do not modify in-place:** `Premier_Evolution_Chunk1_Updated.pptx`
- **Authoritative requirements:** `CHANGE_REQUESTS.md`
- **Brand references (read-only):** `brand/` (template decks + PDF style guide)
- **Edit plan:** `edits/edits.yaml`
- **Generated outputs:** `out/` and `build/`

## Non-negotiable rules
1) NEVER overwrite `Premier_Evolution_Chunk1_Updated.pptx`.
2) Do not edit anything under `brand/`.
3) Prefer small, deterministic edits (text/geometry/alignment). Avoid broad redesign unless explicitly requested in `CHANGE_REQUESTS.md`.
4) If an element can’t be safely edited (SmartArt/charts/groups), WARN and:
   - leave as-is, OR
   - use an explicit fallback only if `CHANGE_REQUESTS.md` allows it.

## Required iteration loop (per run)
Prefer the built-in runner:
```bash
python scripts/run_iteration.py \
  --input "Premier_Evolution_Chunk1_Updated.pptx" \
  --edits "edits/edits.yaml" \
  --change_requests "CHANGE_REQUESTS.md"
```

This run should:
1) Apply edits to a new deck and update `out/deck_latest.pptx`.
2) Write a timestamped deck: `out/deck_YYYYMMDD_HHMM.pptx`.
3) Render PNGs to `out/png/<run_id>/` (if renderer available).
4) Print a status report mapping checklist items to DONE | PARTIAL | BLOCKED.

## Checklist/status mapping
- Checklist items are generated in `build/change_request_checklist.json`.
- To mark an item DONE, include `change_id` (or `change_ids`) on the corresponding operation(s) in `edits/edits.yaml`.
- If a slide has edits but no matching `change_id`, it will show as PARTIAL.

## Optional (only when helpful)
### AI visual critique (suggest-only)
If `OPENAI_API_KEY` is available AND PNGs exist:
```bash
python scripts/qa_critic.py \
  --png_dir out/png/latest \
  --style_guide "brand/Premier-SlideStyleGuide-Feb25.pdf" \
  --shape_index "build/shape_index.json" \
  --output "build/qa_suggestions.yaml"
```
- Treat output as suggestions only. Do NOT auto-merge into `edits/edits.yaml`.
- Propose a small set of high-confidence edits before applying.

## Guardrails for edits.yaml
- Prefer targeting shapes by stable `shape.name`. If names are generic, add `rename_shape` ops first.
- Keep edits ordered and grouped by slide.
- Avoid fragile geometry changes unless necessary; prefer align/distribute.

## Definition of “complete”
- Every item in `CHANGE_REQUESTS.md` is DONE or explicitly BLOCKED with a recommended manual step.
- Latest output exists: `out/deck_latest.pptx`.
- Latest renders exist if supported: `out/png/latest/`.