printing-press-retro

/printing-press-retro

分析 Printing Press 執行階段，找出改進 CLI 生產系統的方法 — 包含 Go 二進位檔、樣板、Skills 與工作流程文件。重點不在於修正剛產出的特定 CLI，而是進行系統性改進，讓下一次產出的 CLI 更強大。

Printing Press 的目標並非「完全無需人工微調即可產出完美的 CLI」。 這本就是系統的本質。我們期望 Agent 能夠對產出的 CLI 進行推理，針對特定 API 進行客製化、建置創新功能並持續迭代。在每次執行中包含部分手工調整是正常現象。

復盤工作的核心，是找出人工操作中**機器確實有機會提升底線（Raise the floor）**的範疇 — 例如為 Agent 提供更好的起點、完全避免問題發生，或是消除在下一次產生 CLI 時會重複出現的摩擦。具體符合以下兩種明確情況：

1. 機器本可完全避免此問題，且該模式可通用於許多產出的 CLI。 提案建立 Issue。
2. 機器本可顯著提升底線 — 提供更好的預設值、部分骨架程式碼（Partial scaffold）、吸收樣板程式碼的 Helper — 且你能舉出多個 CLI 實例作為佐證。 提案建立 Issue。

除此之外的手工調整均屬於正常的迭代，不應產生提案項目。有些項目會回饋為機器層面的修正，但並非全部。復盤就是區分這兩者的過濾器。

復盤會在 printing-press 儲存庫中建立 GitHub Issue，附上通過初步篩選與對抗性檢查的發現事項以及相關產物（Artifacts），以便維護者（或 AI Agent）修復 Printing Press。

術語 (Terminology)

• The Printing Press：生產 CLI 的完整系統。在所有面向使用者的輸出（Issues、復盤文件、Prompts）中均使用此名稱。它包含四個子系統：
  • Generator — 產生 Go 程式碼的樣板（internal/generator/）
  • Scorer — 為輸出結果評分的工具：verify、dogfood、scorecard
  • Skills — 在產生過程中引導 Claude 的 SKILL.md 指引
  • Binary — Go CLI 本身：指令、旗標、剖析器（cmd/cli-printing-press/）
• Printed CLI：由 Printing Press 針對特定 API 所產出的 CLI（例如 notion-pp-cli）。針對 Printed-CLI 的修正只對該特定 CLI 有幫助。

在討論整體系統時請使用 "the Printing Press"。在指引開發者修復特定組件時，請使用子系統名稱 — 「修復 scorer」與「修復 generator」屬於不同的 PR。

基本原則 (Cardinal rules)

• Issue 內文與復盤文件屬於公開內容。在引用前必須遮蔽（Redact）所有真實的金鑰憑證與個人可識別資訊（PII）。 Manuscript（原稿資料夾）中包含憑證、帳號識別碼、真實 Email 以及即時 API 回應資料 — 這就是為什麼 references/secret-scrubbing.md 會在上傳產物前進行清理。Issue 內文會直接發布至公開的 GitHub Issue，而復盤文件本身會保留在原稿證明中，並可能以 zip 格式上傳。 當你引用掃描器輸出、dogfood 載荷、Greptile 審查留言或 API 回應內文作為「證據」時，在貼上之前必須將敏感字串替換為 <REDACTED:<kind>>。這在處理關於敏感資訊/PII 洩漏的發現時尤為重要：人們常本能地引用實際洩漏的值來證明洩漏存在 — 但這會導致敏感資訊在公開 Issue 中二次洩漏。Phase 5（撰寫復盤文件）與 Phase 6（發布前清理）會以機械化方式執行此規則；本規則是該機械化執行的可讀宣告。相關遮蔽模式與替換格式請參閱 references/secret-scrubbing.md "Layer 0"。
• 預設原則是「不要動機器」。 Printing Press 已經相當成熟 — 已產出 30+ 個 CLI，大多數樣板已在多種情境下經過驗證。舉證責任在於發現事項本身，而非 Skip 流程。你在產生單一 CLI 時遇到的多數問題，通常是該 CLI 的特殊性、迭代噪音或上游 API 的行為 — 而非 generator 的缺陷。只有在跨 CLI 的證據確鑿且發現事項通過 Phase 3 的對抗性檢查（Step G）時，才提出機器變更。
• 三個精準高質量的復盤發現，遠比十個品質參差不齊的發現更有價值。 每個提交的發現都會消耗維護者的精力。如果你發現自己寫下「每個發現都需要採取行動」，或者完全沒有任何捨棄（Drop）或跳過（Skip）的項目，請停下來重新評估 — 這種結果正是本 Skill 旨在防止的失敗模式。
• 復盤提出的 Printing Press 變更必須能惠及多個產出的 CLI。不要針對剛發布的單一 CLI 提出直接修改，也不要提出價值僅限於該 CLI 特殊需求的機器變更 — 那只是套著 generator 外衣的特定 CLI 修正。
• 切勿上傳未經清理的產物。 所有產物在上傳前都必須通過敏感資訊清理。
• 切勿修改原始碼目錄。 Manuscripts 與 library 目錄皆為唯讀。清理操作應在臨時副本上進行。
• 切勿跳過敏感資訊清理， 即使產生管線之前已經執行過一次。這是多重防禦（Defense in depth）。
• 切勿繞過 Printing Press 中的 scorer bug。 如果評分工具錯誤地扣分或懲罰某項內容，修正應直接作用於該評分工具。

設定 (Setup)

<!-- RETRO_SETUP_START -->

# Path-only setup — no binary detection required.
# The retro skill reads manuscripts and runs gh/curl. It does not invoke the
# cli-printing-press binary. This avoids aborting for users who installed the
# plugin but not the Go binary.

_scope_dir="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
_scope_dir="$(cd "$_scope_dir" && pwd -P)"

PRESS_HOME="${PRINTING_PRESS_HOME:-$HOME/printing-press}"
PRESS_MANUSCRIPTS="$PRESS_HOME/manuscripts"
PRESS_LIBRARY="$PRESS_HOME/library"
RETRO_SCRATCH_DIR="/tmp/printing-press/retro"

mkdir -p "$PRESS_MANUSCRIPTS" "$PRESS_LIBRARY" "$RETRO_SCRATCH_DIR"

# Detect whether we're inside the printing-press repo
IN_REPO=false
if [ -f "$_scope_dir/cmd/cli-printing-press/main.go" ]; then
  IN_REPO=true
  REPO_ROOT="$_scope_dir"
  echo "Running from printing-press repo: $REPO_ROOT"
fi

<!-- RETRO_SETUP_END -->

安全防護 (Guard rails)

無可復盤項目 (Nothing to retro)

if [ ! -d "$PRESS_MANUSCRIPTS" ] || [ -z "$(ls -A "$PRESS_MANUSCRIPTS" 2>/dev/null)" ]; then
  echo "No manuscripts found. Run /printing-press first to generate a CLI."
  exit 1
fi

解析 API 名稱 (Resolve which API)

如果使用者將 API 名稱作為引數傳入，則使用該名稱。驗證是否包含路徑穿越（Path traversal）：

# Reject names with /, \, or ..
if echo "$USER_API_NAME" | grep -qE '[/\\]|\.\.'; then
  echo "Invalid API name: '$USER_API_NAME'. Names cannot contain path separators or '..'."
  exit 1
fi

# Verify resolved path stays under PRESS_MANUSCRIPTS
RESOLVED="$(cd "$PRESS_MANUSCRIPTS/$USER_API_NAME" 2>/dev/null && pwd -P)"
case "$RESOLVED" in
  "$PRESS_MANUSCRIPTS"/*) ;; # OK
  *) echo "Invalid API name: path resolves outside manuscripts directory."; exit 1 ;;
esac

若未提供 API 名稱且存在多個 API，請列出這些 API 及其最近的執行日期，並請使用者選擇：

echo "Multiple APIs found in manuscripts:"
for api_dir in "$PRESS_MANUSCRIPTS"/*/; do
  api_name=$(basename "$api_dir")
  latest=$(ls -t "$api_dir" 2>/dev/null | head -1)
  echo "  - $api_name (latest run: $latest)"
done

使用 AskUserQuestion 讓使用者進行選擇。

解析執行紀錄 (Resolve which run)

若該 API 有多次執行紀錄，預設使用最新的一筆。若使用者指定了 run ID，則使用該 ID。否則：

API_DIR="$PRESS_MANUSCRIPTS/$API_NAME"
RUN_ID=$(ls -t "$API_DIR" 2>/dev/null | head -1)
RUN_DIR="$API_DIR/$RUN_ID"

echo "Retro for: $API_NAME (run $RUN_ID)"
echo "Manuscripts: $RUN_DIR"

解析 CLI 目錄 (Resolve CLI directory)

API_SLUG="$API_NAME"
CLI_NAME="${API_SLUG}-pp-cli"
CLI_DIR="$PRESS_LIBRARY/$CLI_NAME"

if [ ! -d "$CLI_DIR" ]; then
  # Try without -pp-cli suffix (legacy naming)
  CLI_DIR="$PRESS_LIBRARY/$API_NAME"
fi

if [ ! -d "$CLI_DIR" ]; then
  echo "WARNING: CLI directory not found at $PRESS_LIBRARY/$CLI_NAME"
  echo "Proceeding with manuscripts only — CLI source will not be included in artifacts."
  CLI_DIR=""
fi

執行時機 (When to run)

最佳效果是在產生 CLI 的同一對話中執行（在 shipcheck 完成後）— 復盤流程可以挖掘完整對話歷史中的錯誤、重試、人工修改與新發現。

若在全新的對話中執行，復盤將僅根據 manuscript（原稿）證據進行。Phase 2 會將依賴對話紀錄的發現標記為 "evidence: manuscripts only"。

Phase 1: 收集證據 (Gather evidence)

讀取本次執行的所有產物：

1. 研究簡報 (Research brief) — $RUN_DIR/research/*brief*
2. 吸收清單 (Absorb manifest) — $RUN_DIR/research/*absorb*
3. Shipcheck 證明 — $RUN_DIR/proofs/*shipcheck*
4. 建置日誌 (Build log) — $RUN_DIR/proofs/*build-log*（若存在）
5. 實機冒煙測試日誌 (Live smoke log) — $RUN_DIR/proofs/*live-smoke*（若存在）
6. 產出的 CLI — $CLI_DIR/（若可用）

同時收集記分板 (scorecard)、verify 通過率以及 dogfood 報告（取自 shipcheck 證明，或者在 IN_REPO 為 true 且 binary 可用時重新執行工具取得）。

Phase 2: 挖掘對話紀錄 (Mine the session)

掃描對話歷史中的六類訊號並產出候選清單（Candidate list）。候選清單並非最終的發現清單 — Phase 2.5 的初步篩選會進行淘汰，Phase 3 會進一步剔除品質較弱的項目。大多數候選項目最終都不會保留。

在收集時，請注意區分：

• 迭代噪音 (Iteration noise) — 在漫長的產生過程中偶發的重試、打字錯誤、正常的試錯。即使在候選階段也應跳過這些項目，它們無法通過篩選。
• 單一 CLI 的特殊性 (Per-CLI quirks) — 與該 API 形態綁定的特定行為（特殊的認證方式、未公開的端點、廠商特定的包裝格式），不會在其他規格中重複出現。將其加入候選清單並標記 "looks per-CLI" — 大多數會在初步篩選時被剔除。
• 系統性摩擦 (Systemic friction) — 在下一次產生 CLI 時合理預期會重複出現的模式（樣板缺陷、需要修改的預設值、誤導你的 Skill 指引）。這正是復盤旨在發掘的核心內容。

若在沒有產生歷史紀錄的新對話中執行： 請註明此點，並僅依據 manuscript 證據繼續執行。專注於 manuscript 所揭露的內容 — scorecard 缺陷、verify 失敗、dogfood 問題，以及 CLI 原始碼中明顯的樣板模式。將依賴對話紀錄的發現標記為 "evidence: manuscripts only"。

2a. 錯誤與重試 (Errors and retries)

任何指令執行失敗並重新執行的時刻、建置中斷，或是 Printing Press 產出了無法編譯的程式碼。發生了什麼故障？又是如何解決的？

2b. 人工程式碼修改 (Manual code edits)

迭代過程中的人工修改是正常的 — Agent 會對產出的 CLI 進行推理並微調。為了處理該 CLI 特殊性而進行的單次修改屬於正常工作流程。

針對每一次人工修改，請思考：機器是否有機會在此提升底線（Raise the floor）？

• 機器是否能完全避免這次修改？ 預設值對大多數 API 都是錯的、樣板產出了損壞的程式碼、剖析器漏掉了常見模式。如果是，且你能舉出多個需要相同修改的 CLI 實例作為佐證 → 列入候選。
• 機器是否能提供更好的起點，使修改更小、更簡單，或在常見情況下可直接跳過？ 即使仍需要微調，提升底線也能在未來的 CLI 中產生累積效益。如果是，且具通用性 → 列入候選。
• 這是否只是預期 Agent 應完成的特定 API 客製化？ 捨棄。
• 這是否屬於迭代噪音（打字錯誤、重試、暫時性的困惑）？ 捨棄。

初步篩選的核心問題是：機器提升底線是否能在未來的 CLI 產生累積效益...

<!-- truncated for translation batch; full body continues in source -->