Atlas-KK/prd-lifecycle

PRD Lifecycle

將原本分散的 PRD 建立、補全、審查與執行規劃能力統一為單一入口，同時保留各階段不同的權限邊界與確認關卡。

模式路由

先判斷使用者目前擁有的材料與期望產物，只進入必要模式，不強迫使用者從頭走完整流程。

模式	典型輸入	主要產物	關鍵邊界
create 建立	功能構想 + 現有倉庫	現狀報告、確認基準、版本化 PRD	先取證、逐輪確認，未經核准基準前不產生 PRD
refine 補全	PRD/需求草稿	分步修訂稿、版本歷史、可選 .docx	每步先審閱，確認後才寫入與升版
review 紅隊審查	指定 PRD + 可選基準/倉庫	分級問題、證據、修訂建議	只審查，不修改文件、不實作程式碼
execute 執行規劃	已核准 PRD + 現有倉庫	就緒稽核、開發執行文件、追蹤矩陣、控制提示詞	只規劃，不修改 PRD、不實作程式碼

路由規則：

• 只有構想，且希望結合現有專案形成 PRD：使用 create。
• 已有草稿，目標是補全、修訂、精修或產出定稿：使用 refine。
• 目標是找出矛盾、風險、遺漏或不可驗收項目，不要求代改：使用 review。
• 已有明確核准版本，目標是交給 Codex 分階段開發：使用 execute。
• 使用者要求端到端處理時，從最早適用階段開始；每到下述關卡都停下等待授權，不自動跨階段。
• 「審一下」若同時可能表示審查或代改，優先採用唯讀的 review，並說明審查結果可在使用者另行授權後進入 refine。
• 使用者只想評估並實作現有倉庫中的局部程式碼、UI、互動、重構或架構變更，使用 repo-grounded-change；不要強制先寫 PRD。

共享約束

權威順序

除非使用者另行指定，按以下順序處理衝突：

1. 使用者當前明確指令。
2. 當前任務中已明確確認的決定。
3. 指定的已核准需求基準與 PRD。
4. 當前程式碼和測試所證明的既有行為。
5. 當前產品文件。
6. 歷史草稿、審查記錄與建議。

目標 PRD 不是天然正確的；出現衝突時展示衝突、影響與所需決定，不靜默選邊。程式碼用於證明現狀，不能否定已經核准的新需求。

事實與建議標籤

在結論可能被混淆時使用：已確認、程式碼事實、文件事實、產品假設、技術建議、待確認、本期不實作。

授權邊界

• 不臆造業務規則、狀態、閾值、權限、優先順序、相依性、外部整合或驗收標準。
• 不把階段完成、審查通過或計畫生成視為實作授權。
• 不修改業務程式碼，不提交、推送、部署，不呼叫外部生產系統。
• 檢查工作樹並保護使用者已有修改；無法安全避讓時停止並說明重疊區域。
• 只執行使用者請求的當前模式。進入下一模式必須有明確請求或確認。

create：倉庫取證後建立 PRD

1. 讀取 project-discovery.md，檢查倉庫、產品資料、測試和工作樹，輸出當前狀態報告。除非使用者明確要求合併流程，否則停下等待現狀確認。
2. 讀取 clarification-rounds.md，根據證據缺口規劃主題。每輪只討論一個主題，提出 1–3 個互斥選擇題；推薦項目在前並說明影響。
3. 使用者回答後先總結本輪已確認項、未確認項、衝突與下游影響，再等待本輪總結確認。未確認不得進入下一主題。
4. 所有相關主題確認後，讀取 baseline-and-prd.md，產生需求確認基準並停止。
5. 只有使用者明確核准基準並要求產生 PRD 後，才建立版本化 PRD；搜尋已有版本並遞增，不靜默覆蓋。

完成標準：PRD 與確認決定一致，範圍與非目標明確，需求與驗收可追蹤，倉庫影響有證據，未決事項沒有偽裝成最終要求。

refine：分步補全與版本化修訂

1. 讀取完整原文，保留原意並建立工作基準。若需要新建 Markdown 工作文件，使用 scripts/prd_doc.py init 建立 v1.0 與章節骨架。
2. 讀取 refinement-steps.md 當前步驟的小節。預設骨架為：
   • 需求釐清與使用者故事；
   • 功能方案；
   • 邊界條件；
   • 驗收標準。
3. 一次只做當前步驟。先在對話中呈現待審閱內容，不提前寫入檔案。
4. 使用者要求修改或補充時留在當前步驟，不升版。只有使用者明確確認後才寫入文件，並按 versioning.md 執行 minor 升版與修訂記錄。
5. 需要指標、相依性排程、風險回退、合規或審查意見回填時，可插入擴充步驟；同樣執行「產出 → 審閱 → 確認 → 寫入 → 升版」關卡。
6. 全部步驟確認後，整稿合併並執行 major 升版。使用者要求 .docx 時使用 scripts/prd_doc.py export，並按可用文件工具完成版式驗證。

每步內容既要補全，也要指出原文中的空泛、矛盾、不可驗證項與易漏場景。使用者故事、功能、邊界與驗收之間必須可回溯；驗收項應包含明確條件與可觀測結果。

完成修訂不等於 PRD 已獲業務核准，也不自動進入 review 或 execute。

review：證據化紅隊審查

1. 讀取 review-protocol.md，確認目標版本、審查範圍、權威來源、倉庫證據與缺失材料。完整閱讀目標 PRD。
2. 提取範圍、類型、狀態、閾值、權限、資料、時間、優先順序與驗收不變量。
3. 讀取 finding-taxonomy.md，分別檢查基準回歸、內部一致性、生命週期、資料歷史、介面等冪、權限稽核、原型邊界、NFR、可執行性與 FR/AC 追蹤。
4. 去重後僅保留有證據、有後果、可修正的問題。不要為了顯得全面而製造發現。
5. 讀取 review-report.md，給出 Pass、Pass with changes、Blocked 或 Limited review，並按嚴重度輸出發現、證據、影響與最小修正建議。

審查預設唯讀。即使發現明顯問題，也不得直接修改 PRD；使用者授權修訂後再進入 refine。

execute：轉為 Codex 開發執行文件

前提是存在可識別版本的已核准 PRD。修訂完成或紅隊通過本身不等於核准。

1. 讀取 readiness-audit.md，核對 PRD 版本、確認基準、目標釋出範圍、未決事項、當前倉庫與測試，形成差距表與就緒結論。
2. 若產品行為無法唯一確定、權威衝突、驗收不可觀察或需要未經授權的相依性/整合/遷移，結論為 BLOCKED 並停止，不把問題藏進技術假設。
3. 讀取 execution-document.md，定義滿足 PRD 的最小架構邊界、所有權、狀態、資料、介面、持久化、時鐘、降級與既有系統保護。
4. 從唯讀 Phase 0 開始，建立依賴有序、獨立可審閱的階段。每階段寫明 FR/AC、檔案範圍、禁止事項、測試、驗收證據、品質關卡與停止關卡。
5. 讀取 traceability-and-gates.md，映射每個範圍內 FR/AC 到階段、程式碼區域、測試與證據，識別孤兒需求與越權工作。
6. 讀取 codex-control-prompt.md，產生總控提示詞與單階段提示詞。提示詞必須保留版本、權威順序、真實測試、使用者變更保護與逐階段授權。

完成標準：另一個 Codex 實例能從唯讀稽核開始，只執行一個獲批階段，以真實命令驗證、報告追蹤結果並停止；文件明確假設、排除項、阻斷項、延期項與受保護行為。

階段銜接關卡

• create → refine：僅在使用者認為已產生 PRD 仍需補全或修訂時進入。
• create/refine → review：必須由使用者明確要求審查；審查不自動代改。
• review → refine：使用者明確授權處理指定發現後進入，逐項保留發現 ID 與修訂映射。
• create/refine/review → execute：必須明確指定「已核准」的 PRD 版本與目標釋出範圍。
• execute → implementation：執行文件只提供控制計畫；實際實作必須由使用者在後續任務中單獨授權。

反饋學習

工作流程開始時讀取 feedback-learning.md 與 learned-guidance.md。反饋先應用於當前任務；只有使用者明確要求記住並確認特定規則與作用域後，才允許持久化。學習規則不能覆蓋當前指令、階段關卡、事實核驗、版本管理或授權邊界。