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" - 先搞清楚再動手