客戶需求 → Agent 理解不完整 → 實作偏差 → 浪費時間重做

📋 Context (背景)
   - What are we working on?
   - What's the current state?

❓ Ambiguity (不清楚的地方)
   - What's unclear or ambiguous?
   - What assumptions are we making?

🎯 Options (可能的理解)
   - Option A: [interpretation 1]
   - Option B: [interpretation 2]
   - Option C: [interpretation 3]

💡 Recommendation (建議)
   - Recommended approach and why
   - Trade-offs of this choice

⚡ Impact (影響範圍)
   - What components are affected?
   - What tests are needed?
   - Estimated complexity?

User: "客戶說要加一個搜尋功能"

📋 Context
- Working on: career_ios_backend client management
- Current state: Clients can only be listed, no search

❓ Ambiguity
1. 搜尋什麼？(Search by what?)
   - Client name?
   - Client code?
   - Email?
   - All fields?

2. 搜尋方式？(Search type?)
   - Exact match?
   - Partial match?
   - Fuzzy search?

3. 搜尋結果？(Results?)
   - Paginated?
   - How many per page?
   - Sorting?

🎯 Options

Option A: Simple name search (exact match)
- Fastest to implement
- Limited functionality
- Good for MVP

Option B: Multi-field search (partial match)
- Name, email, code searchable
- More flexible
- Moderate complexity

Option C: Full-text search (fuzzy)
- Search all fields
- Most powerful
- Requires additional setup

💡 Recommendation
Start with Option B (multi-field partial match):
- Balances power and simplicity
- Covers 80% of use cases
- Can upgrade to Option C later if needed

⚡ Impact
Affected:
- app/api/clients.py (add search endpoint)
- app/schemas/client.py (add search request schema)
- tests/integration/test_clients_api.py (add search tests)

Complexity: 🟡 Medium (2-3 hours)
Tests needed: 3-5 integration tests

AskUserQuestion(
    questions=[{
        "question": "客戶搜尋功能應該搜尋哪些欄位？",
        "header": "Search Fields",
        "multiSelect": True,
        "options": [
            {
                "label": "姓名 (Name)",
                "description": "搜尋客戶姓名"
            },
            {
                "label": "Email",
                "description": "搜尋 Email 地址"
            },
            {
                "label": "客戶代碼 (Code)",
                "description": "搜尋客戶代碼"
            },
            {
                "label": "全部欄位 (All)",
                "description": "搜尋所有文字欄位"
            }
        ]
    }]
)

## Feature: Client Search

### User Story
As a counselor, I want to search for clients by name/email/code,
so that I can quickly find the client I need.

### Acceptance Criteria
- [ ] Can search by client name (partial match)
- [ ] Can search by email (partial match)
- [ ] Can search by client code (exact match)
- [ ] Returns paginated results (10 per page)
- [ ] Case-insensitive search

### API Design
GET /api/v1/clients/search?q={query}&page={page}

Response:
{
  "items": [...],
  "total": 42,
  "page": 1,
  "pages": 5
}

### Tests Required
1. test_search_by_name_success
2. test_search_by_email_success
3. test_search_by_code_success
4. test_search_case_insensitive
5. test_search_pagination

✅ Requirements clear
✅ User confirmed understanding
✅ Acceptance criteria defined
→ NOW safe to write tests and implement

1. requirements-clarification (THIS SKILL)
   - Clarify requirements
   - Get user confirmation
   - Document understanding
   ↓
2. tdd-workflow
   - Write tests based on acceptance criteria
   - Implement to pass tests
   - Refactor

requirements-clarification
   → Define API contract
   → Clarify request/response format
   ↓
api-development
   → Implement FastAPI endpoint
   → Follow defined contract

User: "客戶說要能匯出報告"

Agent: (直接實作)
- Creates PDF export
- Only exports basic info
- No customization

Result: ❌ 客戶要的是 Excel，要自訂欄位
        → 浪費 2 小時重做

User: "客戶說要能匯出報告"

Agent: (啟動 requirements-clarification skill)

📋 Context: 諮詢報告匯出功能

❓ Ambiguity:
1. 匯出格式？PDF? Excel? 都要？
2. 匯出內容？哪些欄位？
3. 匯出時機？手動？自動？
4. 客製化？能選擇欄位嗎？

🎯 Options:
A. PDF only (fixed format)
B. Excel only (customizable)
C. Both formats

💡 Recommendation: Option B (Excel)
- 客戶通常要進一步分析
- Excel 更靈活
- 可自訂欄位

⚡ Impact: Medium complexity

(Gets user confirmation)

User: "對，要 Excel，而且要能選擇哪些欄位"

Agent: ✅ 明確了！現在用 TDD 開發...

Result: ✅ 一次做對，客戶滿意

# Bad
user_input = "加一個搜尋"
# → 直接假設是全文搜尋，實作後才發現要的是簡單篩選

# Bad
"不確定要哪個，所以全部都做"
# → 浪費時間，可能都不是客戶要的

# Bad
"有 20 個問題要問你..."
# → 用戶厭煩，寧願給模糊需求

# Good
"有 3 個關鍵問題，澄清後就能開始："
# → 聚焦核心，快速決策

## Requirement Clarification

User Request: "[用戶原話]"

📋 Context:
-

❓ Ambiguity:
1.
2.
3.

🎯 Options:
A.
B.
C.

💡 Recommendation:
-

⚡ Impact:
- Files affected:
- Tests needed:
- Complexity:

---

Questions for user:
1.
2.
3.