requirements-engineering

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 51e630616a9b · 20 Oct 2026Report an issue or request a re-scan

• Publisherjasonkneen GitHub userOwner of the repository this skill is read from
• Source folderjasonkneen/kiro/skills/requirements-engineeringThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict51e630616a9bA new audit runs when the source changes
• Repository statusNot archivedLast push 280 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Transform vague feature ideas into clear, testable requirements using EARS format. Capture user stories, define acceptance criteria, identify edge cases, and validate completeness before moving to design.

---
name: requirements-engineering
description: Transform vague feature ideas into clear, testable requirements using EARS format. Capture user stories, define acceptance criteria, identify edge cases, and validate completeness before moving to design.
license: MIT
compatibility: Claude Code, Cursor, VS Code, Windsurf
metadata:
  category: methodology
  complexity: beginner
  author: Kiro Team
  version: "1.0.0"
---

# Requirements Engineering

Master the art of capturing what needs to be built before diving into how to build it. This skill teaches the EARS (Easy Approach to Requirements Syntax) format for creating clear, testable requirements.

## When to Use This Skill

Use requirements engineering when:
- Starting any new feature or project
- Clarifying ambiguous stakeholder requests
- Creating acceptance criteria for user stories
- Documenting system behavior for testing
- Ensuring all team members share understanding

## The EARS Format

EARS provides consistent patterns for writing requirements that are specific, testable, and unambiguous.

### Basic Patterns

**Event-Response (Most Common):**
```
WHEN [triggering event] THEN [system] SHALL [required response]
```

**Conditional Behavior:**
```
IF [precondition is met] THEN [system] SHALL [required response]
```

**Complex Conditions:**
```
WHEN [event] AND [additional condition] THEN [system] SHALL [response]
```

**Optional Conditions:**
```
WHEN [event] OR [alternative event] THEN [system] SHALL [response]
```

### Advanced Patterns

**State-Based:**
```
WHEN [system is in specific state] THEN [system] SHALL [behavior]
```

**Performance:**
```
WHEN [user action] THEN [system] SHALL [respond within X seconds/milliseconds]
```

**Security:**
```
IF [authentication condition] THEN [system] SHALL [security response]
```

## Step-by-Step Process

### Step 1: Capture User Stories

Format: **As a [role], I want [feature], so that [benefit]**

Focus on:
- Who is the user? (role)
- What do they want to accomplish? (feature)
- Why does it matter? (benefit/value)

**Example:**
```markdown
As a returning customer, I want to save my payment methods, so that I can checkout faster in the future.
```

### Step 2: Generate Acceptance Criteria

For each user story, define specific acceptance criteria using EARS:

**Example for payment methods:**
```markdown
**User Story:** As a returning customer, I want to save my payment methods, so that I can checkout faster.

**Acceptance Criteria:**
1. WHEN user adds a valid credit card THEN system SHALL securely store card details
2. WHEN user adds a card with invalid number THEN system SHALL display validation error
3. WHEN user has saved cards THEN system SHALL display list during checkout
4. WHEN user selects saved card THEN system SHALL pre-fill payment form
5. WHEN user deletes saved card THEN system SHALL remove card from list
6. IF user is not authenticated THEN system SHALL redirect to login before saving card
7. WHEN user adds card THEN system SHALL mask all but last 4 digits in display
```

### Step 3: Identify Edge Cases

For each requirement, ask:
- What if the input is empty/null?
- What if the input is at boundary values?
- What if the operation fails?
- What if the user is not authorized?
- What if there are concurrent operations?

**Edge case patterns:**
```markdown
**Error Handling:**
- WHEN [operation fails] THEN system SHALL [display error / retry / log]

**Boundary Conditions:**
- WHEN [value equals minimum/maximum] THEN system SHALL [specific behavior]

**Concurrent Access:**
- WHEN [multiple users access same resource] THEN system SHALL [conflict resolution]

**Empty States:**
- WHEN [collection is empty] THEN system SHALL [display empty state message]
```

### Step 4: Validate Requirements

Use this checklist:

**Completeness:**
- [ ] All user roles identified and addressed
- [ ] Normal flow scenarios covered
- [ ] Edge cases documented
- [ ] Error cases handled
- [ ] Business rules captured

**Clarity:**
- [ ] Each requirement uses precise language
- [ ] No ambiguous terms (fast, easy, user-friendly)
- [ ] Technical jargon avoided or defined
- [ ] Expected behaviors are specific

**Consistency:**
- [ ] EARS format used throughout
- [ ] Terminology consistent across requirements
- [ ] No contradictory requirements
- [ ] Similar scenarios handled similarly

**Testability:**
- [ ] Each requirement can be verified
- [ ] Success criteria are observable
- [ ] Inputs and expected outputs specified
- [ ] Performance requirements are measurable

## Common Mistakes to Avoid

### Mistake 1: Vague Requirements
**Bad:** "System should be fast"
**Good:** "WHEN user submits search THEN system SHALL return results within 2 seconds"

### Mistake 2: Implementation Details
**Bad:** "System shall use Redis for caching"
**Good:** "WHEN user requests frequently accessed data THEN system SHALL return cached results"

### Mistake 3: Missing Error Cases
**Bad:** Only documenting happy path
**Good:** Include WHEN/IF statements for all error conditions

### Mistake 4: Untestable Requirements
**Bad:** "System should be user-friendly"
**Good:** "WHEN new user completes onboarding THEN system SHALL require no more than 3 clicks to reach main dashboard"

### Mistake 5: Conflicting Requirements
**Bad:** Requirements that contradict each other
**Good:** Review all requirements together, resolve conflicts explicitly

## Examples

### Example 1: File Upload Feature

```markdown
**User Story:** As a user, I want to upload files, so that I can share documents with my team.

**Acceptance Criteria:**
1. WHEN user selects file under 10MB THEN system SHALL accept file for upload
2. WHEN user selects file over 10MB THEN system SHALL display "file too large (max 10MB)" error
3. WHEN user selects unsupported file type THEN system SHALL display "unsupported format" error with list of allowed types
4. WHEN upload is in progress THEN system SHALL display progress indicator with percentage
5. WHEN upload completes successfully TH

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-20
   ✓SAFE B 89 / 100

   first audit · source 51e630616a9b

Questions about requirements-engineering

• github.com/jasonkneen/kiro/tree/main/skills/requirements-enginee — the audited source at commit 51e630616a9b and every finding aboveObserved · 20 Oct 2026

Spotted something wrong? Report a correction · Methodology