PPT Rebuilder Skill

PPT_rebuilder is a Codex skill for rebuilding editable PowerPoint decks from source material.

Current detailed focus:

• PDF-to-editable-PPT reconstruction

Supported interface directions, with detailed rules to be expanded later:

• screenshot/image-to-PPT reconstruction
• HTML-to-PPT reconstruction
• text outline/course framework-to-PPT generation
• existing component spec-to-PPT rendering

The system is not a simple converter. Its job is to decide which parts can be trusted mechanically, which parts need AI/vision reconstruction, how every generated element is grounded to source evidence, and whether the final PPT is both faithful and editable.

For the full product manual, see SYSTEM_OVERVIEW.md. Chinese version: SYSTEM_OVERVIEW_CN.md.

Core Idea

The system separates concerns that are often confused:

source evidence
-> reconstruction decision
-> execution lock
-> grounding
-> rendering
-> validation

In practice:

• source_quality_report.json: what the source contains and how reliable each layer is.
• reconstruction_plan.json: what route each layer will take.
• reconstruction_lock.json: the accepted execution contract for canvas, theme, routes, and validation requirements.
• grounding_map.json: what source evidence supports each planned/rendered element.
• scene_spec.json or component_inventory.json: what the renderer should draw.
• validation artifacts: whether the output is structurally valid, faithful, editable, and plan-compliant.

System Flow

flowchart TD
    A["Input Source"] --> B["Source Intake"]
    B --> C["Preflight Evidence Extraction"]
    C --> D["Source Quality Report"]
    D --> E["Reconstruction Plan"]
    E --> LOCK["Reconstruction Lock"]
    LOCK --> F["Describe Page Structure"]
    F --> G["Ground Elements"]
    G --> H["Component Inventory / Scene Spec"]
    H --> I["Render PPTX"]
    I --> J["Validation Layers"]
    J --> K{"Pass?"}
    K -- "Yes" --> L["Deliver PPTX"]
    K -- "No" --> M["Repair Relevant Artifact"]
    M --> G

Loading

Current PDF Flow

For PDF work, the expected sequence is:

1. Detect canvas and page range.
2. Extract evidence only: preview, text lines, image bounds, drawings, paths, z-order, opacity, clipping, and object counts.
3. Build source_quality_report.json and PDF-specific semantic_quality_report.json.
4. Build reconstruction_plan.json from quality evidence.
5. Write reconstruction_lock.json from the accepted plan.
6. Build text structure and visual/layout descriptions according to the lock.
7. Build grounding_map.json.
8. Build component inventory or scene_spec.json.
9. Render editable PPT.
10. Validate in separate layers.
11. Repair only the relevant artifact and rerun the affected page.

Layer Routes

Every major layer gets its own route. Do not force the whole page down one path.

Common layers:

• text
• background
• images
• vector_shapes
• tables
• diagrams
• icons

Route	Meaning	Typical Use
script_trusted	Source/script data is reliable enough to use as source-of-truth.	Embedded PDF text with stable bboxes.
script_candidate_ai_decision	Script provides candidates; AI decides grouping or final representation.	Split bullets, tables, flow nodes, dense small text.
ai_rebuild_script_measure	AI/vision owns reconstruction; scripts provide measurements and evidence.	Non-separable backgrounds, path soup, visual-only structures.
preserve_as_image	Preserve raster asset with documented reason.	Photos, complex logos, real screenshots, complex artwork.
ai_design_script_measure	Interface for future non-visual design from outlines.	Text outline/course framework generation.

Artifact Map

flowchart TD
    SQ["source_quality_report.json\nEvidence: what is reliable?"]
    SEM["semantic_quality_report.json\nPDF-specific evidence"]
    PLAN["reconstruction_plan.json\nDecision: what route to use?"]
    LOCK["reconstruction_lock.json\nExecution contract"]
    GROUND["grounding_map.json\nEvidence master table"]
    TEXT["text_structure.json/.md\nEditable text groups"]
    COMP["component_inventory.json / component_spec.md\nComponent description"]
    SCENE["scene_spec.json\nRenderer instructions"]
    PPT["page_xxx.pptx / final deck"]
    VAL["render_validation.json + review notes"]

    SQ --> PLAN
    SEM --> PLAN
    PLAN --> LOCK
    LOCK --> TEXT
    LOCK --> COMP
    LOCK --> GROUND
    TEXT --> GROUND
    COMP --> GROUND
    GROUND --> SCENE
    SCENE --> PPT
    PPT --> VAL

Loading

Key boundary:

• source_quality_report.json and semantic_quality_report.json do not decide routes.
• reconstruction_plan.json decides routes.
• reconstruction_lock.json freezes accepted execution values and must be re-read downstream.
• grounding_map.json owns full source evidence.
• scene_spec.json references grounding_id and tells the renderer what to draw.

Repository Layout

• SKILL.md: runtime entry point for the skill.
• SYSTEM_OVERVIEW.md: full system manual.
• SYSTEM_OVERVIEW_CN.md: Chinese system manual.
• agents/openai.yaml: Codex-facing skill metadata.
• references/: detailed workflow, source intake, planning, grounding, schemas, validation, and native-shape rules.
• scripts/: reusable extraction, rendering, summarization, and validation utilities.
• docs/: PRD and high-level diagrams.
• logs/: development logs.

Module Responsibilities

Module / Reference	Purpose	Main Output
source_intake_and_planning.md	Source-type interface and future branches.	Source interface expectations.
semantic_quality_gate.md	PDF-specific quality measurement.	semantic_quality_report.json evidence.
planning_schema.md	Boundary between evidence and route decisions.	reconstruction_plan.json.
reconstruction_lock_schema.md	Execution contract that prevents drift after planning.	reconstruction_lock.json.
grounding_schema.md	Grounding master-table rules.	grounding_map.json.
text_structure_schema.md	Editable text grouping rules.	text_structure.json, text_structure.md.
component_taxonomy.md	Shared vocabulary for text, containers, shapes, assets.	Stable component names.
component_schema.md	Renderer-facing scene schema.	scene_spec.json.
native_shape_library.md	Native PPT shape mapping.	Shape decisions.
validation_layers.md	Validation categories and boundaries.	Validation interpretation.
validation_checklist.md	Return checklist before delivery.	Final quality gate.
rebuild_library.md	Script responsibilities and future library plan.	Script usage guidance.
long_run_loop.md	Long-running page-loop state model.	chapter_run_manifest.json.

Trigger Rules

• Run source intake when a new source file or source type is introduced.
• Run the PDF semantic quality gate when editable PPT reconstruction is requested from a PDF.
• Build reconstruction planning only after source evidence and quality reports exist.
• Write reconstruction_lock.json once the reconstruction plan is accepted.
• Trigger visual text partitioning only when quality/planning evidence says text grouping is unreliable.
• Build grounding before rendering.
• Render only after planning, grounding, and component inventory or scene spec exist.
• Validate after rendering and before delivery.

Preserve-As-Image Policy

Allowed:

• photos
• complex logos
• real screenshots
• complex artwork
• assets explicitly not required to be editable

Not allowed without explicit user approval or documented impossibility:

• editable-required text
• tables or table-like grids
• flowcharts and process diagrams
• regular arrows, connectors, masks, cards, or frames
• simple icons that can reasonably become native shapes

Every preserved image must have a reason in reconstruction_plan.json, a grounding entry in grounding_map.json, and validation of visual placement and editability impact.

Validation Philosophy

Do not use one validation result as proof of the whole reconstruction.

validate_pptx.py checks only package/content smoke signals such as zip integrity, slide count, expected text, and shape hints. It does not prove:

• visual fidelity
• semantic quality
• grounding completeness
• plan compliance
• editability of required content

What Is Not Included

Do not commit proprietary source PDFs, customer decks, extracted brand images, or other copyrighted business materials into this repository unless they are explicitly cleared for publication.

For public examples, use synthetic or fully authorized materials.