ppt-design-skill

# PPT Design Skill

This skill is a presentation design director and delivery workflow. The
`pptx-designer` Python package is the rendering engine; this skill decides
what should be designed, how it should be structured, how it should look, and
whether the rendered result actually satisfies the user's need.

The design framework below keeps the mature design judgment, content rules,
domain paradigms, and quality standards that make the workflow reliable. The
implementation engine is the public `pptx-designer` Python library.

## Designer mindset

Act as a senior presentation designer. Make decisions from the audience and
the communication goal, not from the list of available Python functions.

- **Audience first**: decide what the audience must understand, remember, feel,
  or do before choosing a layout.
- **Restraint over decoration**: one clear accent system is better than random
  effects; every element must earn its place.
- **Systematic thinking**: a deck is one visual system, not independent pages.
  Lock margins, spacing rhythm, typography, color roles, corner treatment,
  image treatment, and component language.
- **Intentional variation**: vary page architecture and density when the story
  changes, not merely to make pages look different.
- **Explain decisions**: be able to state why a page uses a figure, chart,
  comparison, diagram, image, or sparse statement for this audience.

## Stop before writing code

For a new delivery-grade presentation task, initialize the task from
`templates/task-init/` and keep task-specific requirements in those task
files. Run `init_presentation_task.py` from the loaded Skill's `scripts/`
directory (use its absolute path if the working directory is the project):
`python <skill-root>/scripts/init_presentation_task.py --project <project-root>
--name <lowercase-task-slug>`. It creates an isolated
`<project-root>/ppt_tasks/<task-slug>/` and refuses to overwrite it. Do not
begin implementation while a required research or direction decision remains
unresolved.

For a delivery-grade deck, do not write the build script until these decisions
are explicit:

- topic, audience, scenario, language, and desired action;
- domain paradigm;
- page count and page-by-page goals;
- visual direction and design tokens;
- when supplied, reference qualities stated as observable features, their
  intended transfer, and the final PNG evidence that will demonstrate them;
- variance, motion, and density levels;
- generation mode: FreeStyle `generate_ppt()`, Build Mode, or VI Build Mode;
- image and template constraints;
- the user's confirmation of the structure and visual direction.

The only acceptable shortcut is an explicitly requested quick exploratory draft.

## Non-negotiable outcome

A PPTX file that merely runs successfully is not complete. A task is complete
only after the deck has been rendered through the confirmed `PPTX -> PDF ->
PNG` path, the LLM has inspected the PNG output, material visual issues have
been revised, and the user has confirmed the final direction or result.

## Workflow

1. Confirm the brief and write a **brief acceptance contract**: audience,
   scenario, language, purpose, duration, page count, source material,
   brand/template constraints, image needs, editability requirements, and the
   visual conditions that must be true in the final PNGs. Classify each
   condition as `MUST`, `SHOULD`, or `NICE_TO_HAVE`.
2. Establish the **visual quality target before content planning**: write the
   visual thesis, expected finish level, page anchors, occupied zones, and the
   intended purpose of major whitespace. When reference material is supplied,
   convert its observable qualities into transfer decisions and PNG evidence;
   do not reduce it to vague style labels or mechanically copy its content.
   Run a thumbnail preflight; a page without a focal point or a complete visual
   composition is not ready for content or code.
3. Detect the domain and set the design read: page goal, core takeaway, content type, and
   relationship to surrounding pages. The domain must refine the visual target,
   not reduce it to a generic template.
4. Coach the user through the visual direction: infer the design read, present
   two or three genuinely different directions when needed, explain the
   tradeoffs in plain language, and recommend one.
5. Lock the selected direction in a versioned **Theme Lock**: mood, visual
   thesis, palette intent, typography intent, grid, spacing, density, image
   treatment, chart language, page archetypes, and forbidden patterns. A Theme
   Lock is a project design record, not a `pptx-designer` API object. Resolve
   it once with `ThemeComposer.compose(...)`, save the resulting complete
   **resolved theme**, and pass that object to the generation API.
6. Present the structure and visual direction for confirmation before building
   a delivery-grade deck, unless the user explicitly requests a one-shot draft.
7. Generate a reproducible Python build script or structured `content` using documented public
   `pptx_designer` APIs. Record the Theme Lock version, resolved-theme source,
   seed, package version, and module path with the generation result.
8. Run the generation path and perform basic structural checks.
9. Export the PPTX to PDF and PNG using `skill/scripts/render_pptx.ps1`.
10. Inspect the rendered PNGs directly using two gates. **Gate 1 is visual
   effect first**: ask whether the result looks client-ready at a glance, with a
   clear visual thesis, focal point, composition, density, rhythm, and purposeful
   whitespace. A technically correct but visually ordinary or under-composed
   page is `NEEDS_REVISION`. **Gate 2 preserves the serious-defect review**:
   check overflow, overlap, clipping, unreadable text, missing requirements,
   unsupported claims, broken citations, editability, and other delivery risks.
11. Check every page against the brief
   acceptance contract; use a contact sheet only as an overview, neve