# Problem Definition: /feat Codegen Implementation Priority

## Metadata

- **Date**: 2025-10-14
- **Author**: Kent (via Claude Code Socratic Inquiry)
- **Git Commit**: 5c35b7b70b49008fa6dec991c80e8faf8e642bb7
- **Branch**: main
- **Problem ID**: feat-codegen
- **Tags**: #feature-priority #demo-prep #decision-making #risk-mitigation
- **Status**: Defined
- **Method**: Socratic Inquiry (v4.0.3)

---

## 🎯 Problem Statement

**真正的問題不是「不知道怎麼實作」，而是「擔心做錯方向浪費時間」。**

在半個月 Demo 的時間壓力下，開發者知道技術上如何實作 `/feat` 功能（參考 ai_brain.py 模式），但缺乏信心確認這是正確的優先順序，擔心投入 4-5 天開發後發現：
- 主管不認同這個優先順序
- 做出來後發現不是產品差異化
- 或者應該先做 `/chat` 或 `/SDD`

這是典型的**決策焦慮**而非技術困難。

---

## 🔍 Discovery Process

### 初始描述
「不知道接下來做哪個功能比較有價值，因為不久後需要 Demo。」

### 關鍵洞察與轉折點

1. **第一層表象**：「想知道做哪個功能最有價值」
   - 挑戰：價值對誰？基於什麼標準？
   - 發現：a) 對用戶有用 + b) 產品看起來完整

2. **第二層深入**：「有其他韌體工程師作為潛在用戶」
   - 挑戰：有跟用戶聊過嗎？
   - 發現：這是新產品，基於市調需求（週期長、門檻高、過程煩雜）

3. **第三層轉折**：「半個月後 Demo 給內部主管」
   - 挑戰：為什麼糾結功能選擇？
   - 發現：主管會問「接下來做什麼」，需要有說服力的答案

4. **第四層真相**：「其實我自己也不確定哪個功能更重要」
   - 候選功能：/feat（AI 協助新功能開發）vs /chat（通用對話）
   - 困擾：不知道互動設計（直接式 vs 對話式 vs 規格驅動）

5. **第五層矛盾**：「產品方向已規劃好，但不知道如何進行會比較好」
   - 發現：是軟體工程師，不熟悉韌體工程師習慣
   - 完整流程設想：research → plan → implement → verify（15-25 天）
   - 簡化流程：feat → codegen → build → flash（4-5 天）

6. **核心突破**：「為什麼覺得『AI 協助開發新功能』比『AI 自動修復』更酷？」
   - 主管問的是「差異化在哪」
   - 挑戰：AI 寫新功能跟 Cursor/Copilot 有何差異？
   - 發現：真正差異化在「自動修復 + 閉環」，而非「AI 寫代碼」

7. **最終真相**：「不知道從哪裡開始實作」
   - 魔鬼代言人挑戰：是否其實知道怎麼做，只是缺信心？
   - 確認：**是的，知道怎麼做（參考 ai_brain.py），但擔心做錯方向**

### 信心歷程

- **初始信心**: 3/10（完全不確定要做什麼）
- **釐清目標後**: 5/10（知道候選功能，但不確定選哪個）
- **簡化方案後**: 7/10（技術可行，但擔心方向）
- **魔鬼代言人後**: 9/10（確認真正問題是決策焦慮）

### 魔鬼代言人挑戰記錄

**挑戰 1 - 解決方案偽裝成需求**：
- 「AI 賦能韌體開發」是解決方案還是需求？
- 發現：用戶抱怨「過程煩雜、重複性工作多」才是真需求

**挑戰 2 - 差異化質疑**：
- 「AI 寫新功能」vs「AI 自動修復」哪個更獨特？
- 發現：自動修復閉環才是真正差異化

**挑戰 3 - 時間現實檢查**：
- 完整流程（7 步驟）vs 簡化流程（3 步驟），半個月做得完嗎？
- 發現：只能做簡化版（codegen → build → flash）

**挑戰 4 - 價值挑戰**：
- 簡化版 /feat 跟「Cursor 寫代碼 + fwauto build」有何差異？
- 發現：差異在「自動接回修復閉環」

**挑戰 5 - 證據追問**：
- 「擔心 AI 質量」是測試過還是假設？
- 發現：沒測試過，只是擔心

**挑戰 6 - 行動阻礙**：
- 為什麼為「未驗證的擔憂」猶豫，而不先測試？
- 發現：認為需要 fwauto 功能才能測試（思維盲點）

**挑戰 7 - 最終挑戰**：
- 如果你其實知道怎麼做，只是缺信心，證據會有什麼不同？
- 確認：**是的，真正問題是擔心做錯方向**

### 5 Whys 追蹤

1. **為什麼不知道做哪個功能？**
   → 因為有多個候選功能在競爭

2. **為什麼有多個候選功能？**
   → 因為產品規劃有 /feat、/chat、/SDD 等多種模式

3. **為什麼要在半個月內決定？**
   → 因為要 Demo，主管會問「接下來做什麼」

4. **為什麼擔心主管的問題？**
   → 因為自己也不確定優先順序是否正確

5. **為什麼不確定優先順序？**
   → 因為不熟悉目標用戶（韌體工程師）的習慣，擔心做錯方向浪費時間

---

## ✨ Real Requirement

### 真實需求（不是解決方案）

**需求**: 在時間壓力下，需要確認技術方向的正確性，降低決策風險

**不是**:
- ❌ 不知道怎麼實作（技術問題）
- ❌ 需要別人幫忙寫代碼（執行問題）
- ❌ 不知道產品要做什麼（規劃問題）

**而是**:
- ✅ 需要驗證「先做 /feat」是正確的優先順序
- ✅ 需要清晰的理由說服自己和主管
- ✅ 需要降低「做錯方向」的心理風險

### 解決方案 vs 真實需求對比

| 表面請求 | 真實需求 |
|---------|---------|
| 「告訴我做哪個功能」 | 「驗證我的判斷是對的」 |
| 「教我怎麼實作」 | 「給我信心和理由」 |
| 「哪個功能最有價值」 | 「降低決策風險」 |

---

## 📊 Success Criteria

### 可衡量的成功標準

1. **技術交付**:
   - ✅ 半個月內完成可 Demo 的 `/feat` 簡化版
   - ✅ 功能包含：codegen → build → 自動修復閉環 → flash
   - ✅ 至少一個成功案例（如：蜂鳴器功能）

2. **Demo 準備**:
   - ✅ 能清楚說明「為什麼先做 /feat」的理由
   - ✅ 能回答主管「跟 Copilot 有何差異」→ 答：自動接回修復閉環
   - ✅ 準備好「接下來做什麼」的答案

3. **風險控制**:
   - ✅ 技術方向清晰，不走冤枉路
   - ✅ 時間預估準確（4-5 天開發 + 2-3 天測試優化）
   - ✅ 有 Plan B（如果做不完，如何展示部分進度）

### 驗收方式

**最小成功標準**：
```bash
fwauto feat "加入蜂鳴器，發出 3 秒長音後 1 秒斷音"
# → AI 生成代碼
# → 自動編譯（可能失敗）
# → AI 自動修復
# → 自動重新編譯（成功）
# → 自動燒錄
# → 完成
```

**Demo 腳本**：
1. 展示現有「AI 自動修復編譯錯誤」（差異化核心）
2. 展示新功能「AI 協助開發新功能」（產品完整性）
3. 說明：兩者整合 = 完整的 AI 輔助閉環

---

## 🌍 Context & Impact

### 影響範圍
- **直接影響**: 半個月內的開發優先順序
- **間接影響**: 產品路線圖的可信度、團隊信心

### 時間壓力
- **Demo 時間**: 半個月後
- **開發時間**: 約 10 個工作天
- **實際可用**: 4-5 天開發 + 2-3 天測試 + 2 天 buffer

### 利害關係人
- **主管**: 評估進度、決定資源投入
- **開發者（自己）**: 需要信心和清晰方向
- **潛在用戶**: 韌體工程師（但現階段不直接參與）

### 問題嚴重程度
- **技術風險**: 中等（AI 質量未驗證，但有自動修復兜底）
- **時間風險**: 高（時間緊迫，容錯空間小）
- **方向風險**: 中等（擔心主管不認同優先順序）

---

## 🔐 Assumptions & Constraints

### 關鍵假設

1. **技術假設**:
   - ✅ 參考 ai_brain.py 的模式可以快速實作 feat_codegen node
   - ⚠️ AI 生成韌體代碼的質量可接受（**未驗證**）
   - ✅ 自動修復閉環可以兜底（已驗證，regression test 有數據）

2. **產品假設**:
   - ✅ /feat 是規劃好的必做功能
   - ⚠️ 「AI 協助新功能開發」是重要里程碑（主管視角未確認）
   - ⚠️ 差異化在「閉環」而非「AI 寫代碼」（需要 Demo 時強調）

3. **用戶假設**:
   - ⚠️ 韌體工程師需要這個功能（基於市調，未直接驗證）
   - ⚠️ 直接式 /feat 比對話式 /chat 更適合（未驗證）

### 技術約束
- **時間**: 半個月（10 工作天）
- **人力**: 單人開發
- **環境**: Windows 11 + Keil + STM32

### 業務約束
- **Demo 對象**: 內部主管（技術理解程度中等）
- **目標**: 展示進度 + 說明接下來方向
- **壓力**: 主管會問「差異化」「接下來做什麼」

---

## 📦 Scope & Boundaries

### In Scope（半個月內要做的）

1. **核心功能**:
   - ✅ 實作 `nodes/feat_codegen.py`
   - ✅ 新增 `prompts/feat_codegen.md`
   - ✅ 更新 State 結構（加入 `feat_description`）
   - ✅ 更新 graph routing（feat_codegen → build → ai_brain → ...）
   - ✅ CLI 整合 `fwauto feat <description>`

2. **測試與優化**:
   - ✅ 至少一個成功案例（蜂鳴器）
   - ✅ 整合測試（確保不破壞現有功能）
   - ⚠️ AI 質量驗證（快速測試，不求完美）

3. **Demo 準備**:
   - ✅ 準備 Demo 腳本
   - ✅ 準備應答話術（差異化、接下來計畫）

### Out of Scope（暫時不做的）

1. **複雜流程**:
   - ❌ Research node（分析現有代碼）
   - ❌ Plan generation + user confirmation（生成計劃、等待確認）
   - ❌ AI verification（分析日誌驗證結果）
   - ❌ 多輪迭代閉環（失敗重試做新功能）

2. **其他互動模式**:
   - ❌ `/chat` 對話式
   - ❌ `/SDD` 規格驅動式

3. **完美主義**:
   - ❌ 100% AI 質量保證
   - ❌ 支援所有韌體功能類型
   - ❌ 完整的錯誤處理和 edge cases

### Edge Cases（已識別但暫不處理）
- AI 生成的代碼無法通過自動修復（Demo 時避開）
- 複雜的硬體配置需求（先做簡單案例）
- 用戶需求描述不清楚（Demo 時用精心準備的案例）

---

## 🚀 Next Steps

### 建議行動順序

#### Phase 1: 快速驗證（0.5 天）
1. **測試 AI 質量**（降低擔憂）:
   ```python
   # 簡單測試 Claude Code SDK 生成韌體代碼
   # 用蜂鳴器案例測試
   ```

2. **確認技術可行性**（增強信心）:
   - 檢視 ai_brain.py 實作
   - 草擬 feat_codegen.py 架構

#### Phase 2: 核心實作（3-4 天）
1. **Day 1-2**: 實作 feat_codegen node
   - `nodes/feat_codegen.py`
   - `prompts/feat_codegen.md`
   - State 擴展

2. **Day 3**: 整合 graph routing
   - 更新 `graph.py`
   - CLI 整合

3. **Day 4**: 初步測試
   - 蜂鳴器案例
   - 修復明顯 bugs

#### Phase 3: 優化與 Demo 準備（2-3 天）
1. **Day 5-6**: 測試與優化
   - 整合測試
   - Prompt 調整
   - 成功率驗證

2. **Day 7**: Demo 準備
   - 腳本撰寫
   - 話術準備
   - Plan B 預案

#### Phase 4: Buffer（2 天）
- 處理意外問題
- 最後調整

### 決策建議

**為什麼先做 /feat？**
1. ✅ 這是規劃好的必做功能（非臨時起意）
2. ✅ 技術上可行且時間充足（4-5 天 < 10 天）
3. ✅ 展示產品完整性（不只修復，還能開發）
4. ✅ 差異化在「接回自動修復閉環」（不只是 AI 寫代碼）
5. ✅ 簡化版已經有價值（不需要完整 research-plan-verify）

**如何回答主管「差異化」？**
- "市面上 Copilot/Cursor 能幫寫代碼，但寫完還是要手動編譯、手動改錯。"
- "我們的差異化是：AI 寫完 → 自動編譯 → 失敗自動修復 → 再編譯 → 自動燒錄，完整閉環。"
- "這需要深度整合 Keil + LangGraph + 韌體專業知識，別人做不到。"

**如何回答主管「接下來做什麼」？**
- "短期：優化 /feat 質量，加入更多韌體功能支援（UART、Timer、ADC...）"
- "中期：擴展到 /chat 對話式互動，讓 AI 能引導需求釐清"
- "長期：加入 research → plan → verify 完整流程，實現規格驅動開發"

### 風險緩解

**風險 1**: AI 質量不好
- **緩解**: Phase 1 快速測試，及早發現
- **Plan B**: Demo 用精心準備的案例，不現場執行

**風險 2**: 時間不夠
- **緩解**: 嚴格控制 scope，只做簡化版
- **Plan B**: 展示部分功能 + 說明完整願景

**風險 3**: 主管質疑優先順序
- **緩解**: 準備清晰的差異化說明
- **Plan B**: 強調這是「驗證技術可行性」的里程碑

---

## 💭 Reflection

### 信心程度
**9/10** - 對問題理解有高度信心

### 開放問題

1. **AI 質量**（重要性：高）:
   - Claude 生成 STM32 代碼的實際質量如何？
   - 建議：Phase 1 快速測試驗證

2. **主管期待**（重要性：中）:
   - 主管心中的「差異化」定義是什麼？
   - 建議：Demo 前可以非正式確認

3. **用戶習慣**（重要性：低）:
   - 韌體工程師真的偏好直接式 /feat 嗎？
   - 建議：做出來後再收集反饋，現階段不用糾結

### 診斷者備註

這是一個典型的「決策焦慮偽裝成技術問題」的案例。開發者實際上：
- ✅ 有技術能力（知道怎麼做）
- ✅ 有時間資源（4-5 天 < 10 天）
- ✅ 有清晰目標（/feat 是必做功能）

但因為：
- ⚠️ 時間壓力（半個月 Demo）
- ⚠️ 資訊不對稱（不熟悉韌體工程師習慣）
- ⚠️ 決策責任（擔心主管質疑）

導致產生「不知道做什麼」的焦慮感。

**真正需要的不是技術指導，而是決策驗證和信心支持。**

---

## 📚 References

- 現有文件: `/home/kent/dev/playground/fwauto/docs/integration-flow.md`
- 技術參考: `src/fwauto/nodes/ai_brain.py`
- 測試參考: `tests/integration/test_ai_regression.py`
- 專案狀態: 60% 完成度（build, flash, AI 修復, log 分析已完成）

---

## 📝 Change Log

- 2025-10-14: 初始版本（透過 27 輪蘇格拉底式對話完成診斷）
