Requirements Clarification Skill

Purpose

STOP implementing before fully understanding requirements.

Prevent the common problem:

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

Solution: Force clarification BEFORE any code is written.

Auto-Activation

Triggers when user mentions:

✅ "需求", "requirement", "客戶要", "案主說"
✅ "新功能", "用戶想要", "想加一個"
✅ "客戶反饋", "需要改成", "應該要"

CARIO Clarification Framework

Structured format for requirements clarification:

📋 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?

Mandatory Workflow

Step 1: STOP and Analyze

When user provides requirements, DO NOT implement immediately.

Instead:

Read the requirement carefully
Identify ALL ambiguities
List ALL assumptions
Generate clarifying questions

Step 2: Use CARIO Format

Example:

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

Step 3: Get User Confirmation

Use AskUserQuestion tool:

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

Step 4: Document Understanding

Create a mini-spec:

## 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

Step 5: Only THEN Start TDD

After confirmation, activate tdd-workflow:

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

Common Ambiguity Patterns

Pattern 1: Vague Verbs

❌ Ambiguous:

"處理客戶" (handle clients)
"管理資料" (manage data)
"改進效能" (improve performance)

✅ Clarify:

What action? (Create? Update? Delete? Search?)
What data? (Which fields?)
How much improvement? (What metric? Target?)

Pattern 2: Missing Details

❌ Incomplete:

"加一個報告" (add a report)

✅ Clarify:

What data in report?
What format? (PDF? Excel? HTML?)
Who can access?
How to generate? (On-demand? Scheduled?)

Pattern 3: Assumed Context

❌ Assumption:

"客戶說要改成這樣" (client wants it changed)

✅ Clarify:

Changed from what state?
Changed to what state?
Why the change?
What stays the same?

Clarification Questions Checklist

Before implementing ANY feature, answer:

Functional Questions

What exactly should it do?
What should it NOT do?
What are edge cases?
What happens on error?

Data Questions

What data is needed?
Where does data come from?
What's the data format?
What are validation rules?

Integration Questions

What other features are affected?
What APIs are involved?
What database changes needed?
What tests are required?

User Experience Questions

Who uses this feature?
When do they use it?
How do they trigger it?
What feedback do they get?

Integration with Other Skills

Works with tdd-workflow

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

Works with api-development

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

Real Example: Before and After

❌ Before (No Clarification)

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

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

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

✅ After (With Clarification)

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: ✅ 一次做對，客戶滿意

Anti-Patterns to Avoid

❌ Assuming Without Asking

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

❌ Implementing Multiple Interpretations

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

❌ Asking Too Many Questions

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

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

Success Metrics

Before This Skill

⏱️ 需求理解錯誤率：40%
⏱️ 重做時間：平均 2 小時/功能
😤 客戶滿意度：中等

After This Skill

✅ 需求理解錯誤率：<5%
✅ 重做時間：幾乎沒有
😊 客戶滿意度：高

Time Investment:

Clarification: +10 minutes
Saved rework: -2 hours
Net benefit: +1h 50m per feature

Quick Start Template

Copy this whenever receiving requirements:

## 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.

Related Skills

tdd-workflow: Implement after clarification
api-development: API contract definition
prd-workflow: Document requirements formally

Skill Version: v1.0 Last Updated: 2025-12-25 Project: career_ios_backend Philosophy: "Measure twice, cut once" - 先搞清楚再動手