mck-ppt-design

McKinsey PPT Design — Harness Framework

Version: 2.3.3-harness-v2 · Engine: MckEngine (python-pptx) · Author: likaku

Required tools: Read, Write, Bash · Requires: pip install python-pptx lxml

---

よくある失敗パターン（生成のたびに必読。HARD RULES より先に確認）

AI にどのような成果物を作るか伝えるより、過去にどこで失敗しやすかったかを伝えるほうが効果的です。 以下の3つのアンチパターンは実際の実行で確認済みです。毎回、必ず意識してください。

アンチパターン 1：「ゲート通過」と口頭で宣言する（最もよくある失敗）

誤った方法：

「S4 QA では errors が7件あり、すべて engine の設計上の動作と判断したため、ゲートを通過して S5 に進みます」

問題点：passed がプログラムによって導出されたのではなく、AI の口頭判断になっています。どれほど十分な理由があっても、この発言は AI が自分自身に完了証明書を書いているのと同じです。

正しい方法：

1. python references/scripts/gate_check.py <pptx路径> <项目目录> を実行します
2. <项目目录>/gate_result.json を読み込みます
3. gate_result.json の "passed": true の場合に限り、S5 に進めます
4. "passed": false の場合は、user_code_errors のリストにある問題を修正して再レンダリングし、gate_check を再度実行します

---

アンチパターン 2：S3 ゲートを「頭の中で確認」しただけで通過とする

誤った方法：

「S3 コンテンツゲートの事前確認：API 形式は正しく、文字数も制限内なので、通過して S4 に進みます」（コードは何も実行していない）

問題点：今日実際に発生した3件の API 形式エラー（four_column／matrix_2x2／executive_summary のパラメーター形式）は、頭の中で確認しても見つけられません。コードによる確認が必須です。

正しい方法：

1. python references/scripts/gate_check_s3.py <content.json路径> <项目目录> を実行します
2. <项目目录>/gate_s3.json を読み込みます
3. "passed": true の場合に限り、S4 に進めます
4. fail 項目がある場合は、content.json を修正し、gate_check_s3 を再度実行します

---

アンチパターン 3：engine_bug 分類を逃げ道として使う

誤った方法：

「peer_font_inconsistency は engine 内部の設計上の動作であり、ユーザーコードの問題ではないため、許容できます」

問題点：この分類自体は正しいものですが、AI が会話の中で口頭判断すると、例外を認める権限を AI 自身に渡すことになります。AI には自分自身を通過させようとする動機があります。

正しい方法： gate_check.py には、ハードコードされた ENGINE_BUG_WHITELIST 列挙型があります。免除されるのは、ホワイトリストに含まれる error category のみです。ホワイトリストはコードであり、AI の判断ではありません。特定の error をホワイトリストに追加すべきだと考える場合は、口頭で免除を宣言するのではなく、gate_check.py の列挙型を変更してください。

---

HARD RULES（必ず守ること。回避不可）

1. 生成のたびに5段階のプロセスを実施すること。前段階を省略して「一言で直接生成」することはできません
2. TaskCreate で進捗を管理すること：開始前に5つの task を作成し、各段階が完了したらすぐに TaskUpdate で completed にします
3. 必要に応じてコンテキストを読み込むこと：各段階では対応するファイルのみを読み、旧版 SKILL.md の内容をすべて読み込まないでください
4. ゲートを機械で判定すること：S3 と S4 のゲートでは、対応する gate_check スクリプトを実行して JSON の結果を読み取り、口頭で判断してはいけません
5. Self-Refinement を必ず実施すること：pattern-level の問題を修正するたびに、experiences/ の対応するファイルに記録します
6. エンジンのパスは固定です：sys.path.insert(0, os.path.expanduser('~/.workbuddy/skills/mck-ppt-design'))

---

コンテキスト読み込みルート（コンテキスト読み込みインデックス）

各段階の開始時に、対応するファイルを読みます。一度にすべて読み込まないでください。

段階	必ず読むファイル	説明
S1 要件	references/team/brand-guide.md	デザイン上の制約を確認します
S2 構成	references/framework/engine-api.md + references/layout-matrix.yaml	レイアウトの選択と対応範囲
S3 内容	references/framework/guard-rails.md + experiences/*.md（存在する場合）	あふれ防止のルールと過去の失敗
S4 レンダリング	使用する references/layouts/*.md（実際に使うレイアウトのみを読む）	レイアウトの実装詳細
S5 納品	なし	—

完全なルート表：references/INDEX.md

---

5段階の生成プロセス

┌─────────┐   ┌─────────────┐   ┌─────────────┐   ┌──────────────┐   ┌──────────┐
│ S1 需求  │──▶│ S2 结构 ⭐   │──▶│ S3 内容 ⭐   │──▶│ S4 渲染+QA ⭐⭐│──▶│ S5 交付   │
│ brief.md│   │ outline.json│   │content.json │   │  .pptx       │   │ + 沉淀   │
└─────────┘   └─────────────┘   └─────────────┘   └──────────────┘   └──────────┘
                    ⭐ = 门禁（FAIL 则在本阶段修正，不得跳过）
    S3/S4 门禁必须运行 gate_check 脚本，读 JSON 结果 — 不得口头宣布通过

Stage 1: 要件定義

読むファイル：references/team/brand-guide.md

収集する情報：

• 対象者（役職／意思決定における役割）
• 目的（意思決定／報告／説得）
• 所要時間（分数 → 1ページあたり約1分）
• 重要なメッセージ（主要な message は最大5件）
• データソース（利用可能なデータ）

成果物：作業ディレクトリに ppt-project-{slug}/brief.md を作成します

ゲート：audience、goal、key_messages の3項目が空でないこと（AI による自己評価で可）

---

Stage 2: 構成設計

読むファイル：references/framework/engine-api.md、references/layout-matrix.yaml

タスク：

1. 所要時間に基づいてページ数を決めます（1分あたり1ページ）
2. 各スライドの layout を選びます（engine-api.md のクイックリファレンスを確認）
3. 各ページに中核となる key_point を1文で書きます（ラベルではなく、完全な文にします）
4. レイアウトが対応範囲内であることを確認します（layout-matrix.yaml を確認）

成果物：ppt-project-{slug}/outline.json

{
  "brief": {"audience": "董事会", "goal": "战略汇报", "duration_minutes": 15},
  "slides": [
    {"idx": 1, "layout": "cover", "title": "Q1 2026 战略回顾", "key_point": ""},
    {"idx": 2, "layout": "toc", "title": "目录", "key_point": ""},
    {"idx": 3, "layout": "table_insight", "title": "市场格局三大转变驱动战略重构", "key_point": ""}
  ]
}

⭐ ゲート S2（AI による自己評価）：

• cover スライドが存在する
• スライド数が所要時間の制約内である（count <= duration_minutes * 1.2）
• すべての layout が layout-matrix.yaml に定義されている
• Action Title がすべて完全な文である（len > 10、動詞を含む）
• two_column_text の数が1以下である

---

Stage 3: 内容の作成

読むファイル：references/framework/guard-rails.md、experiences/*.md（存在するファイルをすべて）

タスク：

1. 各スライドに具体的な文言、数値、グラフデータを入力します
2. 各ページに source の出典があることを確認します
3. layout-matrix.yaml の char_budget に従って文字量を調整します

成果物：ppt-project-{slug}/content.json

⭐ ゲート S3（必ず機械で判定し、AI の自己評価は禁止）：

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check_s3.py \
    <项目目录>/content.json  <项目目录>

<项目目录>/gate_s3.json を読み込みます：

• "passed": true → S4 に進みます
• "passed": false → fail_items に記載された問題を content.json で修正し、再度実行します

---

Stage 4: 渲染 + QA

读文件：用到的版式对应的 references/layouts/*.md

任务：

1. 根据 content.json 生成 Python 渲染脚本
2. 执行脚本生成 .pptx
3. 运行 QA 门禁脚本

⭐⭐ 门禁 S4（必须机读化，不得口头宣布通过）：

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check.py \
    <pptx路径>  <项目目录>

读取 <项目目录>/gate_result.json：

• "passed": true → 进入 S5
• "passed": false → 查看 user_code_errors，修复渲染代码，重新渲染，再次执行

注意：engine_bug 类 errors（peer_font_inconsistency 等白名单条目）由脚本自动豁免，不需要 AI 口头判断。

产出：<项目目录>/gate_result.json + .pptx

---

Stage 5: 交付 + Self-Refinement

任务：

1. 读取 gate_result.json 确认 passed: true（不得在无此文件时声称通过）
2. 交付 .pptx 文件
3. Self-Refinement：判断本次是否有 pattern-level 修正

⭐ Self-Refinement 协议：

修正后判断：
  ONE-TIME（单次特定调整）→ 不需要沉淀
  PATTERN（跨 deck 可重现的问题）→ 必须写入 experiences/
    - 溢出类 → experiences/overflow.md
    - 图表限制 → experiences/chart-limits.md
    - 版式踩坑 → experiences/layout-pitfalls.md
    - 中文渲染 → experiences/cjk-issues.md

格式：
  ## Experience NNN: {title}
  **Date**: YYYY-MM-DD
  **Problem**: ...
  **Root Cause**: ...
  **Fix**: ...
  **Rule**: ...（门禁层面如何预防）

---

Fast Track（简单需求跳过 S2/S3 门禁）

满足全部条件时，AI 可跳过 S2 结构评审和 S3 内容审查：

• 总页数 ≤ 5
• 无数据图表（donut/bar/table 类）
• 用户明确表达"快速"/"马上要"/"简单"

仍然必须：S1 需求收集 + S4 QA 门禁（gate_check.py 脚本执行）+ S5 交付

---

Checkpoint / 断点恢复

当用户说"继续做那个 PPT"时：

import os, json, glob

projects = glob.glob('ppt-project-*/')
for proj in projects:
    brief   = os.path.exists(f'{proj}brief.md')
    outline = os.path.exists(f'{proj}outline.json')
    content = os.path.exists(f'{proj}content.json')
    gate_s3 = os.path.exists(f'{proj}gate_s3.json')
    gate_s4 = os.path.exists(f'{proj}gate_result.json')
    pptx    = bool(glob.glob(f'{proj}*.pptx'))

    if not brief:           stage = 1
    elif not outline:       stage = 2
    elif not content:       stage = 3
    elif not gate_s3:       stage = '3-gate'   # content 有了但 gate 还没跑
    elif not pptx:          stage = 4
    elif not gate_s4:       stage = '4-gate'   # pptx 有了但 gate 还没跑
    else:                   stage = 5

    print(f"项目 {proj}: 当前处于 Stage {stage}")

---

MckEngine 快速模板

import sys, os
sys.path.insert(0, os.path.expanduser('~/.workbuddy/skills/mck-ppt-design'))
from mck_ppt import MckEngine
from mck_ppt.constants import *

eng = MckEngine(total_slides=12)
eng.cover(title='标题', subtitle='副标题', author='作者', date='2026年')
eng.toc(items=[('1', '章节一', '一句话描述'), ('2', '章节二', '一句话描述')])
# ... 内容页 ...
eng.closing(title='谢谢', message='期待进一步交流')
eng.save('output/deck.pptx')  # 自动 full_cleanup

详细 API：references/framework/engine-api.md 版式规范：references/layouts/ 10条护栏：references/framework/guard-rails.md 版式能力边界：references/layout-matrix.yaml 历史踩坑：experiences/ S3 门禁脚本：references/scripts/gate_check_s3.py S4 门禁脚本：references/scripts/gate_check.py