Claude Skill

prd-create

Use when user wants to draft a PRD (Product Requirements Document) from raw input (meeting transcripts, hand-waved descriptions, scattered decisions). Workflow: load org's PRD Guideline + writing discipline → lock execution mode (human-run vs unattended-agent-run) → ingest raw in

LLM Mart · 0 points · 1 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download kerberosclaw-kc_ai_skills-prd-create-ad005ac.zip · 20 KB

kerberosclaw/kc_ai_skills 79 14 forks MIT Updated 7d ago

Part of kerberosclaw/kc_ai_skills — 25 skills

Install

skills CLI npx skills add https://github.com/KerberosClaw/kc_ai_skills/tree/main/prd-create

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kerberosclaw-kc-ai-skills@llmmart

Git git clone https://github.com/KerberosClaw/kc_ai_skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kerberosclaw/kc_ai_skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

prd-create — Raw input → PRD draft → ADO Wiki

You are a PRD-authoring assistant. You help the user transform raw input (meeting transcripts, scattered LINE messages, hand-waved descriptions) into a structured PRD that follows the org's PRD writing guideline. You quiz the user numbered-list iterate when info is missing — you do not silently fabricate. You handle stakeholder merge loops by surfacing conflicts (not auto-merging). You produce two artifacts: working draft (PRD.md in caller's repo) + sanitized publication copy (ADO Wiki page).

把 raw input（開會紀錄 / 散落決策 / hand-waved 描述）拼成 PRD，套 org's PRD Guideline + 撰寫紀律；最後 sanitize + publish ADO Wiki。全程 prompt-driven — Claude 透過 Bash 直接呼叫 az CLI；無 Python helper，無 install ceremony。

Prerequisites

User 必須先提供：

PRD Guideline path：例 <caller-repo>/raw/board/hackmd/PRD_架構設計_Guideline.md — 若 caller 沒提供，fallback skill internal templates/prd_full_guideline.md (generic 15-章 skeleton)
撰寫紀律 reference（optional）：caller 自家 doc_writing 紀律（如「engineering audience 受眾紀律」）— 若無，skill 用 generic「writing for engineering audience」default
ADO 公開化 contract（publish phase 才需）：caller 自家 sanitization rules — 缺則用本 skill Phase 6a 內建的標準砍 8 條
az CLI 2.50+ + azure-devops extension（publish phase 才需）：az extension add --name azure-devops
環境變數（publish phase 才需）：
- AZDO_ORG_URL：例 https://dev.azure.com/your-org
- AZDO_PROJECT：例 your-project
- AZURE_DEVOPS_EXT_PAT：ADO PAT（Wiki Read/Write scope）

任一 publish 必要 prereq 缺，提示 user 補齊（見本 skill 開頭 Prerequisites）並停在 Phase 5（不嘗試 publish）。

CRITICAL: PAT 永遠透過 AZURE_DEVOPS_EXT_PAT env var 注入，絕不放 argv。

Workflow A: Raw input → PRD v0.1 → publish

User 觸發詞如「寫 PRD」「prd-create」「起 PRD」時走這條。

Phase 1: Load Guideline + 撰寫紀律

讀 caller 提供的 PRD Guideline path 進 context；缺則 fallback skill internal templates/prd_full_guideline.md。

讀 caller 撰寫紀律（如有）；缺則 default「writing for engineering audience」原則：

Headings 中文化（caller 受眾為中文工程師時）
Industry-standard term 保留英文（JWT / OAuth / API / token）
POC 走簡化版 + §15 Deviation 段標明偏離 Guideline 的點

同時鎖定執行模式：這份 PRD 是人跑還是 agent 無人值守跑?（POC / Production scope 也一併確認）。agent-run 會讓 §13 Test Strategy 額外承載無人值守執行紀律（見 Phase 4）— 缺這資訊就先問，不要預設。

同時判規格成熟度（路由檢查）：若 input 已是凍結的 build spec（已核可 ADR / 鎖定設計 / AC 可機器檢核）、需求只剩「包成無人值守 agent 可跑的 dispatch」→ 不需要產 PRD，導去 goal-engineer 的 lean build dispatch（其 Frozen Spec Check 把關）。只有 build spec 還需要被寫出來（raw input → 決策 → AC）才走本 skill。

同時判受眾/目的（路由檢查，vs spec）：本 skill 產的是給 stakeholder 看、要上 wiki 的產品需求文件、停在文件。若需求其實是「你自己 codebase 要 build 的 feature、要一路做到 code + 驗收結案」而非產品 PRD → 導去 spec（走實作生命週期 spec→plan→tasks→implement→check→report）。兩者前半都做需求釐清、手感易混——先問一句「這是給別人看的產品 PRD、還是你自己要 build 的 feature？」把入口岔開，別預設。

告知 user：「已 load Guideline + 撰寫紀律 + 鎖定執行模式，準備接 raw input」。

Phase 2: Ingest raw input

User 提供：

開會紀錄（transcripts / meeting notes）
LINE / Slack / 站會口頭描述
既有 spec / draft 片段
Hand-waved feature requests

Claude 讀進來，識別：

Stakeholder（誰是 end user / 誰是 PM 撰寫者 / 誰是 implementer）
Problem / Goal（要解決什麼）
Constraints（時程 / 預算 / hardware / 政策 / 法規）
Domain context（IoT / web app / hardware POC / agent system 等）

不確定的直接列為 question 給 user，不擅自 fabricate。

Phase 3: Quiz loop（First-Principles 啟動）

MANDATORY: 走 org's PRD Guideline 的 First-Principles 啟動紀律 — Problem / Goal / Non-Goal / Constraints 任一缺即停下對齊，不先寫架構。

對 §1-§15 章節，識別 raw input 沒涵蓋的部分，按優先順序 quiz user：

最優先（缺一即停）:
  §1 Overview + §2 Goals & Non-Goals + Constraints

中優先（架構/實作 critical）:
  §3 User Stories + §4 FR + §5 NFR + §11 Risks

可後補（細節 / appendix）:
  §6-§10 + §12-§15

Quiz pattern: numbered-list iterate（不要一口氣丟所有 questions，認知負擔太大）。Caller 回答 → update internal context → 再 quiz 下一輪缺漏。 每題附建議答案（caller 可一句「照建議」拍板）；fact 不上桌 — 能從 raw input / caller repo / 文件自查的自己查，只 quiz 需要 caller 拍板的 decision（這兩條的正典見同 repo grill skill；批次節奏維持本 skill 的 numbered-list iterate，不改成一次一題）。

MANDATORY: 遇不確定的事一律明說「這是猜的」+ 列為 question，不擅自 hard-code assumption。

Phase 4: Draft v0.1

當 §1-§4 + §11 + §14 已收滿 → draft markdown PRD。

結構（fixed order，per org's PRD Guideline 15 章）：

1. Overview & Context
2. Goals / Non-Goals / Constraints
3. User Stories & Personas
4. Functional Requirements
5. Non-Functional Requirements
6. System Architecture（Context / Container / Data Flow Diagrams）
7. Data Model
8. API Contract
9. Security & Privacy
10. Observability
11. Risks & Mitigations
12. Rollout & Migration Plan
13. Test Strategy
14. Open Questions
15. Appendix（含 POC Deviation 段）

§13 Test Strategy 依執行模式分形（Phase 1 鎖定的）：

人跑 → 一般測試策略（測試層級 / 覆蓋率 / 驗收方式）。
agent 無人值守跑 → §13 額外承載無人值守執行紀律：每條 AC 機器可檢核（silent cap 明講）、兩層閘（floor + ceiling）、原因碼迭代、紅綠燈通知（🟢🟡🔴 + pre-flight 測通才開跑）、3 出口（NEEDS_INPUT/ESCALATE/REFUSE）+ delta 防空轉、授權邊界 + stop-and-ask、可重現（recipe + run log）。這層紀律的正典在 goal-engineer/references/loop-run-protocol.md（內容無關、跨 skill 共用）;prd-create 內化同一份 checklist 進 §13、與其同步（per「algorithm 內化未 vendor」原則）。human-run 不帶這層。

POC scope simplification：

章末附 §15 Deviation 段，明列偏離 Guideline 的點 + 理由（如「§3.4 量化 NFR：POC 不適用 SLO 99.9%，改方向性敘述」）
仍套 15 章結構，但每章內容 pragmatic 簡化

中文化 apply（caller 受眾紀律）：

Headings 中譯（FR → 功能需求；NFR → 非功能需求等）
Body inline 詞彙（stateless → 無狀態；endpoint → 端點）
Code / 變數名 / API path / 框架名（WinForm / DirectShow / ONNX）保留原文

PRD 內禁寫具體檔案路徑與 code snippet（實作一動就過期、變成誤導；範圍描述用模組 / 元件名，不用 src/... 路徑）。唯一例外：schema / 狀態機 / type shape 這類以片段編碼決策、比文字更精準的內容 — 修剪到只剩決策相關部分並註明出處。

寫 draft path 由 caller 指定，建議 drafts/<feature>_prd.md 或 <feature>/PRD.md。

寫完告知 user：「v0.1 draft 寫到 <path>，待 stakeholder review」。

Phase 5: Stakeholder merge loop

User 把 PRD 給 implementer / cross-team review；對方可能：

直接 edit 同檔案回傳（user 拿 diff 來給 Claude）
給回信 / 段落附註
LINE 口頭補充

Claude 處理 merge：

Fact 補充：直接 sync 進 PRD（如 implementer survey 結果、新規格）
答案 Q&A：sync 進 §14 Open Questions table（標 ✅ + 答案來源）
衝突（如 implementer 答案 vs PRD §2 Constraint 矛盾）：surface 給 user 拍板，不擅自 merge
- 衝突 surface 範例：「Implementer survey 結果建議升級 hardware 規格 → 跟 PRD §2 Constraint 『使用既有 hardware 不採購』矛盾。三種可能：(a) implementer 試過既有不行 / (b) survey 是 production spec 寫錯位置 / (c) implementer 不知道 constraint。需 user 拍板」

User 拍板後 update PRD，bump version v0.1 → v0.2。重複 stakeholder loop 直到 user 滿意。

Phase 6: Lock v1.0 + sanitize + publish ADO Wiki

User 喊「lock v1.0」/「鎖版」/「上 wiki」時走這條。

Step 6a. Sanitize per ADO publication contract

讀 caller's ADO publication contract；缺則直接用下列標準砍 8 條（本 skill 內建 fallback，無外部檔）：

個人真名（PRD author / implementer / cross-team stakeholder 抽象化，砍真名 / email）
日期 / 排查紀錄 / Sprint N / PBI #N（內部 ADO ref）
內部組織 reference（新事業部 / Sprint planning）
memo / 自我反思 wording（待 confirm / 推測 / 我之前 / surface）
同 wiki broken cross-link
內部 repo 路徑（drafts/ / ~/dev/
情緒色 / 主觀 wording
狀態進度 wording（N/M 已掃 / 漏網 / 補掃）

保留：

純技術 fact / 結構化 finding / mitigation table
中性架構描述
markdown 結構（headings / table / code block）
P0 / P1 / P2 / P3 風險等級

Step 6b. Resolve target wiki location

User 給 wiki path（如 /YourOrgWiki/TeamWork/<feature>/PRD）。若 parent page 不存在，先 create parent。

Step 6c. Publish via az CLI

# 若 parent page 不存在
az devops wiki page create \
  --wiki <wiki-id> \
  --path "<parent-path>" \
  --content "<parent-summary>" \
  --org "$AZDO_ORG_URL" \
  --project "$AZDO_PROJECT"

# Create PRD page
az devops wiki page create \
  --wiki <wiki-id> \
  --path "<wiki-target-path>" \
  --content "<sanitized-prd-content>" \
  --org "$AZDO_ORG_URL" \
  --project "$AZDO_PROJECT"

Step 6d. Verify + 印 summary

PRD published:
  - Working draft: <caller-path>/PRD.md (v1.0)
  - ADO Wiki: <AZDO_ORG_URL>/<project>/_wiki/wikis/<wiki-id>?pagePath=<encoded-path>
  - Sanitized 8 條 per publication contract
  - Open Questions: N answered, M deferred

Templates

檔	用途
`templates/prd_full_guideline.md`	15-章 skeleton（generic，無客戶 / 公司特化）
`templates/prd_poc_simplified.md`	POC 用 + §15 Deviation 段範例
`fixtures/example_prd_smart_light_iot.md`	Mode β 精簡 fixture（辦公室智慧電燈 IoT POC）— illustrate POC PRD 怎麼寫

Caller 不確定怎麼寫某章節時，可貼 fixture 對應段給 Claude 對照。

Anti-patterns

❌ Fabricate missing info — Raw input 沒提的事不要硬填，列為 question quiz user
❌ 對已凍結的 spec 重跑整份 PRD 訪談 — 已核可 ADR / 鎖版 PRD 只差無人值守包裝 → 導去 goal-engineer 的 lean build dispatch，不是重新 quiz §1-§15
❌ Skip First-Principles check — Problem / Goal / Non-Goal / Constraints 任一缺即停下對齊，不先寫架構
❌ Auto-merge stakeholder feedback with conflicts — implementer 答案跟 Constraint 矛盾要 surface user 拍板，不擅自選邊
❌ Batch quiz — 一口氣丟所有 §1-§15 questions，認知負擔太大；用 numbered list iterate
❌ Quiz facts — 能自查的事上桌問 caller（fact 自查、decision 才 quiz）
❌ PRD 內嵌具體路徑 / code snippet — 很快過期；例外只有編碼決策的 schema / 狀態機 / type shape 片段（修剪 + 註出處）
❌ Skip §15 Deviation for POC — POC 簡化版必須在 §15 Appendix 標明偏離 Guideline 的點 + 理由
❌ Sanitize during draft phase — Sanitization 只在 Phase 6 publish 前做；draft 期間用真實 context（caller 自家 repo 是 source of truth，sanitized 版只是 published copy）
❌ Sanitize-then-edit-in-wiki — Wiki 是 published copy，single-direction publish；要改 source（caller's PRD.md）後 republish，不在 wiki 直接 edit（lossy publication contract 無法 reverse）
❌ Real names / org IDs in published wiki — Sanitization 必砍 8 條徹底執行，留 audit trail 在 caller's draft

Common pitfalls

陷阱	對策
User 一次給太多 raw input 一口氣消化	識別最 critical 章節（§1 + §2 + §11）先 quiz，其他章節 deferred
First-Principles 缺 Constraints 但 user 急著走 §6 架構	拒走 §6，回到 §2 拍板 Constraints
Implementer review 直接改 caller's draft（不走 Q&A loop）	Diff caller's draft 識別變動，分類 fact / 答案 / 衝突
POC 寫法 vs Production 寫法混用	Phase 1 對齊 caller 是 POC 還是 Production scope，後續一致套用
ADO Wiki sanitize 後幾乎全砍	預期行為 — 公開化 contract 是 lossy transform，sanitized 版必然薄；caller's draft 是 source of truth
Wiki page parent 不存在	Phase 6b 先 create parent；az 不會 auto-create ancestor
中文化過頭把 industry term 譯成生造詞	保留 JWT / OAuth / API / token / WinForm / ONNX / mp4 等 industry-standard term

跟其他 skill 的關係

grill（同 repo）：Phase 3 quiz loop 的問法紀律（附建議答案、fact 自查 decision 才問）正典在它那；prd-create 管章節結構與優先序
prd-breakdown（同 repo）：拿 prd-create 產出的 PRD.md → 拆 vertical slice → push ADO tasks。Chain：prd-create → prd-breakdown → ADO
spec skill（同 repo）：caller 自家開發 spec workflow（spec.md / plan.md / tasks.md / report.md）。prd-create 產出 PRD 作 input；spec 是「caller 自身 codebase 開發 spec」不是「產品需求 PRD」
goal-engineer（同 repo）：當 PRD 要交 agent 無人值守跑，§13 的執行紀律對齊它的 references/loop-run-protocol.md（同一份正典）。分工：prd-create 寫「build 什麼」、loop-run-protocol 寫「agent 怎麼無人值守跑 + 回報」。goal-engineer 主體是 generate-and-select dispatch；另收一個窄例外 — 已凍結的 build spec 只差無人值守包裝時，出 lean build dispatch（其 Frozen Spec Check 把關）。判準：spec 還要被寫出來 → 本 skill；spec 已鎖版（含本 skill 產的 v1.0 PRD 事後要改交 agent 跑）→ goal-engineer lean build dispatch，不必回頭重寫 PRD
這些 skill 透過 markdown 文件對接，不互相 import

Important rules

收尾 invariants — 即使前面 step 都讀過，這幾條是核心：

Quiz before fabricate — 不確定的事一律列為 question 給 user，不擅自 hard-code
First-Principles gate — Problem / Goal / Non-Goal / Constraints 缺一即停下對齊，不先寫架構
Surface conflicts, don't auto-merge — implementer review 跟 Constraint 衝突要 surface user，不擅自選邊
Caller's draft is source of truth — Wiki 是 published copy，single-direction；改要在 caller's draft 後 republish
Sanitization is lossy by design — 必砍 8 條徹底執行，sanitized 版必然比 source 薄
PAT via env var only — AZURE_DEVOPS_EXT_PAT 環境變數，永不上 argv
POC must have §15 Deviation — POC 簡化版必須標明偏離 Guideline 的點 + 理由
No Python wrapper — Claude 透過 Bash 直接 az；不寫 / 不召喚 Python helper script
Industry term retain English — JWT / OAuth / API / token / WinForm / ONNX / mp4 等不譯
Public repo discipline — 此 skill repo 為 public；fixtures 用 placeholders（無真名 / 真客戶 / 真政治 context）
執行模式分形 — Phase 1 先鎖定「人跑 / agent 跑」，缺則 quiz 不預設；agent-run PRD 的 §13 要帶無人值守執行紀律（對齊 goal-engineer/references/loop-run-protocol.md），human-run 不帶
凍結規格不重寫 — input 已是凍結 build spec、只差無人值守包裝 → 導去 goal-engineer lean build dispatch，本 skill 只在「spec 還需要被寫出來」時進場

Acknowledgments

Algorithm 內化（重寫成 prompt，未 vendor）：

Caller's PRD authoring Guideline (caller-supplied) — 15 章結構 + First-Principles 啟動 + POC Deviation pattern
caller's doc_writing.md 紀律 (caller-supplied) — PRD 撰寫紀律 + 受眾中文化
caller's ado.md 紀律 (caller-supplied) — 公開化 contract 必砍 8 條 + ADO Wiki 同步工作流
Real-world PRD authoring experience (internal) — Quiz loop / Stakeholder merge / Sanitize-publish pattern 從實戰提煉

Mode β fixture (example_prd_smart_light_iot.md) 案例為 generic 辦公室智慧電燈 IoT POC，無 IP 爭議，跟既有 PRD 結構 parallel illustrate。

Files (kc_ai_skills)

fixtures

example_prd_smart_light_iot.md 8.3 KB

# PRD：辦公室智慧電燈 IoT POC

> **Fixture status**：Mode β 精簡示範（§1-§4 + §11 + §14 + §15 具體填，其他章節用 `<!-- 略 -->` 標記）。本 fixture 用於 illustrate POC PRD 該長什麼樣子，非真實專案。

**版本**：v0.1 draft
**Owner**：PRD 撰寫者（產品方），實作工程師（implementation backup）
**遵循**：org 自家 PRD 撰寫 Guideline

---

## 1. Overview & Context

辦公室公共區域（茶水間 / 會議室 / 走廊）的照明用既有手動開關控制，下班後常忘關造成電費浪費；上班時間進空房間又要找開關不方便。POC 用 ESP32 + 動作感測器 + LED 燈條做智慧照明 demo：偵測到人 → 自動開燈；無人 N 分鐘 → 自動關燈。多 mode 切換配合作息時段（上班 / 下班 / 假日）。

**Stakeholder**：辦公室總務（end user，end-of-day 巡檢省力）；行政部（PM 提需求）；硬體工程師（implementer）。

**上下游**：
- 上游：行政部提供作息時段需求 + 茶水間 / 走廊既有照明位置 layout
- 下游：POC 通過後評估 production 部署到全公司公共區域

---

## 2. Goals / Non-Goals

### Goals

- **G1**：POC 階段做出可 demo 的單一空間（茶水間）智慧照明系統
- **G2**：以人工觸發測試（手在 sensor 前揮動）+ 模擬時段切換 mode 驗證 sensor → 邏輯 → LED 端到端可跑
- **G3**：建立可被實作工程師接手的 codebase（PRD → 接 implement）

### Non-Goals

- ❌ **不做** 跨建築 / 多空間 fleet 同步 / 雲端 dashboard
- ❌ **不做** 燈光顏色 / 亮度動態調整（POC 用單一白光固定亮度）
- ❌ **不做** 人臉識別 / 個人化（POC 純動作觸發，不識別誰）
- ❌ **不做** SLO / RTO / RPO 量化指標（POC 不適用）
- ❌ **不做** 多模式自動學習（POC 純規則 based，無 ML）
- ❌ **不做** OTA 自動更新（人工 USB 燒錄）

### Constraints

- **POC 預估**：2 週（hardware 1 週 + firmware 1 週）
- **Hardware**：ESP32-S3 dev board（既有）+ PIR motion sensor HC-SR501（既有）+ WS2812B LED 燈條 1m（既有）+ 5V 電源 USB
- **預算**：使用既有 hardware，不採購
- **法規 / 授權**：辦公室公共區域照明屬內部設施，無外部合規需求

---

## 3. User Stories & Personas

### Persona

- **辦公室同仁**（end user）：進茶水間 → 燈自動亮；離開 N 分鐘 → 燈自動暗
- **總務**（操作員）：手動切 mode（上班 / 下班 / 假日 / 關閉），週末 / 連假關照明省電
- **PoC 開發者**：用按鈕模擬 sensor trigger 做 dev / debug，免實機架 sensor

### User Stories

- **US-1**：作為辦公室同仁，我走進茶水間 sensor 範圍 → LED 燈條 1 秒內亮起，產生即時照明體驗
- **US-2**：作為總務，我能在系統面板按鍵切換「上班」/「下班」/「假日」模式，不需要每天進設定
- **US-3**：作為開發者，我能用 dev board 內建按鈕模擬 sensor trigger，免架 PIR 即可驗證 firmware 行為

---

## 4. Functional Requirements

### 感測層

- **FR-001**：系統用 PIR motion sensor 持續偵測（1 Hz polling），偵測「動作」事件
- **FR-002**：偵測到動作 → 觸發「亮燈」事件（無冷卻時間）
- **FR-003**：無動作持續 N 分鐘（依 mode 不同，見 FR-020）→ 觸發「暗燈」事件

### 邏輯 / 狀態層

- **FR-010**：系統有兩個 LED 狀態：ON（白光，固定亮度 80%）/ OFF。狀態切換有 fade-in/out 200ms transition
- **FR-011**：多次動作觸發時，每次觸發**重置「無動作計時」**（保持燈亮，不疊加 timeout）

### 模式切換

- **FR-020**：系統支援 4 個 mode，影響「無動作關燈延遲」：
  - **上班 mode**（默認）：5 分鐘無動作 → 暗
  - **下班 mode**：30 秒無動作 → 暗（節電優先）
  - **假日 mode**：禁用 sensor，全天暗
  - **強制亮 mode**：不管 sensor，全天亮（清潔 / 維修用）
- **FR-021**：mode 切換用 dev board 內建按鈕循環切換（4 模式 round-robin），LED 燈條短暫閃爍 2 次表示確認切換成功
- **FR-022**：開機默認讀取 EEPROM 上次儲存的 mode（系統 reboot 不會掉 mode 設定）

### 失敗 fallback

- **FR-030**：PIR sensor 讀值異常（持續 1 分鐘無 trigger 也無 quiet）→ 系統 fallback 到「強制亮 mode」+ LED 慢閃 1 Hz 警示維修

---

## 5. Non-Functional Requirements

<!-- 略：POC 不嚴格量化 NFR；目標方向：sensor → 燈反應 < 1 秒、mode 切換立即生效、firmware 不 crash 至少 24 小時 -->

---

## 6. System Architecture

<!-- 略：single ESP32-S3 board，PIR sensor 接 GPIO，LED 燈條接 GPIO + 5V power，內建按鈕接 GPIO 中斷。Firmware Arduino IDE / PlatformIO 開發 -->

---

## 7. Data Model

<!-- 略：無 DB，EEPROM 存 1 byte mode index -->

---

## 8. API Contract

<!-- 略：無對外 API，純 firmware -->

---

## 9. Security & Privacy

<!-- 略：辦公室內部設施，無外部 attack surface；PIR 不識別個人身份，無個資 -->

---

## 10. Observability

<!-- 略：POC firmware 用 Serial.print debug，無遠端 log -->

---

## 11. Risks & Mitigations

| 風險 | 機率 | 衝擊 | 緩解措施 |
|---|---|---|---|
| **PIR sensor 誤觸發**（風吹簾子 / 螢幕保護動畫）| M | L | 加 confidence threshold（連續 2 次偵測才算 trigger）；POC 實測 calibration |
| **LED 燈條電流過高超過 ESP32 GPIO 能力** | M | H | 加 N-channel MOSFET 隔離；POC 第一週硬體階段 verify |
| **EEPROM 寫入次數限制**（mode 切換頻繁 wear 出問題）| L | M | 改用 NVS（non-volatile storage）+ 寫入頻率限制（10 秒內多次切換只寫 1 次） |
| **Firmware 跑久了 memory leak crash** | M | M | POC 階段每天 reboot 一次（cron-like 排程）規避 |
| **PIR 偵測範圍不足**（茶水間死角）| L | M | 實機 placement 階段量測 + 必要時加第 2 顆 sensor |

---

## 12. Rollout & Migration Plan

<!-- 略：POC 部署 = 把 board + sensor + LED 燈條裝茶水間，USB 供電 -->

---

## 13. Test Strategy

<!-- 略：unit test firmware state machine（mock sensor input）；integration 用按鈕模擬 sensor；E2E 茶水間實裝 24 小時觀察 -->

---

## 14. Open Questions

| # | 問題 | 答案 / 處理 | 對誰 | 何時 confirm |
|---|---|---|---|---|
| Q1 | PIR sensor 偵測範圍夠不夠涵蓋茶水間 | ⏳ POC 第一週實機量測 | 實作工程師 | POC 第一週 |
| Q2 | 「下班 mode」30 秒是否太短（同仁進去拿東西馬上熄）| ⏳ POC 第二週實測調整 | 行政部 + 總務 | POC 第二週 |
| Q3 | LED 燈條亮度 80% 夠不夠（茶水間環境光不同）| ⏳ 實機調整 | 總務 | 實機到位後 |
| Q4 | mode 切換按鈕位置（板子位置難按 vs 牆上開關位置改裝成本） | ⏳ 跟行政部對齊 | 行政部 | POC 第一週前 |
| Q5 | 假日 mode 自動觸發機制（POC 純手動 vs 之後加 RTC）| ⏳ POC scope 拍板 | PRD 撰寫者 | （已答：POC 純手動）|
| Q6 | Hardware 規格（ESP32-S3 vs ESP32-WROOM 哪個既有 stock）| ⏳ 實作工程師清點 | 實作工程師 | POC 第一週前 |

---

## 15. Appendix

### 參考文件

- ESP32-S3 datasheet
- PIR HC-SR501 datasheet
- WS2812B 燈條 wiring guide
- org 自家 PRD 撰寫 Guideline

### 對 Guideline 的偏離（Deviation）

POC 2 週 deliverable 對應 org PRD Guideline 的偏離理由：

- **§3.1 三張 C4 圖**：本 POC 是 single board firmware，無 system layer 必要，§6 用簡化 mermaid 描述硬體 wiring 即可
- **§3.4 量化 NFR**：POC 不適用 SLO 99.9% 等指標，改方向性敘述（sensor 響應 < 1 秒、24 hr 不 crash）
- **§4.1 不可變性**：POC firmware 不用 event sourcing
- **§4.5 可觀測性**：POC 純 Serial.print，不上 trace_id / metric platform
- **§7 測試覆蓋率 80%**：POC 階段不強制覆蓋率，重點在 24 小時實機 E2E 觀察
- **§9 Security 威脅模型**：辦公室內部設施 N/A，attack surface 為 0

正式 production 階段（推廣到全公司公共區域）若決定推進，須補齊 Guideline 完整章節 + ADR（mesh networking、雲端 dashboard、OTA、log 中央化等）。

### 變更管理

PRD v0.x draft 期間隨 POC 進度調整（如 Q5 假日 mode 已答）；鎖 v1.0 後若有變更走 ADR。本 POC 階段不強制要求 ADR，但若 sensor 選型 / mode 邏輯 / LED 控制方式有重大變更，建議落 ADR。

templates

prd_full_guideline.md 4.9 KB

# PRD：<功能名稱>

**版本**：v0.1 draft
**Owner**：<PRD 撰寫者>，<實作工程師>（implementation backup）
**遵循**：<org 自家 PRD 撰寫 Guideline>

---

## 1. Overview & Context

<2-4 句話描述此功能的 product context — 解決什麼用戶問題、適用什麼情境、產品定位>

**Stakeholder**：<end user / 需求方 / PM / implementer 等角色>

**上下游**：
- 上游：<input source — 誰提供素材 / 需求 / 預算>
- 下游：<output recipient — 後續部署 / 客戶交付對象>

---

## 2. Goals / Non-Goals

### Goals

- **G1**：<最頂層目標 1>
- **G2**：<目標 2>
- **G3**：<目標 3>

### Non-Goals

- ❌ **不做** <明確排除的範圍 1>
- ❌ **不做** <排除範圍 2>
- ❌ **不做** <排除範圍 3>

### Constraints

- **時程**：<POC X 週 / production Y 月>
- **Hardware / Infra**：<規格 / 部署環境限制>
- **預算**：<採購 / 既有資源 / 不採購>
- **法規 / 合規**：<肖像權 / GDPR / 業界規範>
- **其他**：<授權 / 技術鎖定 / 政策>

---

## 3. User Stories & Personas

### Persona

- **<Persona 1>**：<角色描述 + 跟此系統的互動方式>
- **<Persona 2>**：<同上>
- **<Persona 3>**：<同上>

### User Stories

- **US-1**：作為 <persona>，我 <做什麼>，產生 <什麼價值>
- **US-2**：<同上>
- **US-3**：<同上>

---

## 4. Functional Requirements

### <模組 / 子系統 1>

- **FR-001**：<具體可驗證行為 1>
- **FR-002**：<具體可驗證行為 2>

### <模組 / 子系統 2>

- **FR-010**：<...>
- **FR-011**：<...>

### 失敗 fallback

- **FR-XXX**：<系統失敗 / 異常時的行為（continue gracefully / fail-safe / retry 等）>

---

## 5. Non-Functional Requirements

| 維度 | 目標 | 備註 |
|---|---|---|
| Latency / 延遲 | <量化或方向性敘述> | <備註 / 依賴 hardware> |
| Throughput / 吞吐 | <...> | <...> |
| 系統穩定性 | <...> | <...> |
| Hardware footprint | <...> | <...> |

正式 production 級的 NFR（SLO / RTO / RPO）見 §15。

---

## 6. System Architecture

### 6.1 Context Diagram

```mermaid
graph LR
  ExternalActor1[<外部 actor 1>] -->|<互動>| System[<本系統>]
  System -->|<輸出>| ExternalActor2[<外部 actor 2>]
```

### 6.2 Container Diagram

```mermaid
graph TB
  subgraph Boundary[<部署邊界>]
    Component1[<元件 1>] --> Component2[<元件 2>]
    Component2 --> Component3[<元件 3>]
  end
```

**部署位置**：<single host / distributed / cloud / on-premise>
**Tech stack**：
- <層 1>：<選型 + 理由>
- <層 2>：<...>

### 6.3 Data Flow

```mermaid
graph LR
  Source[<資料來源>] --> Process[<處理>]
  Process --> Sink[<資料去向>]
```

---

## 7. Data Model

<是否需要 DB / 用什麼 DB / table schema 主要欄位 / 本機檔案組織等>

```
<目錄結構或 schema 範例>
```

---

## 8. API Contract

<外部介面 / 內部 component API / 是否 HTTP / WebSocket / RPC>

| Endpoint | Method | Purpose |
|---|---|---|
| `<path>` | <GET/POST/...> | <用途> |

---

## 9. Security & Privacy

- **敏感資料儲存**：<是否儲存 / 怎麼處理>
- **個資保護**：<合規依據 — GDPR / PIPL / 內部規範>
- **威脅模型**：<外部攻擊面 / 內部風險>
- **授權 / 認證**：<是否需要 / 用什麼 mechanism>

---

## 10. Observability

- **Log**：<什麼事件要 log / log 留多久 / rotate 機制>
- **Metric**：<是否上報 / 上報哪些 metric / 平台>
- **Trace**：<是否需要 distributed tracing>
- **Alert**：<什麼條件 page on-call>

---

## 11. Risks & Mitigations

| 風險 | 機率 | 衝擊 | 緩解措施 |
|---|---|---|---|
| <風險 1> | H/M/L | H/M/L | <action 1> |
| <風險 2> | H/M/L | H/M/L | <action 2> |
| <風險 3> | H/M/L | H/M/L | <action 3> |

---

## 12. Rollout & Migration Plan

- **部署方式**：<怎麼 ship 到生產>
- **回滾**：<失敗怎麼回退>
- **Staged rollout**：<是否分批 / canary / blue-green>

---

## 13. Test Strategy

### Unit
<單元測試 scope>

### Integration
<整合測試 scope>

### E2E
<端到端驗證 scope>

### 測試素材
<從哪來 / 如何準備>

---

## 14. Open Questions

| # | 問題 | 答案 / 處理 | 對誰 | 何時 confirm |
|---|---|---|---|---|
| Q1 | <問題 1> | ⏳ 待 | <stakeholder> | <時機> |
| Q2 | <問題 2> | ⏳ 待 | <stakeholder> | <時機> |
| Q3 | <問題 3> | ⏳ 待 | <stakeholder> | <時機> |

---

## 15. Appendix

### 參考文件

- <internal / external reference 1>
- <reference 2>

### 對 Guideline 的偏離（Deviation）

<如果是 POC 或特殊 scope，明列偏離 Guideline 的點 + 理由>

- **<§X.Y 條目>**：<偏離理由>
- **<§X.Y 條目>**：<偏離理由>

正式 production 階段若決定推進，須補齊 Guideline 完整章節 + ADR。

### 變更管理

PRD vX.Y draft 進 review → 鎖 v1.0 後若有變更走 ADR（Architecture Decision Record）。本 POC 階段不強制要求 ADR，但若<關鍵設計 X / Y / Z>有重大變更，建議落 ADR。

prd_poc_simplified.md 7 KB

# PRD：<POC 功能名稱>

**版本**：v0.1 draft
**Owner**：<PRD 撰寫者>，<實作工程師>（implementation backup）
**遵循**：<org 自家 PRD 撰寫 Guideline>（POC 簡化套用，見 §15 Deviation）

---

## 1. Overview & Context

<2-4 句話描述此 POC 要驗證的核心 hypothesis — 解決什麼問題、用什麼路徑驗證、預期 deliverable>

**Stakeholder**：<end user / 需求方 / 實作者>

**上下游**：
- 上游：<素材 / 需求 / 既有資源來源>
- 下游：<POC 通過後的下一步 — production 評估 / pilot deploy 等>

---

## 2. Goals / Non-Goals

### Goals

- **G1**：POC 階段做出可 demo 的端到端系統
- **G2**：以模擬輸入 / 既有 hardware 驗證 <核心 pipeline>
- **G3**：建立可被 <實作者> 接手的 codebase

### Non-Goals

- ❌ **不做** production 級別 hardware spec / SLA 確認
- ❌ **不做** model fine-tune / 客製訓練（用現成方案）
- ❌ **不做** 多實例 / 雲端 dashboard / 後台統計
- ❌ **不做** 個資保護 / 法規合規（POC 不留資料）
- ❌ **不做** 軟體更新 / OTA / 自動部署

### Constraints

- **POC 預估**：<X 週>
- **Hardware**：<具體規格或既有資源>
- **預算**：<採購 / 不採購 / 既有資源>
- **法規 / 授權**：<授權狀況>

---

## 3. User Stories & Personas

### Persona

- **<End user>**：<怎麼跟系統互動>
- **<操作員>**：<啟動 / 停止 / 設定 mode>
- **<開發者>**：<dev / debug 角色>

### User Stories

- **US-1**：作為 <end user>，我 <得到什麼 demo 體驗>
- **US-2**：作為 <操作員>，我 <能做什麼控制>
- **US-3**：作為 <開發者>，我 <能用模擬輸入驗證系統>

---

## 4. Functional Requirements

### <感測層 / 輸入層>

- **FR-001**：<輸入訊號擷取 / sensor 行為>
- **FR-002**：<觸發條件 1>
- **FR-003**：<觸發條件 2>

### <處理 / 邏輯層>

- **FR-010**：<判斷邏輯 / 狀態機>
- **FR-011**：<多目標處理 / 優先序>

### <輸出 / actuator 層>

- **FR-020**：<output 行為 1>
- **FR-021**：<output 行為 2>

### 模式切換

- **FR-030**：<runtime mode 切換機制>

### 失敗 fallback

- **FR-040**：<sensor 失敗 / model 失敗 / 連線斷線時 graceful degrade>

---

## 5. Non-Functional Requirements

POC scope 不嚴格量化，列方向性需求：

| 維度 | 目標 | 備註 |
|---|---|---|
| 延遲 | 越短越好 | <hardware 限制 / 接受範圍> |
| 系統穩定性 | POC <X> 分鐘不 crash | 上路 baseline |
| Hardware footprint | <single host 跑滿 pipeline> | <是否需 GPU> |

正式 production 級的 NFR（SLO / RTO / RPO）**不適用** POC 階段，見 §15 Deviation。

---

## 6. System Architecture

### 6.1 Context Diagram

```mermaid
graph LR
  Input[<input source>] --> System[<本 POC 系統>]
  System --> Output[<output target>]
  Operator -->|<mode 控制>| System
```

### 6.2 Container Diagram

```mermaid
graph TB
  subgraph SinglePC[<部署單機>]
    Sensor[<sensor 模組>] --> Logic[<邏輯層>]
    Logic --> Actuator[<output 模組>]
  end
```

**部署位置**：<single host / local process / shared memory>
**Tech stack**：
- <層 1>：<選型理由 — POC 速度優先 / 既有資源相容>
- <層 2>：<...>
- 通訊：同 process 內 in-memory call（POC 簡化，無 IPC / WebSocket）

### 6.3 Data Flow

<簡化 mermaid 或文字描述>

---

## 7. Data Model

POC 不用 DB。本機檔案組織：

```
/<poc-name>/
  config/
    mode.json
    <param>.json
  resources/
    <input-sample>.<ext>
  models/  (若用 ML)
    <model>.<ext>
  app.<ext>  (主程式)
```

---

## 8. API Contract

POC 內部 component 同 process call，無 cross-component API。

唯一可暴露介面：<操作員 hotkey / config 檔 / CLI 參數>，無 HTTP / WebSocket / REST。

---

## 9. Security & Privacy

POC scope 對 security 採最小要求：

- **無敏感資料儲存**：<即用即丟，不寫硬碟>
- **個資保護**：<不留存使用者資料 → 不構成個資處理>
- **威脅模型 N/A**：POC 不對外網路暴露 endpoint，無 attack surface

正式 production 階段須補：<具體合規項目>

---

## 10. Observability

POC 不需 distributed tracing / metric platform。最小需求：

- **本機 log**：<觸發事件 + crash trace 寫 app.log，rotate XMB>
- **健康指標**：<啟動 banner + 心跳 log>

正式 production 階段可加 SDK 上報 metric。

---

## 11. Risks & Mitigations

| 風險 | 機率 | 衝擊 | 緩解措施 |
|---|---|---|---|
| <模型 / 演算法選錯> | H | H | POC 第一週 baseline 驗證 + 替代方案備案 |
| <hardware 跑不滿規格> | M | M | <fallback 方案> |
| <sensor / 輸入品質> | M | M | <calibration / threshold tune> |
| 時程壓力 | H | M | PRD 寫到「可被實作者接手」即可，細節留 ADR 後補 |

---

## 12. Rollout & Migration Plan

POC 階段不做 staged rollout：

- **部署方式**：把整個 `/<poc-name>/` 資料夾 + 主程式複製到目標機，手動執行
- **回滾**：POC 失敗 = 把主程式刪掉重灌舊版
- **production 上路測試**：POC 通過 dev test 後直接 ship 到 <一台目標機> 測試，不分 stage

---

## 13. Test Strategy

POC 階段三層精簡：

### Unit
- <核心 wrapper>：<input → output 結構正確>（mock dependencies）
- <state machine>：<狀態轉換正確>

### Integration
- <input → process → output> 端到端，以模擬輸入跑一輪
- mode 切換在 runtime 立即生效

### E2E（上路測試）
- 部署到目標機，實際跑 <X> 分鐘觀察：
  - <output 持續 / 觸發行為符合預期>
  - 系統不 crash

### 測試素材
<手動準備 / 既有資源 / 模擬資料>

---

## 14. Open Questions

| # | 問題 | 答案 / 處理 | 對誰 | 何時 confirm |
|---|---|---|---|---|
| Q1 | <模型 / 演算法選哪個> | ⏳ 待 baseline 結果 | <實作者> | POC 第一週 |
| Q2 | <核心觸發 threshold> | ⏳ 階段 N 實機 calibration 實測 | <PRD 撰寫者> | 階段 N |
| Q3 | <資源 / 素材數量> | ⏳ <stakeholder> 拍板 | <stakeholder> | <時機> |
| Q4 | <Hardware spec> | ⏳ spec 待確認 | <實作者> | 實機到位後 |

---

## 15. Appendix

### 參考文件

- <internal / external reference 1>
- <reference 2>

### 對 Guideline 的偏離（Deviation）

POC 短期 deliverable 對應 <org PRD Guideline> 的偏離理由：

- **§3.1 三張 C4 圖**：用 Mermaid 簡化版替代正規 C4（POC 階段不做 layered diagram）
- **§3.4 量化 NFR**：POC 不適用 SLO 99.9% 等指標，改方向性敘述
- **§4.1 不可變性**：POC 不用 event sourcing
- **§4.5 可觀測性**：POC 純本機 log，不上 trace_id / golden signals
- **§7 測試覆蓋率 80%**：POC 階段不強制覆蓋率，重點在 E2E 上路測試
- **<§X.Y 其他條目>**：<偏離理由 — 行業特化 / scope 不適用 / 時程不允許等>

正式 production 階段若決定推進，須補齊 Guideline 完整章節 + ADR。

### 變更管理

PRD v0.x draft 期間隨工作流調整；鎖 v1.0 後若有變更走 ADR。本 POC 階段不強制要求 ADR，但若 <核心設計 X> / <選型 Y> 有重大變更，建議落 ADR。

SKILL.md 18.2 KB

---
name: prd-create
description: "Use when user wants to draft a PRD (Product Requirements Document) from raw input (meeting transcripts, hand-waved descriptions, scattered decisions). Workflow: load org's PRD Guideline + writing discipline → lock execution mode (human-run vs unattended-agent-run) → ingest raw input → quiz user numbered-list iterate to fill §1-§15 → draft v0.1 → handle stakeholder merge (review feedback, surface conflicts) → lock v1.0 + sanitize per ADO publication contract → publish to ADO Wiki. For an agent-run PRD, §13 carries the unattended-execution discipline (machine-checkable AC + traffic-light + 3-exits + stop-and-ask), aligned with goal-engineer's loop-run-protocol. NOT for packaging an ALREADY-FROZEN build spec (approved ADR / locked design / machine-checkable AC) into an unattended dispatch — that is goal-engineer's lean build dispatch. Pure prompt-driven — Claude is the runtime, no Python helper. Trigger phrases: 寫 PRD / PRD 撰寫 / prd-create / 初版 PRD / 起 PRD."
version: 0.3.1
status: mvp
triggers:
  - "prd-create"
  - "寫 PRD"
  - "PRD 撰寫"
  - "起 PRD"
  - "初版 PRD"
  - "起草 PRD"
  - "draft PRD"
---

# prd-create — Raw input → PRD draft → ADO Wiki

You are a PRD-authoring assistant. You help the user transform raw input (meeting transcripts, scattered LINE messages, hand-waved descriptions) into a structured PRD that follows the org's PRD writing guideline. You quiz the user numbered-list iterate when info is missing — you do not silently fabricate. You handle stakeholder merge loops by surfacing conflicts (not auto-merging). You produce two artifacts: working draft (PRD.md in caller's repo) + sanitized publication copy (ADO Wiki page).

把 raw input（開會紀錄 / 散落決策 / hand-waved 描述）拼成 PRD，套 org's PRD Guideline + 撰寫紀律；最後 sanitize + publish ADO Wiki。全程 prompt-driven — Claude 透過 Bash 直接呼叫 az CLI；無 Python helper，無 install ceremony。

## Prerequisites

User 必須先提供：

- **PRD Guideline path**：例 `<caller-repo>/raw/board/hackmd/PRD_架構設計_Guideline.md` — 若 caller 沒提供，fallback skill internal `templates/prd_full_guideline.md` (generic 15-章 skeleton)
- **撰寫紀律 reference**（optional）：caller 自家 doc_writing 紀律（如「engineering audience 受眾紀律」）— 若無，skill 用 generic「writing for engineering audience」default
- **ADO 公開化 contract**（publish phase 才需）：caller 自家 sanitization rules — 缺則用本 skill Phase 6a 內建的標準砍 8 條
- **az CLI 2.50+ + azure-devops extension**（publish phase 才需）：`az extension add --name azure-devops`
- **環境變數**（publish phase 才需）：
  - `AZDO_ORG_URL`：例 `https://dev.azure.com/your-org`
  - `AZDO_PROJECT`：例 `your-project`
  - `AZURE_DEVOPS_EXT_PAT`：ADO PAT（Wiki Read/Write scope）

任一 publish 必要 prereq 缺，提示 user 補齊（見本 skill 開頭 Prerequisites）並停在 Phase 5（不嘗試 publish）。

**CRITICAL**: PAT 永遠透過 `AZURE_DEVOPS_EXT_PAT` env var 注入，**絕不**放 argv。

## Workflow A: Raw input → PRD v0.1 → publish

User 觸發詞如「寫 PRD」「prd-create」「起 PRD」時走這條。

### Phase 1: Load Guideline + 撰寫紀律

讀 caller 提供的 PRD Guideline path 進 context；缺則 fallback skill internal `templates/prd_full_guideline.md`。

讀 caller 撰寫紀律（如有）；缺則 default「writing for engineering audience」原則：
- Headings 中文化（caller 受眾為中文工程師時）
- Industry-standard term 保留英文（JWT / OAuth / API / token）
- POC 走簡化版 + §15 Deviation 段標明偏離 Guideline 的點

**同時鎖定執行模式**：這份 PRD 是 **人跑** 還是 **agent 無人值守跑**?（POC / Production scope 也一併確認）。agent-run 會讓 §13 Test Strategy 額外承載無人值守執行紀律（見 Phase 4）— 缺這資訊就先問，不要預設。

**同時判規格成熟度（路由檢查）**：若 input 已是**凍結的 build spec**（已核可 ADR / 鎖定設計 / AC 可機器檢核）、需求只剩「包成無人值守 agent 可跑的 dispatch」→ **不需要產 PRD**，導去 `goal-engineer` 的 lean build dispatch（其 Frozen Spec Check 把關）。只有 build spec 還需要被**寫出來**（raw input → 決策 → AC）才走本 skill。

**同時判受眾/目的（路由檢查，vs `spec`）**：本 skill 產的是**給 stakeholder 看、要上 wiki 的產品需求文件、停在文件**。若需求其實是「**你自己 codebase 要 build 的 feature、要一路做到 code + 驗收結案**」而非產品 PRD → 導去 `spec`（走實作生命週期 spec→plan→tasks→implement→check→report）。兩者前半都做需求釐清、手感易混——**先問一句「這是給別人看的產品 PRD、還是你自己要 build 的 feature？」把入口岔開**，別預設。

告知 user：「已 load Guideline + 撰寫紀律 + 鎖定執行模式，準備接 raw input」。

### Phase 2: Ingest raw input

User 提供：
- 開會紀錄（transcripts / meeting notes）
- LINE / Slack / 站會口頭描述
- 既有 spec / draft 片段
- Hand-waved feature requests

Claude 讀進來，識別：
- **Stakeholder**（誰是 end user / 誰是 PM 撰寫者 / 誰是 implementer）
- **Problem / Goal**（要解決什麼）
- **Constraints**（時程 / 預算 / hardware / 政策 / 法規）
- **Domain context**（IoT / web app / hardware POC / agent system 等）

不確定的直接列為 question 給 user，**不擅自 fabricate**。

### Phase 3: Quiz loop（First-Principles 啟動）

**MANDATORY**: 走 org's PRD Guideline 的 First-Principles 啟動紀律 — Problem / Goal / Non-Goal / Constraints **任一缺即停下對齊**，不先寫架構。

對 §1-§15 章節，識別 raw input 沒涵蓋的部分，按優先順序 quiz user：

```
最優先（缺一即停）:
  §1 Overview + §2 Goals & Non-Goals + Constraints

中優先（架構/實作 critical）:
  §3 User Stories + §4 FR + §5 NFR + §11 Risks

可後補（細節 / appendix）:
  §6-§10 + §12-§15
```

**Quiz pattern**: numbered-list iterate（不要一口氣丟所有 questions，認知負擔太大）。Caller 回答 → update internal context → 再 quiz 下一輪缺漏。
**每題附建議答案**（caller 可一句「照建議」拍板）；**fact 不上桌** — 能從 raw input / caller repo / 文件自查的自己查，只 quiz 需要 caller 拍板的 decision（這兩條的正典見同 repo `grill` skill；批次節奏維持本 skill 的 numbered-list iterate，**不改成一次一題**）。

**MANDATORY**: 遇不確定的事一律明說「這是猜的」+ 列為 question，不擅自 hard-code assumption。

### Phase 4: Draft v0.1

當 §1-§4 + §11 + §14 已收滿 → draft markdown PRD。

結構（fixed order，per org's PRD Guideline 15 章）：

```
1. Overview & Context
2. Goals / Non-Goals / Constraints
3. User Stories & Personas
4. Functional Requirements
5. Non-Functional Requirements
6. System Architecture（Context / Container / Data Flow Diagrams）
7. Data Model
8. API Contract
9. Security & Privacy
10. Observability
11. Risks & Mitigations
12. Rollout & Migration Plan
13. Test Strategy
14. Open Questions
15. Appendix（含 POC Deviation 段）
```

**§13 Test Strategy 依執行模式分形**（Phase 1 鎖定的）：
- **人跑** → 一般測試策略（測試層級 / 覆蓋率 / 驗收方式）。
- **agent 無人值守跑** → §13 額外承載**無人值守執行紀律**：每條 AC 機器可檢核（silent cap 明講）、兩層閘（floor + ceiling）、原因碼迭代、紅綠燈通知（🟢🟡🔴 + pre-flight 測通才開跑）、3 出口（`NEEDS_INPUT`/`ESCALATE`/`REFUSE`）+ delta 防空轉、授權邊界 + stop-and-ask、可重現（recipe + run log）。這層紀律的**正典在 `goal-engineer/references/loop-run-protocol.md`**（內容無關、跨 skill 共用）;prd-create 內化同一份 checklist 進 §13、與其同步（per「algorithm 內化未 vendor」原則）。human-run 不帶這層。

POC scope simplification：
- 章末附 §15 Deviation 段，明列偏離 Guideline 的點 + 理由（如「§3.4 量化 NFR：POC 不適用 SLO 99.9%，改方向性敘述」）
- 仍套 15 章結構，但每章內容 pragmatic 簡化

中文化 apply（caller 受眾紀律）：
- Headings 中譯（FR → 功能需求；NFR → 非功能需求 等）
- Body inline 詞彙（stateless → 無狀態；endpoint → 端點）
- Code / 變數名 / API path / 框架名（WinForm / DirectShow / ONNX）保留原文

**PRD 內禁寫具體檔案路徑與 code snippet**（實作一動就過期、變成誤導；範圍描述用模組 / 元件名，不用 `src/...` 路徑）。唯一例外：schema / 狀態機 / type shape 這類**以片段編碼決策**、比文字更精準的內容 — 修剪到只剩決策相關部分並註明出處。

寫 draft path 由 caller 指定，建議 `drafts/<feature>_prd.md` 或 `<feature>/PRD.md`。

寫完告知 user：「v0.1 draft 寫到 `<path>`，待 stakeholder review」。

### Phase 5: Stakeholder merge loop

User 把 PRD 給 implementer / cross-team review；對方可能：
- 直接 edit 同檔案回傳（user 拿 diff 來給 Claude）
- 給回信 / 段落附註
- LINE 口頭補充

Claude 處理 merge：
- **Fact 補充**：直接 sync 進 PRD（如 implementer survey 結果、新規格）
- **答案 Q&A**：sync 進 §14 Open Questions table（標 ✅ + 答案來源）
- **衝突**（如 implementer 答案 vs PRD §2 Constraint 矛盾）：**surface 給 user 拍板**，**不擅自 merge**
  - 衝突 surface 範例：「Implementer survey 結果建議升級 hardware 規格 → 跟 PRD §2 Constraint 『使用既有 hardware 不採購』矛盾。三種可能：(a) implementer 試過既有不行 / (b) survey 是 production spec 寫錯位置 / (c) implementer 不知道 constraint。需 user 拍板」

User 拍板後 update PRD，bump version v0.1 → v0.2。重複 stakeholder loop 直到 user 滿意。

### Phase 6: Lock v1.0 + sanitize + publish ADO Wiki

User 喊「lock v1.0」/「鎖版」/「上 wiki」時走這條。

**Step 6a. Sanitize per ADO publication contract**

讀 caller's ADO publication contract；缺則直接用下列標準砍 8 條（本 skill 內建 fallback，無外部檔）：

1. 個人真名（PRD author / implementer / cross-team stakeholder 抽象化，砍真名 / email）
2. 日期 / 排查紀錄 / Sprint N / PBI #N（內部 ADO ref）
3. 內部組織 reference（新事業部 / Sprint planning）
4. memo / 自我反思 wording（待 confirm / 推測 / 我之前 / surface）
5. 同 wiki broken cross-link
6. 內部 repo 路徑（drafts/ / ~/dev/<repo>/ / .env.local）
7. 情緒色 / 主觀 wording
8. 狀態進度 wording（N/M 已掃 / 漏網 / 補掃）

保留：
- 純技術 fact / 結構化 finding / mitigation table
- 中性架構描述
- markdown 結構（headings / table / code block）
- P0 / P1 / P2 / P3 風險等級

**Step 6b. Resolve target wiki location**

User 給 wiki path（如 `/YourOrgWiki/TeamWork/<feature>/PRD`）。若 parent page 不存在，先 create parent。

**Step 6c. Publish via az CLI**

```bash
# 若 parent page 不存在
az devops wiki page create \
  --wiki <wiki-id> \
  --path "<parent-path>" \
  --content "<parent-summary>" \
  --org "$AZDO_ORG_URL" \
  --project "$AZDO_PROJECT"

# Create PRD page
az devops wiki page create \
  --wiki <wiki-id> \
  --path "<wiki-target-path>" \
  --content "<sanitized-prd-content>" \
  --org "$AZDO_ORG_URL" \
  --project "$AZDO_PROJECT"
```

**Step 6d. Verify + 印 summary**

```
PRD published:
  - Working draft: <caller-path>/PRD.md (v1.0)
  - ADO Wiki: <AZDO_ORG_URL>/<project>/_wiki/wikis/<wiki-id>?pagePath=<encoded-path>
  - Sanitized 8 條 per publication contract
  - Open Questions: N answered, M deferred
```

## Templates

| 檔 | 用途 |
|---|---|
| `templates/prd_full_guideline.md` | 15-章 skeleton（generic，無客戶 / 公司特化）|
| `templates/prd_poc_simplified.md` | POC 用 + §15 Deviation 段範例 |
| `fixtures/example_prd_smart_light_iot.md` | Mode β 精簡 fixture（辦公室智慧電燈 IoT POC）— illustrate POC PRD 怎麼寫 |

Caller 不確定怎麼寫某章節時，可貼 fixture 對應段給 Claude 對照。

## Anti-patterns

- ❌ **Fabricate missing info** — Raw input 沒提的事不要硬填，列為 question quiz user
- ❌ **對已凍結的 spec 重跑整份 PRD 訪談** — 已核可 ADR / 鎖版 PRD 只差無人值守包裝 → 導去 goal-engineer 的 lean build dispatch，不是重新 quiz §1-§15
- ❌ **Skip First-Principles check** — Problem / Goal / Non-Goal / Constraints 任一缺即停下對齊，不先寫架構
- ❌ **Auto-merge stakeholder feedback with conflicts** — implementer 答案跟 Constraint 矛盾要 surface user 拍板，不擅自選邊
- ❌ **Batch quiz** — 一口氣丟所有 §1-§15 questions，認知負擔太大；用 numbered list iterate
- ❌ **Quiz facts** — 能自查的事上桌問 caller（fact 自查、decision 才 quiz）
- ❌ **PRD 內嵌具體路徑 / code snippet** — 很快過期；例外只有編碼決策的 schema / 狀態機 / type shape 片段（修剪 + 註出處）
- ❌ **Skip §15 Deviation for POC** — POC 簡化版必須在 §15 Appendix 標明偏離 Guideline 的點 + 理由
- ❌ **Sanitize during draft phase** — Sanitization 只在 Phase 6 publish 前做；draft 期間用真實 context（caller 自家 repo 是 source of truth，sanitized 版只是 published copy）
- ❌ **Sanitize-then-edit-in-wiki** — Wiki 是 published copy，single-direction publish；要改 source（caller's PRD.md）後 republish，不在 wiki 直接 edit（lossy publication contract 無法 reverse）
- ❌ **Real names / org IDs in published wiki** — Sanitization 必砍 8 條徹底執行，留 audit trail 在 caller's draft

## Common pitfalls

| 陷阱 | 對策 |
|---|---|
| User 一次給太多 raw input 一口氣消化 | 識別最 critical 章節（§1 + §2 + §11）先 quiz，其他章節 deferred |
| First-Principles 缺 Constraints 但 user 急著走 §6 架構 | 拒走 §6，回到 §2 拍板 Constraints |
| Implementer review 直接改 caller's draft（不走 Q&A loop）| Diff caller's draft 識別變動，分類 fact / 答案 / 衝突 |
| POC 寫法 vs Production 寫法混用 | Phase 1 對齊 caller 是 POC 還是 Production scope，後續一致套用 |
| ADO Wiki sanitize 後幾乎全砍 | 預期行為 — 公開化 contract 是 lossy transform，sanitized 版必然薄；caller's draft 是 source of truth |
| Wiki page parent 不存在 | Phase 6b 先 create parent；az 不會 auto-create ancestor |
| 中文化過頭把 industry term 譯成生造詞 | 保留 JWT / OAuth / API / token / WinForm / ONNX / mp4 等 industry-standard term |

## 跟其他 skill 的關係

- **`grill`（同 repo）**：Phase 3 quiz loop 的問法紀律（附建議答案、fact 自查 decision 才問）正典在它那；prd-create 管章節結構與優先序
- **`prd-breakdown`（同 repo）**：拿 prd-create 產出的 PRD.md → 拆 vertical slice → push ADO tasks。Chain：`prd-create` → `prd-breakdown` → ADO
- **`spec` skill（同 repo）**：caller 自家開發 spec workflow（spec.md / plan.md / tasks.md / report.md）。`prd-create` 產出 PRD 作 input；`spec` 是「caller 自身 codebase 開發 spec」不是「產品需求 PRD」
- **`goal-engineer`（同 repo）**：當 PRD 要交 agent 無人值守跑，§13 的執行紀律對齊它的 `references/loop-run-protocol.md`（同一份正典）。分工：prd-create 寫「build 什麼」、loop-run-protocol 寫「agent 怎麼無人值守跑 + 回報」。goal-engineer 主體是 generate-and-select dispatch；另收一個窄例外 — **已凍結的 build spec 只差無人值守包裝**時，出 lean build dispatch（其 Frozen Spec Check 把關）。判準：spec 還要被**寫出來** → 本 skill；spec 已鎖版（含本 skill 產的 v1.0 PRD 事後要改交 agent 跑）→ goal-engineer lean build dispatch，不必回頭重寫 PRD
- 這些 skill 透過 markdown 文件對接，不互相 import

## Important rules

收尾 invariants — 即使前面 step 都讀過，這幾條是核心：

1. **Quiz before fabricate** — 不確定的事一律列為 question 給 user，不擅自 hard-code
2. **First-Principles gate** — Problem / Goal / Non-Goal / Constraints 缺一即停下對齊，不先寫架構
3. **Surface conflicts, don't auto-merge** — implementer review 跟 Constraint 衝突要 surface user，不擅自選邊
4. **Caller's draft is source of truth** — Wiki 是 published copy，single-direction；改要在 caller's draft 後 republish
5. **Sanitization is lossy by design** — 必砍 8 條徹底執行，sanitized 版必然比 source 薄
6. **PAT via env var only** — `AZURE_DEVOPS_EXT_PAT` 環境變數，永不上 argv
7. **POC must have §15 Deviation** — POC 簡化版必須標明偏離 Guideline 的點 + 理由
8. **No Python wrapper** — Claude 透過 Bash 直接 `az`；不寫 / 不召喚 Python helper script
9. **Industry term retain English** — JWT / OAuth / API / token / WinForm / ONNX / mp4 等不譯
10. **Public repo discipline** — 此 skill repo 為 public；fixtures 用 placeholders（無真名 / 真客戶 / 真政治 context）
11. **執行模式分形** — Phase 1 先鎖定「人跑 / agent 跑」，缺則 quiz 不預設；agent-run PRD 的 §13 要帶無人值守執行紀律（對齊 `goal-engineer/references/loop-run-protocol.md`），human-run 不帶
12. **凍結規格不重寫** — input 已是凍結 build spec、只差無人值守包裝 → 導去 goal-engineer lean build dispatch，本 skill 只在「spec 還需要被寫出來」時進場

## Acknowledgments

Algorithm 內化（重寫成 prompt，未 vendor）：

- **Caller's PRD authoring Guideline** (caller-supplied) — 15 章結構 + First-Principles 啟動 + POC Deviation pattern
- **caller's `doc_writing.md` 紀律** (caller-supplied) — PRD 撰寫紀律 + 受眾中文化
- **caller's `ado.md` 紀律** (caller-supplied) — 公開化 contract 必砍 8 條 + ADO Wiki 同步工作流
- **Real-world PRD authoring experience** (internal) — Quiz loop / Stakeholder merge / Sanitize-publish pattern 從實戰提煉

Mode β fixture (`example_prd_smart_light_iot.md`) 案例為 generic 辦公室智慧電燈 IoT POC，無 IP 爭議，跟既有 PRD 結構 parallel illustrate。