requirement-assistant

Original source / Raw SKILL.md

---
name: requirement-assistant
description: |
  Guide requirement writing, user story creation, and feature specification.
  Use when: writing requirements, user stories, issues, feature planning.
  Keywords: requirement, user story, issue, feature, specification, 需求, 功能規劃, 規格.
---

# Requirement Assistant

This skill provides guidance on writing clear, complete, and actionable requirements.

## Quick Reference

### User Story Format (INVEST)

```
As a [role],
I want [feature],
So that [benefit].
```

### INVEST Criteria

| Criterion | Description | Question to Ask |
|-----------|-------------|-----------------|
| **I**ndependent | Can be delivered alone | Does this depend on other stories? |
| **N**egotiable | Details can be discussed | Is this too prescriptive? |
| **V**aluable | Provides user value | What problem does this solve? |
| **E**stimable | Can estimate effort | Do we understand the scope? |
| **S**mall | Fits in one sprint | Can we break this down? |
| **T**estable | Has clear acceptance criteria | How do we know it's done? |

### Requirement Priority Levels

| Priority | Label | Description |
|----------|-------|-------------|
| P0 | Must Have | Critical for release |
| P1 | Should Have | Important but not blocking |
| P2 | Could Have | Nice to have |
| P3 | Won't Have | Out of scope (this release) |

## Detailed Guidelines

For complete standards, see:
- [Requirement Writing Guide](./requirement-writing.md)
- [Requirement Checklist](./requirement-checklist.md)

## Quick Templates

### Simple Issue Template

```markdown
## Problem
[What problem are we solving?]

## Proposed Solution
[How should we solve it?]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
```

### Feature Request Template

```markdown
## Summary
[One-line description]

## Motivation
[Why is this needed? Who benefits?]

## Detailed Description
[Full description of the feature]

## Acceptance Criteria
- [ ] [Measurable criterion 1]
- [ ] [Measurable criterion 2]

## Out of Scope
- [What this feature does NOT include]
```

### Bug Report Template

```markdown
## Description
[Brief description of the bug]

## Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment
- OS: [e.g., Windows 11]
- Version: [e.g., v1.2.3]
```

## Acceptance Criteria Guidelines

### Good Acceptance Criteria

- **Specific**: Clear, unambiguous
- **Measurable**: Can verify pass/fail
- **Achievable**: Technically feasible
- **Relevant**: Related to the requirement
- **Testable**: Can write a test for it

### Examples

**Good**:
```markdown
- [ ] User can upload files up to 10MB
- [ ] System responds within 500ms for 95th percentile
- [ ] Error message displays when upload fails
```

**Bad**:
```markdown
- [ ] System should be fast  # Not measurable
- [ ] Make it user-friendly  # Too vague
- [ ] Fix the bug            # No specific criteria
```

## Requirement Completeness Checklist

When writing requirements, ensure you cover:

- [ ] **What**: Clear description of the feature
- [ ] **Why**: Business value / problem solved
- [ ] **Who**: Target users / personas
- [ ] **When**: Priority / timeline
- [ ] **How**: High-level approach (if known)
- [ ] **Acceptance**: Criteria for completion
- [ ] **Scope**: What's NOT included

---

## Configuration Detection

This skill supports project-specific requirement templates.

### Detection Order

1. Check `CONTRIBUTING.md` for "Disabled Skills" section
   - If this skill is listed, it is disabled for this project
2. Check `CONTRIBUTING.md` for "Requirement Language" section
3. Check for `.github/ISSUE_TEMPLATE/` directory
4. Check for `docs/templates/` directory
5. If not found, **default to English** and use default templates

### First-Time Setup

If no templates found:

1. Ask the user: "This project doesn't have requirement templates. Which language should I use? (English / 中文)"
2. After user selection, suggest documenting in `CONTRIBUTING.md`:

```markdown
## Requirement Language

This project uses **[chosen option]** for requirements and issues.
<!-- Options: English | 中文 -->
```

3. Suggest appropriate template based on project type

### Configuration Example

In project's `CONTRIBUTING.md`:

```markdown
## Requirement Language

This project uses **English** for requirements and issues.
<!-- Options: English | 中文 -->

### Issue Templates Location
`.github/ISSUE_TEMPLATE/`
```

---

**License**: CC BY 4.0 | **Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### requirement-writing.md

```markdown
# Requirement Writing Guide
# 需求撰寫指南

## User Story Format | 使用者故事格式

### Standard Template | 標準範本

```
As a [user role],
I want [goal/feature],
So that [benefit/value].
```

### Examples | 範例

**Good**:
```
As a registered user,
I want to reset my password via email,
So that I can regain access to my account if I forget my password.
```

**Bad**:
```
Users should be able to reset passwords.
(Missing: who, why, acceptance criteria)
```

---

## INVEST Criteria | INVEST 原則

### I - Independent | 獨立性

- Story can be developed and delivered independently
- Minimal dependencies on other stories
- Can be prioritized and scheduled flexibly

**Test**: "Can we deliver this without finishing another story first?"

### N - Negotiable | 可協商性

- Details are not locked in stone
- Conversation starter, not a contract
- Implementation approach can be discussed

**Test**: "Is there room for technical discussion?"

### V - Valuable | 有價值性

- Delivers value to users or stakeholders
- Solves a real problem
- Contributes to business goals

**Test**: "What problem does this solve? Who benefits?"

### E - Estimable | 可估算性

- Team can estimate the effort
- Scope is understood well enough
- No major unknowns

**Test**: "Can we give a rough estimate?"

### S - Small | 小型化

- Can be completed in one sprint
- Typically 1-5 days of work
- If larger, break into smaller stories

**Test**: "Can we finish this in one sprint?"

### T - Testable | 可測試性

- Clear acceptance criteria
- Can write automated tests
- Definition of done is clear

**Test**: "How do we know this is done?"

---

## Acceptance Criteria | 驗收標準

### Format Options | 格式選項

#### Given-When-Then (BDD Style)

```gherkin
Given [precondition]
When [action]
Then [expected result]
```

**Example**:
```gherkin
Given I am on the login page
When I enter valid credentials and click login
Then I should be redirected to the dashboard
```

#### Checkbox Style

```markdown
- [ ] User can upload files up to 10MB
- [ ] Supported formats: JPG, PNG, PDF
- [ ] Upload progress is displayed
- [ ] Error message shown if upload fails
```

### Writing Good Acceptance Criteria | 撰寫好的驗收標準

| Quality | Good | Bad |
|---------|------|-----|
| **Specific** | "Error message displays within 2 seconds" | "Error handling works" |
| **Measurable** | "Response time < 500ms" | "System is fast" |
| **Testable** | "User sees confirmation modal" | "User experience is good" |
| **Complete** | Lists all scenarios | Missing edge cases |

### Checklist | 檢查清單

- [ ] All happy path scenarios covered
- [ ] Error scenarios defined
- [ ] Edge cases considered
- [ ] Performance criteria (if applicable)
- [ ] Security requirements (if applicable)
- [ ] Accessibility requirements (if applicable)

---

## Requirement Types | 需求類型

### Functional Requirements (FR) | 功能需求

**What the system should DO**

```markdown
### FR1: User Registration

**Description**: Users can create new accounts using email.

**Acceptance Criteria**:
- [ ] Email format validation
- [ ] Password strength requirements (min 8 chars, 1 uppercase, 1 number)
- [ ] Confirmation email sent
- [ ] Duplicate email prevention
```

### Non-Functional Requirements (NFR) | 非功能需求

**How the system should BEHAVE**

| Category | Example |
|----------|---------|
| **Performance** | Response time < 200ms for 95th percentile |
| **Scalability** | Support 10,000 concurrent users |
| **Security** | All data encrypted in transit (TLS 1.3) |
| **Availability** | 99.9% uptime |
| **Usability** | WCAG 2.1 AA compliance |

---

## Priority Frameworks | 優先級框架

### MoSCoW Method

| Priority | Meaning | Description |
|----------|---------|-------------|
| **M**ust Have | Critical | Release cannot proceed without |
| **S**hould Have | Important | High value but not blocking |
| **C**ould Have | Desirable | Nice to have, lower priority |
| **W**on't Have | Out of scope | Not this release |

### Numbered Priority (P0-P3)

| Level | Label | Description | Example |
|-------|-------|-------------|---------|
| P0 | Critical | Showstopper | Security vulnerability |
| P1 | High | Must fix soon | Core feature bug |
| P2 | Medium | Should fix | UX improvement |
| P3 | Low | Nice to have | Minor enhancement |

---

## Issue Templates | Issue 範本

### Feature Request | 功能需求

```markdown
## Summary
[One-line description of the feature]

## Motivation
### Problem Statement
[What problem does this solve?]

### User Impact
[Who is affected and how?]

## Detailed Description
[Full description of the requested feature]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Design Considerations
[Any technical considerations or constraints]

## Out of Scope
- [What this feature does NOT include]

## Priority
- [ ] P0 - Critical
- [ ] P1 - High
- [ ] P2 - Medium
- [ ] P3 - Low
```

### Bug Report | 錯誤回報

```markdown
## Description
[Clear, concise description of the bug]

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [Third step]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Screenshots/Logs
[If applicable]

## Environment
- OS: [e.g., Windows 11, macOS 14]
- Browser: [e.g., Chrome 120]
- Version: [e.g., v1.2.3]

## Severity
- [ ] Critical - System unusable
- [ ] High - Major feature broken
- [ ] Medium - Minor feature broken
- [ ] Low - Cosmetic issue
```

### Technical Task | 技術任務

```markdown
## Summary
[One-line description]

## Background
[Why is this needed? Context.]

## Technical Details
[Implementation details, approach]

## Acceptance Criteria
- [ ] [Technical criterion 1]
- [ ] [Technical criterion 2]

## Dependencies
- [List any dependencies]

## Risks
- [List any risks or concerns]
```

---

## Common Mistakes | 常見錯誤

### Too Vague | 過於模糊

❌ **Bad**:
```
Make the system faster.
```

✅ **Good**:
```
Reduce API response time to under 200ms for the /users endpoint.
```

### Solution Instead of Problem | 寫解決方案而非問題

❌ **Bad**:
```
Add a Redis cache.
```

✅ **Good**:
```
Improve dashboard load time from 5s to under 1s.
(Redis cache may be one solution, but let team decide)
```

### Missing Acceptance Criteria | 缺少驗收標準

❌ **Bad**:
```
Implement user authentication.
```

✅ **Good**:
```
Implement user authentication.

Acceptance Criteria:
- [ ] Users can register with email/password
- [ ] Users can log in with credentials
- [ ] Users can reset password via email
- [ ] Session expires after 24 hours of inactivity
- [ ] Failed login attempts limited to 5 per hour
```

### Too Large | 範圍過大

❌ **Bad**:
```
Build the entire e-commerce platform.
```

✅ **Good**:
```
Epic: E-commerce Platform

Story 1: User can browse product catalog
Story 2: User can add items to cart
Story 3: User can checkout with credit card
Story 4: Admin can manage inventory
```

---

## Requirement Review Checklist | 需求審查檢查清單

Before submitting a requirement:

- [ ] Clear problem statement
- [ ] Target user/persona identified
- [ ] Acceptance criteria defined
- [ ] Priority assigned
- [ ] Scope boundaries clear
- [ ] Dependencies identified
- [ ] Follows INVEST principles
- [ ] Testable and measurable
- [ ] No implementation details (unless necessary)

---

**License**: CC BY 4.0 | **Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

```

### requirement-checklist.md

```markdown
# Requirement Completeness Checklist
# 需求完整性檢查清單

## Quick Checklist | 快速檢查

Before submitting any requirement, verify these essentials:

| Item | Check | Question |
|------|:-----:|----------|
| Problem | [ ] | What problem are we solving? |
| Users | [ ] | Who benefits from this? |
| Value | [ ] | Why is this important? |
| Scope | [ ] | What's included and excluded? |
| Criteria | [ ] | How do we know it's done? |
| Priority | [ ] | How urgent is this? |

---

## Detailed Checklist by Requirement Type | 依需求類型的詳細檢查清單

### Feature Request Checklist | 功能需求檢查清單

#### 1. Problem Definition | 問題定義

- [ ] Problem is clearly stated
- [ ] Current pain points identified
- [ ] Impact quantified (if possible)
- [ ] Root cause understood

#### 2. User Context | 使用者情境

- [ ] Target users/personas identified
- [ ] User goals described
- [ ] Current workarounds documented
- [ ] User journey mapped (if complex)

#### 3. Solution Description | 解決方案描述

- [ ] Feature described (not implementation)
- [ ] User interactions outlined
- [ ] Expected outcomes stated
- [ ] Success metrics defined

#### 4. Acceptance Criteria | 驗收標準

- [ ] All criteria are testable
- [ ] Happy path covered
- [ ] Error scenarios defined
- [ ] Edge cases considered
- [ ] Performance criteria (if applicable)

#### 5. Scope Definition | 範圍定義

- [ ] In-scope items listed
- [ ] Out-of-scope items listed
- [ ] Future considerations noted
- [ ] Dependencies identified

#### 6. Priority & Timeline | 優先級與時程

- [ ] Priority assigned (P0-P3 or MoSCoW)
- [ ] Business justification provided
- [ ] Deadline noted (if any)
- [ ] Release target identified

---

### Bug Report Checklist | 錯誤回報檢查清單

#### 1. Description | 描述

- [ ] Title is clear and specific
- [ ] Description is concise
- [ ] Impact/severity stated

#### 2. Reproduction | 重現步驟

- [ ] Steps are numbered
- [ ] Steps are reproducible
- [ ] Prerequisites listed
- [ ] Test data provided (if needed)

#### 3. Behavior | 行為

- [ ] Expected behavior described
- [ ] Actual behavior described
- [ ] Difference is clear

#### 4. Evidence | 證據

- [ ] Screenshots attached (if UI)
- [ ] Error logs included (if available)
- [ ] Stack trace provided (if crash)

#### 5. Environment | 環境

- [ ] OS and version
- [ ] Browser and version (if web)
- [ ] App version
- [ ] Relevant configuration

#### 6. Classification | 分類

- [ ] Severity assigned
- [ ] Priority assigned
- [ ] Component/area identified
- [ ] Related issues linked

---

### Technical Task Checklist | 技術任務檢查清單

#### 1. Context | 背景

- [ ] Why is this needed?
- [ ] What problem does it solve?
- [ ] What triggered this task?

#### 2. Technical Details | 技術細節

- [ ] Approach described
- [ ] Affected components listed
- [ ] Database changes noted
- [ ] API changes noted

#### 3. Scope | 範圍

- [ ] What will be changed?
- [ ] What will NOT be changed?
- [ ] Backward compatibility addressed

#### 4. Criteria | 標準

- [ ] Definition of done clear
- [ ] Testing requirements defined
- [ ] Documentation needs identified

#### 5. Risks | 風險

- [ ] Technical risks identified
- [ ] Mitigation strategies noted
- [ ] Rollback plan (if deployment)

---

## INVEST Validation | INVEST 驗證

Use this to validate user stories:

### Independent | 獨立性

- [ ] Can be delivered without other stories
- [ ] No blocking dependencies
- [ ] Can be prioritized freely

**If NO**: Consider combining with dependent story or redefining scope.

### Negotiable | 可協商性

- [ ] Implementation details not locked in
- [ ] Room for technical discussion
- [ ] Focus on WHAT, not HOW

**If NO**: Remove implementation specifics, focus on outcome.

### Valuable | 有價值性

- [ ] Delivers value to user/stakeholder
- [ ] Solves a real problem
- [ ] Benefit is clear

**If NO**: Reconsider if this should be done at all.

### Estimable | 可估算性

- [ ] Team can estimate effort
- [ ] Scope is understood
- [ ] No major unknowns

**If NO**: Spike/research task needed first.

### Small | 小型化

- [ ] Can complete in one sprint
- [ ] Typically 1-5 days effort
- [ ] Single coherent piece of work

**If NO**: Break into smaller stories.

### Testable | 可測試性

- [ ] Clear acceptance criteria
- [ ] Can write automated tests
- [ ] Definition of done is unambiguous

**If NO**: Add specific, measurable criteria.

---

## Acceptance Criteria Quality Check | 驗收標準品質檢查

For each acceptance criterion:

| Quality | Check | Example |
|---------|:-----:|---------|
| Specific | [ ] | "Login button is blue (#007bff)" not "Button looks good" |
| Measurable | [ ] | "Response < 200ms" not "Fast response" |
| Achievable | [ ] | Technically feasible |
| Relevant | [ ] | Related to the requirement |
| Testable | [ ] | Can write a test case |

### Common Issues | 常見問題

| Issue | Bad Example | Good Example |
|-------|-------------|--------------|
| Too vague | "System works well" | "System returns 200 OK within 500ms" |
| Subjective | "UI is user-friendly" | "User can complete checkout in 3 clicks" |
| Missing edge cases | "User can upload file" | "User can upload 1-10MB files; error shown for larger files" |
| Implementation detail | "Use Redis cache" | "Dashboard loads in under 1 second" |

---

## Final Review Checklist | 最終審查檢查清單

Before submitting for development:

### Content Quality | 內容品質

- [ ] Title is clear and descriptive
- [ ] Description is complete
- [ ] No ambiguous language
- [ ] No assumptions unstated
- [ ] Technical jargon explained

### Completeness | 完整性

- [ ] All required fields filled
- [ ] Acceptance criteria defined
- [ ] Scope boundaries clear
- [ ] Dependencies listed
- [ ] Priority assigned

### Consistency | 一致性

- [ ] Follows team templates
- [ ] Consistent terminology
- [ ] Linked to related items
- [ ] Labels applied correctly

### Ready for Development | 準備開發

- [ ] Team can estimate effort
- [ ] No blocking questions
- [ ] Stakeholder approval (if needed)
- [ ] Design assets ready (if UI)

---

## Checklist Results | 檢查結果

**Requirement Title**: ___________________________

**Checked By**: ___________________________

**Date**: ___________________________

| Section | Complete | Notes |
|---------|:--------:|-------|
| Problem Definition | [ ] | |
| User Context | [ ] | |
| Solution Description | [ ] | |
| Acceptance Criteria | [ ] | |
| Scope Definition | [ ] | |
| Priority | [ ] | |
| INVEST Validation | [ ] | |

**Ready for Development**: [ ] Yes  [ ] No

**Action Items**:
- ___________________________
- ___________________________

---

**License**: CC BY 4.0 | **Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

```