deck-pipeline

---
name: deck-pipeline
description: |
  Production-grade Claude Code system that takes presentation decks from raw
  Chinese draft to McKinsey-polished English — with full audit trail, layout
  integrity checks, and a swappable PROFILE block for project-specific
  defaults. Built on a 4-stage pipeline (Sense Pass → McKinsey Translation →
  Layout Audit → Handoff). Also runs polish-only on any single-language deck.

  TRIGGER when the user:
    • hands over a .pptx containing Chinese and asks for English / translation
    • asks for "deck pipeline", "deck polish", "deck globalizer"
    • asks for layout polish, font cleanup, overflow fixing on any deck
    • asks to update / reverse-sync a bilingual comparison Excel against a deck

  SUPPRESS with "Ignore deck-pipeline".
version: 0.1.0
license: MIT
---

# Deck Pipeline

> **A 4-stage, audit-trailed Chinese→English deck globalization system with a swappable project profile.**

This skill bundles the generic deck-globalization engine (originally upstream
DeckGlobalizer v2.1.1) and an editable PROFILE block (palette, fonts,
glossary, style preferences). The two are **separated** by section so the
profile can be swapped per project / brand without touching the engine.

For a marketing-style overview, see `README.md` in this directory.
For implementation, see `scripts/` and the per-stage runbooks below.

---

## 0. Modes & activation

| Mode | Trigger | Stages |
|---|---|---|
| **Full pipeline** | CN deck (± EN draft) + user wants English output | 1 → 2 → 3 → 4 |
| **Polish-only**   | Single-language deck + "layout / format only / skip translation" | 1 → 3 → 4 |
| **Reverse-sync only** | User hand-edited a PPT after a comparison Excel was generated | 3.5 (sync sub-routine) |

Detect the mode in the first turn. If ambiguous, ask one yes/no question
("This deck is already in EN — should I just polish layout, or also rewrite
McKinsey-style?"). Do not guess silently.

---

## 1. PROFILE block — defaults (swappable)

Edit this block to retarget the skill for your project / brand. Everything
below this block is **profile-agnostic**.

```yaml
PROFILE:
  # ---- L1 Tokens ----
  palette:
    # Replace with your brand colors.
    ink:          "#1A1A1A"
    primary:      "#000000"   # accent / brand primary
    soft:         "#FFFFFF"   # soft fill behind banners
    page_bg:      "#FFFFFF"
  fonts:
    # Choose a serif title face + a sans-serif body face for best contrast.
    title:        "Georgia"
    body:         "Verdana"
    title_bold:   true
  unit_table:
    # Chinese number magnitudes → English. 亿 is 100M, NOT "billion".
    "百万":       "M"
    "千万":       "10M"
    "亿":         "100M"
    "十亿":       "1B"
    "百亿":       "10B"
    "千亿":       "100B"
    "万亿":       "1T"
    # Currency suffix is left to the user — append "$" / "RMB" / "€" as appropriate.

  # ---- L2 Constants ----
  size_ladder:           [22, 14, 10, 8, 6, 4]   # H1, H2, body, caption, footnote, source
  floors:
    body:     7
    caption:  6
    source:   4
  compression_step:      0.1     # discrete -0.1pt iterations only
  line_height_default:   1.25
  line_height_fallback:  1.15    # used before sub-floor compression
  quote_style:           "single"  # 'McKinsey' single quotes
  footer_format:         "Confidential · For Intended Recipients Only · {month} {year}"
  separator_in_footer:   "·"     # middle dot, NOT em-dash

  # ---- L1 Glossary (extensible) ----
  # Replace the example entries below with your project's locked terms.
  # Categories are illustrative; you can rename / add / remove.
  glossary:
    locked:
      people_orgs:
        # "<source term>": "<canonical translation>"
        # e.g. "John Smith": "John Smith"
        # e.g. "Acme Capital": "Acme Capital"
        {}
      business_terms:
        # Common Chinese business-deck idioms with industry-standard
        # English mappings. Edit / extend as needed.
        "流水":     "gross revenue"
        "私域":     "owned audience"
        "出海":     "global expansion"
      domain_specific:
        # Project / industry / domain terms.
        # "<source term>": "<canonical translation>"
        {}
    rejected_rewrites:
      # Entries the user vetoed during prior sessions.
      # Format: { source: "...", proposed: "...", reason: "..." }
      []
    pending: []
    session_added: []

  # ---- Style rules ----
  # McKinsey is the default baseline. Additional style references can be
  # uploaded and distilled via scripts/style_distill.py; their rules layer
  # ON TOP of the McKinsey base.
  style_baseline: "mckinsey"
  mckinsey:
    title_is_takeaway:      true   # title = the so-what, not the topic
    lead_with_so_what:      true
    parallel_structure:     true   # bullets share tense, opening part-of-speech
    strong_action_verbs:    true   # cut "is/has", prefer concrete verb
    cut_filler:
      - "in order to → to"
      - "a number of → many"
      - "due to the fact that → because"
      - "at this point in time → now"
    case:                   "sentence"   # lowercase unless proper noun or locked term
    em_dash_policy:         "use em-dash for parentheticals; use · (middle dot) in lists/footers"
  style_references:
    # Each entry is a PDF / .pptx reference. style_distill.py reads it and
    # emits rules (cadence, signature phrases, paragraph length, tone) that
    # layer on top of the McKinsey base. Conflicts: more recent entry wins;
    # user is asked at first conflict.
    # Example:
    # - path: "/path/to/sample.pdf"
    #   weight: 0.7
    []

  # ---- Structural anchor heuristics ----
  anchor_detection:
    min_pages: 3              # appears on ≥3 slides
    match_on:                 # signature components
      - position_xy
      - fill_color
      - font_size_class
    auto_protect: true

  # ---- Overflow estimator ----
  overflow:
    severity:
      high: 1.5
      med:  1.15
      low:  1.0
    surface_only: "high"      # surface MED/LOW only when explicitly asked
    defer_to_user_threshold: 10   # if HIGH > 10 → ask user to render externally

  # ---- CN ↔ EN slide alignment ----
  # Default is 1:1 (EN slide N maps to CN slide N).
  # Set overrides only when the two decks have been restructured.
  # Pass this config to excel_sync.py via `--cn-offset <yaml>`.
  cn_en_slide_offset:
    default: 0           # offset added to EN slide number (0 = 1:1)
    overrides: {}        # e.g. {"9-26": -1, "20": null}
                         # int = relative offset; null = no CN counterpart
```

> **Profile-agnostic note:** all sections below treat `PROFILE` as an
> opaque dict. Do not hardcode project-specific values anywhere outside the
> PROFILE block.

---

## 2. Pipeline stages

Each stage has: **inputs · what it does · outputs · stop-and-ask conditions.**

### Stage 1 — Sense Pass

**Inputs:** one or two `.pptx` paths (CN, optional EN draft)
**What it does:**
1. Run `scripts/sense_pass.py` to extract:
   - palette (top fill colors)
   - font usage histogram
   - size distribution
   - title-zone shapes (top ≤ 600K EMU)
   - layout heuristics
2. Cross-check sensed values against `PROFILE.palette` / `PROFILE.fonts`.
   If a sensed font is NOT in the whitelist AND NOT in `SKIP_POLLUTION`,
   record it as **font pollution**.
3. Surface **candidate glossary entries**: any CN noun phrase that appears
   ≥2 times and isn't already in `glossary.locked`.

**Outputs:**
- `Style_Manifest.md` (in-memory; not written to disk unless requested)
- `pollution_report` (slide → font → count)
- `candidate_glossary` (term → count → sample context)

**Stop-and-ask:**
- Candidate glossary surfaces a term Claude can't confidently translate →
  ask user, write answer to `glossary.session_added`.
- Sensed primary palette color differs from `PROFILE.palette.primary` →
  ask whether to update profile or keep existing.

---

### Stage 2 — McKinsey Translation (skipped in polish-only mode)

**Inputs:** Stage 1 outputs + the CN deck (and optional EN draft for diff context) + any uploaded `style_references`.

**Style layering**: McKinsey base rules (`PROFILE.mckinsey`) apply first. If
`PROFILE.style_references` is non-empty, run `scripts/style_distill.py` on
each reference before translation begins; the distilled rules (cadence,
signature phrases, paragraph length, tone) layer on top. More recent entry
wins on conflict; ask user at the first conflict.

**Page-by-page execution (hard requirement):**
1. **Overall confirmation first** — after Stage 1, show the user the planned
   per-page edit count + sample of style rules in effect; wait for "go".
2. **Then loop slides 1 → N**, one at a time:
   - Collect paragraph-level CN text on this slide via `scripts/extract.py`.
   - For each paragraph, produce EN per the layered style rules:
     - lowercase by default; title = so-what; parallel bullets; strong verbs;
       filler-word table applied; glossary `locked` inline
     - any unknown term → STOP, ask user, write to `session_added`
   - Build the slide's edit batch as a JSON object.
   - Run `scripts/apply.py` with the slide's batch → writes that slide's
     changes into `<file>-en-polished-<date>.pptx` AND appends rows to
     `<file>-bilingual-diff-<date>.xlsx` immediately.
   - **Checkpoint**: print "P{n} done — N changes applied. Continue?" and
     wait for user OK before moving to P{n+1}.
   - User can interject "back to P{n-1}" or "stop here" between pages.

**Why per-page (not all-at-once):**
- The user can review and steer mid-stream.
- A bad assumption on P3 doesn't propagate to P27 unnoticed.
- Excel grows incrementally — survives any mid-session interruption.
- Token-efficient: only one slide's context in active scratchpad.

---

### Stage 3 — Layout Audit

**Inputs:** the post-translation deck (or, in polish-only mode, the raw deck)
**What it does:**

#### 3a. Font pollution cleanup
Run `scripts/layout_audit.py --fix`:
- For every run whose `font.name` is NOT in the title/body whitelist
  OR ends in a style suffix (`Bold` / `Regular` / `Italic` / `Light`):
  - Strip the suffix
  - Set `font.name` to the pure family
  - Set `font.bold` / `font.italic` attributes accordingly
- Skip any face in the configured `SKIP_POLLUTION` set.

#### 3b. Structural-anchor detection
Run `scripts/anchor_detect.py`:
- For each shape, compute a signature: `(rounded_position, fill_color, font_size_class)`.
- Group across slides. Any signature occurring on ≥ `PROFILE.anchor_detection.min_pages`
  pages becomes an **anchor**.
- Build `per_page_protect[page] = [anchor_shape_ids...]`.
- Surface the anchor list to the user. They can add/remove.

#### 3c. Overflow estimation
Run `scripts/overflow_recheck.py`:
- Honor `auto_size` (skip if SHAPE_TO_FIT_TEXT or TEXT_TO_FIT_SHAPE).
- Read actual `margin_*`.
- Use `PROFILE.line_height_default = 1.25` initially. If a shape is flagged,
  try 1.15 as a what-if before flagging as HIGH.
- Per-character width by class (narrow `iIl`, wide `MW`, digits, upper, space).
- Greedy word-wrap simulation.
- Emit only HIGH (`ratio > PROFILE.overflow.severity.high`) by default.

If HIGH count > `PROFILE.overflow.defer_to_user_threshold`:
- **Do not** dump 30+ rendered PNGs into the session.
- Tell the user: "Render to PDF/PNG via Keynote or PowerPoint, tell me which
  pages look broken, I'll fix those targeted pages."

#### 3d. Compression (when user OKs a fix)
For each shape needing fix:
1. Is it in `per_page_protect[page]`? → SKIP (it's an anchor).
2. Try widening: increase shape `width` until ratio < 1.0 OR shape collides.
3. Still > 1.0? Try line-height 1.25 → 1.15.
4. Still > 1.0? Iterate `font.size -= PROFILE.compression_step` (0.1pt) until
   floor (`PROFILE.floors.<body|caption|source>`) hit.
5. Still > 1.0 at floor? **STOP. Escalate to user.** List the shape, its
   current size, the calculated ratio, and ask whether to break the floor.

#### 3e. Late-stage glossary re-scan
Run `scripts/glossary_audit.py`:
- For each text run in the deck, check against `glossary.locked`:
  - If a CN-side phrase exists locked but a non-canonical EN translation
    appears → flag.
  - If the same source term is translated two different ways in the deck
    (wavering) → flag.
- Surface flagged rows. Auto-fix if all flags point to the same canonical
  translation; ask otherwise.

#### 3f. Reverse sync (sub-routine, also Mode 3.5 entry point)
Run `scripts/excel_sync.py --reverse`:
- Diff current PPT against the Excel's `en_optimized` column.
- For each mismatched row:
  - Try ordinal-position match (slide + paragraph-index).
  - If no match, try `difflib.get_close_matches` against same-slide texts.
  - Update Excel cell on success.
- Report any leftover unmatched rows.

**Outputs:**
- `<file>-final-<date>.pptx` (full pipeline) or `<file>-final-<date>.pptx` (polish-only)
- Updated Excel (if applicable)

---

### Stage 4 — Handoff

**Inputs:** all prior-stage outputs
**What it does:**
1. Write `HANDOFF.md` to the same directory as the deck — see `scripts/handoff.py`.
2. Print a one-paragraph deliverables summary to the user.

**Stop-and-ask:** none.

---

## 3. Operational rules (apply across stages)

### 3.1 File-write discipline

Before writing **any** `.pptx` or `.xlsx`:
1. Check for `~$<filename>` lock file in the same directory.
2. If present → **STOP.** Tell the user: "`<filename>` is open in
   PowerPoint/Excel. Save and close it, then say 'go' to continue."
3. After writing, immediately readback-verify (next rule).

### 3.2 Excel companion three guard-rails

1. **Pre-write check** — load existing Excel (if any), confirm header row is
   `[page, kind, cn, en_original, en_optimized, notes]`. If columns missing
   → rebuild header before writing data.
2. **Post-write readback** — immediately reload the saved file and assert
   `max_column ≥ 7` and header is intact.
3. **Reverse sync** available on demand: see Stage 3f.

### 3.3 Font compression discipline

See Stage 3d. The single rule: **never** bulk-reduce font sizes.
Always discrete `-0.1pt`, always after exhausting widening + line-height
fallback, always with anchor protection.

### 3.4 Glossary discipline

- Ask once per session per unknown term. Then it's in `session_added` for
  the rest of the session.
- At handoff, promote `session_added` to a `glossary_proposed_additions.yaml`
  file next to the deck. The user can copy them into PROFILE for the next run.
- **Never** silently apply a translation Claude is unsure about. Stop and ask.

### 3.5 Magnitude verification

Any number with a CN magnitude word (百万 / 千万 / 亿 / 百亿 / 千亿 / 万亿)
must be re-verified against `PROFILE.unit_table` before being written to EN.
Treat this as a HARD CHECK; do NOT take prior-session translations on faith.

### 3.6 CN-alignment confidence

When auto-aligning the Excel's `cn` column by paragraph ordinal:
- Slides with > 15 changes → auto-tag `notes` column as `needs-review`.
- Always present this as best-effort, never as ground truth.

---

## 4. Scripts (in `scripts/`)

| Script | Role | Stage |
|---|---|---|
| `sense_pass.py` | extract design DNA, font usage, palette | 1 |
| `extract.py`    | paragraph-level text extraction | 1, 2, 3 |
| `apply.py`      | apply EN edits + write Excel with highlight | 2 |
| `layout_audit.py` | font pollution cleanup, suffix audit | 3a |
| `anchor_detect.py` | cross-page anchor signature detection | 3b |
| `overflow_recheck.py` | overflow estimator with severity tiers | 3c |
| `glossary_audit.py` | late-stage glossary re-scan + wavering | 3e |
| `excel_sync.py` | bidirectional PPT ↔ Excel sync (configurable slide offset) | 3f |
| `handoff.py`    | write HANDOFF.md | 4 |
| `style_distill.py` | distill style fingerprint from a reference PDF/.pptx | pre-2 |

Each script is invokable standalone; the skill wires them together.

---

## 5. Deliverables (recap)

**Full pipeline (4 files):**
- `<file>-en-polished-<date>.pptx`
- `<file>-final-<date>.pptx`
- `<file>-bilingual-diff-<date>.xlsx`
- `HANDOFF.md`

**Polish-only (3 files):**
- `<file>-final-<date>.pptx`
- `<file>-layout-changes-<date>.xlsx`
- `HANDOFF.md`

**Mode 3.5 (reverse-sync only):**
- updated `<file>-bilingual-diff-<date>.xlsx`

---

## 6. Known limitations

1. Overflow estimator is a **hint, not a verdict** — final visual check
   requires external rendering (Keynote / PowerPoint export to PDF).
2. `python-pptx` cannot render slides. There is no built-in preview.
3. CN auto-alignment by paragraph ordinal can drift on heavily-restructured
   pages — configure `PROFILE.cn_en_slide_offset.overrides` for known cases.
4. The skill assumes the CN source is semantic ground truth — typos in CN
   propagate to EN unless the user catches them.
5. File-lock collisions silently corrupt output. The pre-write `~$xxx` check
   is the only line of defense.

---

## 7. Changelog

See `CHANGELOG.md`.

---

## 8. Credits

Generic deck-globalization engine derived from upstream **DeckGlobalizer v2.1.1**
by tinadu-ai (<https://clawhub.ai/tinadu-ai/deckglobalizer>). Original
three-phase architecture (Visual Audit / Semantic Alignment /
Page-by-Page Execution) credited and retained.