---
name: step-03-specify
description: Specification phase - FRD with use cases, requirements, permissions
model: sonnet
prev_step: steps/step-02-analyse.md
next_step: steps/step-04-validate.md
---

<objective>
Create comprehensive Functional Requirements Document (FRD) with:
- Use Cases (UC-XXX)
- Functional Requirements (FR-XXX)
- Permission matrix
- UI wireframes
- Gherkin scenarios
</objective>

<ultrathink>
ULTRATHINK MODE - Specification:
- Each UC must be atomic and testable
- FR must trace back to BR
- Permissions must follow SmartStack convention
- No ambiguity in scenarios
</ultrathink>

## EXECUTION SEQUENCE

### 1. Read Current State

Read `{output_dir}/00-context.md` to restore state variables.
Read `{output_dir}/2-business-requirements.md` for business rules.

Update progress: `03-specify` -> "In Progress"

---

### 2. Load FRD Template

```
Read: templates/frd-spec.md    # ~150 lines (UC + FR + permissions sections)
```

This template contains ONLY the FRD structure.

---

### 3. Define Actors and Permissions

From BRD stakeholders, map to system actors:

| Actor | Description | Permission base |
|-------|-------------|-----------------|
| Admin | Full access | `business.{app}.{module}.*` |
| Manager | Read + Create + Update | `business.{app}.{module}.read,create,update` |
| User | Read + Create | `business.{app}.{module}.read,create` |
| ReadOnly | View only | `business.{app}.{module}.read` |

**Permission format:** `business.{application_name}.{module_name}.{action}`

Actions:
- `.read` - View data
- `.create` - Create new entries
- `.update` - Modify existing
- `.delete` - Remove entries
- `.export` - Export data
- `.import` - Import data
- `.admin` - Administrative functions

---

### 4. Create Use Cases

For each major functionality, create UC:

```markdown
### UC-001: {Use Case Name}

| Attribute | Value |
|-----------|-------|
| **ID** | UC-001 |
| **Name** | {Name} |
| **Primary Actor** | {Role} |
| **Preconditions** | {required conditions} |
| **Postconditions** | {final state} |
| **Permission** | `business.{app}.{module}.{action}` |

**Main Scenario:**
1. The user {action}
2. The system {response}
3. The user {action}
4. The system {response}

**Alternative Scenarios:**

| # | Condition | Steps |
|---|-----------|-------|
| 3a | {condition} | 3a.1 {action}, 3a.2 {action} |

**Error Scenarios:**

| # | Error | Message | Action |
|---|-------|---------|--------|
| E1 | {error} | {user message} | {behavior} |

**Associated Rules:** BR-001, BR-002
```

**ULTRATHINK checkpoint:**
- Each UC maps to at least one BR?
- All actors from BRD have UCs?
- Error scenarios complete?

---

### 5. Define Functional Requirements

For each BR, create corresponding FR:

| ID | Requirement | Linked UC | Priority |
|----|-------------|-----------|----------|
| FR-001 | The system MUST... | UC-001 | Must |
| FR-002 | The system SHOULD... | UC-001 | Should |
| FR-003 | The system COULD... | UC-002 | Could |

**Detailed FR specification:**

```markdown
### FR-001: {Requirement Name}

**Statement:** The system MUST {specific action}

**Acceptance Criteria:**
- [ ] {Measurable criterion 1}
- [ ] {Measurable criterion 2}
- [ ] {Measurable criterion 3}

**Associated Rules:** BR-001, BR-002
**Use Cases:** UC-001
```

**Priority mapping:**
- Must = FR-0XX (000-099)
- Should = FR-1XX (100-199)
- Could = FR-2XX (200-299)

---

### 6. Design Permission Matrix

**Role-Permission Matrix:**

| Permission | Admin | Manager | User | ReadOnly |
|------------|-------|---------|------|----------|
| `business.{app}.{module}.read` | X | X | X | X |
| `business.{app}.{module}.create` | X | X | X | - |
| `business.{app}.{module}.update` | X | X | - | - |
| `business.{app}.{module}.delete` | X | - | - | - |
| `business.{app}.{module}.export` | X | X | - | - |

**Endpoint-Permission Mapping:**

| Endpoint | Method | Required Permission |
|----------|--------|-------------------|
| `/api/business/{module}` | GET | `.read` |
| `/api/business/{module}` | POST | `.create` |
| `/api/business/{module}/{id}` | GET | `.read` |
| `/api/business/{module}/{id}` | PUT | `.update` |
| `/api/business/{module}/{id}` | DELETE | `.delete` |

---

### 7. Create UI Wireframes

**Main screen wireframe:**

```
┌─────────────────────────────────────────────────────────────┐
│  [Logo]    {Module Name}                      [User] [Menu] │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ FILTERS                                              │   │
│  │ [Field 1 ▼] [Field 2 ▼] [Search]                   │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ DATA TABLE                                           │   │
│  │ ┌────────┬────────┬────────┬─────────┐              │   │
│  │ │ Col 1  │ Col 2  │ Col 3  │ Actions │              │   │
│  │ ├────────┼────────┼────────┼─────────┤              │   │
│  │ │ data   │ data   │ data   │ [E] [D] │              │   │
│  │ └────────┴────────┴────────┴─────────┘              │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  [+ New] (if .create)                   [< Prev] [Next >]  │
└─────────────────────────────────────────────────────────────┘
```

**UI Elements description:**

| Element | Type | Behavior | Permission |
|---------|------|----------|------------|
| [+ New] | Button | Opens create modal | `.create` |
| [E] | Icon | Opens edit modal | `.update` |
| [D] | Icon | Confirm + delete | `.delete` |

---

### 8. Write Gherkin Scenarios

```gherkin
Feature: {feature_id} {feature_description}

  Background:
    Given the system is configured with test data
    And the permission system is active

  @permission @403
  Scenario: User without permission cannot create
    Given I am logged in as "user@test.com" with role "ReadOnly"
    When I send POST to "/api/business/{module}"
    Then the response status should be 403
    And the response should contain "Permission denied"

  @happy-path
  Scenario: Admin creates new item
    Given I am logged in as "admin@test.com" with role "Admin"
    And I have permission "business.{app}.{module}.create"
    When I send POST to "/api/business/{module}" with:
      | field1 | value1 |
      | field2 | value2 |
    Then the response status should be 201
    And the response should contain "id"

  @validation
  Scenario: Validation error on required field
    Given I am logged in with permission "business.{app}.{module}.create"
    When I send POST to "/api/business/{module}" with:
      | field1 | |
    Then the response status should be 400
    And the response should contain "field1 is required"

  @business-rule @BR-001
  Scenario: {BR-001 scenario}
    Given {precondition}
    When {action}
    Then {expected result per BR-001}
```

---

### 9. Define Validations and Messages

**Field validations:**

| Field | Rule | Error Message (i18n key) |
|-------|------|--------------------------|
| {field} | Required | `{module}.errors.{field}Required` |
| {field} | MaxLength(100) | `{module}.errors.{field}TooLong` |
| email | Email format | `{module}.errors.invalidEmail` |

**System messages:**

| Code | Type | Message (i18n key) |
|------|------|-------------------|
| MSG-001 | Success | `{module}.messages.created` |
| MSG-002 | Success | `{module}.messages.updated` |
| MSG-003 | Success | `{module}.messages.deleted` |
| MSG-004 | Error | `{module}.errors.notFound` |
| MSG-005 | Error | `{module}.errors.permissionDenied` |

---

### 10. Compile FRD Document

Assemble complete FRD using template structure.

---

### 11. Save Output

Write to: `{output_dir}/3-functional-specification.md`

Update `00-context.md`:
- Progress: `03-specify` -> "Complete"
- Add UC count, FR count, permission count

---

### 12. Display Summary and Load Next Step

**Display:**
```
SPECIFICATION - {feature_id}
├── Status: Complete
├── Use Cases: {UC count}
├── Requirements: {FR count} (Must: X, Should: Y, Could: Z)
├── Permissions: {permission count}
├── Gherkin scenarios: {scenario count}
├── Output: {output_dir}/3-functional-specification.md
└── Next: step-04-validate (Validation Gate)
```

**Load next step:**
```
Read and execute: steps/step-04-validate.md
```

---

## OUTPUT

This step produces:
- `{output_dir}/3-functional-specification.md` (created)
- `{output_dir}/00-context.md` (updated)

Template loaded: **~150 lines** (vs 477 lines full file)
