產品真相
=== ===
一個展示了產品做不到的事情的產品影片,比沒有影片更糟。在這些技能所來自的製作過程中,代價最高的時刻都是真相失敗:一個手工製作的徽章帶有錯誤的尺寸和錯誤的產品名稱;一個工作流程被旁白為「等待通話結果」,但產品僅透過單獨的觸發器返回結果;一個被重新標記為已確認預訂的測試通話,但沒有人進行端到端驗證;一份公司文件的標題與團隊已同意的定位相矛盾。每一個都是在審查時才被發現,並且耗費了一個版本來修正。
此技能將檢查變得明確且機械化:每一行和每個畫面在 TRUTH.md 中都有一個帶有來源的資料列,而 truth_check.py 會拒絕任何資料列缺失、過時或無來源的影片。
輸入
videos/<video>/audio/lines.tsv(旁白,每行 ID 對應一個句子)videos/<video>/SOURCES.md(來自 source-recon:畫面及其程式碼)videos/<video>/BRIEF.md、COVERAGE.md、CLAIMS.md(影片必須說明的內容、定位、應避免的用語、需要核准的主張)product.yaml:positioning、never_say、names(正式名稱到舊版字串)、banned_termssources/<role>/和sources.lock(由 source-recon 鎖定;如果遺失,請先執行 source-recon,因為引用必須指向鎖定的提交)
1. 列出主張
將 lines.tsv 的每一行拆分成它所做出的主張。"Acme Tasks 會讀取您的行事曆,並將逾期任務移至明天" 包含兩個主張:它讀取行事曆,以及它移動逾期任務。每個畫面以及 SOURCES.md 和章節中描述的每個螢幕操作(例如「點擊「規劃我的一天」會開啟規劃器,並顯示三個建議」)都需添加一個主張。
撰寫這些主張所引發的問題,並以程式碼可回答的方式表述:這是什麼觸發的?儲存了什麼?有哪些選項?使用者會看到什麼、在哪裡看到?哪些事情僅在伺服器端發生?
2. 從程式碼和文件中解答
並行啟動唯讀的子代理,每個產品領域一個(前端行為、各後端、文件),使用 references/product-facts-prompt.md 中的提示。將它們指向 sources/<role>/,切勿指向使用者的工作目錄,這樣它們的行號才能與鎖定相符。它們僅從程式碼或文件中回答,引用每個事實,如果找不到則說「未找到」。
3. 分類每個主張
| 可見性 | 含義 | 影片可以 |
|---|---|---|
ui | 由前端渲染;引用模板或 i18n 行 | 顯示它並為其旁白 |
backend | 在伺服器上為真,螢幕上沒有任何顯示 | 為其旁白,永不繪製 UI |
docs | 只有文件這麼說 | 使用文件 URL 為其旁白;在可能的情況下檢查程式碼是否同意 |
mock | 一個設計好的元件,不是產品 UI(電話畫面、結束卡、生成的文字) | 顯示它,在 BRIEF 中標記為設計 |
| 評判 | 含義 |
|---|---|
backed | 來源確切地這麼說 |
approved | 需要簽署(受限、未發布、CLAIMS.md 中列出的主張),並且審查者在 CLAIMS.md 中已給予核准 |
needs-approval | 屬實,但受到限制、有門檻、未發布或在 CLAIMS.md 中列出;等待審查者 |
rewrite | 部分屬實;你在註解中提出有來源支援的措辭 |
cut | 不真實,或沒有找到來源 |
unbacked | 尚未檢查 |
mock | 僅適用於可見性 mock |
對於旁白的行,只有 backed 和 approved 才能通過。一個受限的功能(僅對某些角色、方案或內部團隊可見)、一個在功能開關後的功能,或一個在未合併分支上的功能,在審查者在 CLAIMS.md 中同意之前,是 needs-approval,並且 BRIEF 會備註其受限。這在原始製作中發生過:一個只有內部員工才能看到的功能,應審查者要求被展示,並已標記。
4. 修正不符之處
- 改寫部分屬實的句子,使其成為來源支援的最強版本。保留作者想要的意思;將機制改為真實的機制。
- 刪除沒有來源的內容。不要將其軟化為模糊的內容;模糊的主張仍然是主張。
- 切勿讓標籤偏離。 一個標記為「示意圖」的設計元件,不得為了後續美觀而丟棄該標籤,除非重新檢查未標籤版本所做的主張。
- 定位優於文件。 如果一個簡報或 PRD 說了一些
never_say或 CLAIMS.md 禁止的內容,則該規則獲勝,句子需要更改。 - 僅使用目前的名稱。 使用
product.yaml names中的正式名稱,即使即時 UI 或程式碼仍然顯示舊版字串。搜尋 lines.tsv、規格和模板中每個舊版字串和每個banned_terms項目(競爭對手、團隊不希望出現在螢幕上的第三方供應商、真實客戶),並修復每個命中。
5. 當請求與產品衝突時
當簡報或審查者要求某些程式碼不支援的內容時,不要偽造,也不要默默地放棄它。提出一個帶有選項和建議預設值的封閉式問題,並且每輪最多保留三個這樣的問題,因為無止盡的否決清單會無人回應,而沉默就變成了沒有人做出的決定。「只做真實的」模式:
簡報顯示 Acme Tasks 自己預訂會議室。程式碼只建立任務並連結會議室的行事曆(frontend/src/rooms/LinkRoom.tsx:22@1a2b3c4);預訂在行事曆應用程式中發生。選擇哪一個?
- 只做真實的(建議): 顯示連結步驟,並說「連結會議室的行事曆」。
- 將行事曆應用程式的預訂畫面顯示為一個設計元件,並加上標籤,且旁白為行事曆的步驟。
- 放棄這個節拍(Drop the beat)。
將答案記錄在 CLAIMS.md 中,並據此設定評判。
6. 撰寫 TRUTH.md
# 真相:<video>
已鎖定:前端 main@1a2b3c4,後端 main@5d6e7f8。檢查日期:2026-01-12。
| ID | 句子 | 來源 | 可見性 | 評判 | 備註 |
|---|---|---|---|---|---|
| N1 | Acme Tasks 從您的行事曆規劃您的一天。 | frontend/src/planner/plan.ts:31@1a2b3c4; https://docs.example.com/planner | ui | backed | |
| N2 | 逾期任務在午夜移至明天。 | backend/jobs/rollover.py:12-30@5d6e7f8 | backend | backed | 未在螢幕上顯示 |
| screen:board | 包含三個任務的看板,其中一個逾期 | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 | ui | backed | |
| screen:call | 與客戶通話 | (設計) | mock | mock | 在 BRIEF 中標記 |
## 未解決問題
1. <帶有建議答案的封閉式問題>
每個 lines.tsv 的行 ID 對應一個資料列,句子需完全複製(檢查時會進行比對,因此在真相驗證後編輯該行會導致失敗,直到您重新驗證)。每個畫面一個資料列,ID 為 screen:<name>,與 SOURCES.md 相符。多個引用放入一個儲存格,以分號分隔。
7. 檢查它
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/product-truth/scripts/truth_check.py" <video_dir>
在以下情況下檢查會失敗:一行沒有對應的資料列、句子已更改、旁白行的評判不是 backed 或 approved、引用的角色未被鎖定、其 SHA 不是鎖定的 SHA(程式碼已移動;需重新驗證)、其檔案不在匯出範圍內、或其行號超過檔案尾端。修復每個失敗;不要編輯檢查腳本。
向使用者報告:有多少行和畫面是 backed、你改寫和刪除了什麼(附上原因)、什麼正在等待核准、以及未解決的問題。