---
title: "Creating Requirements"
description: "Define features, user stories, and requirements in TraceRTM"
---

# Creating Requirements

Requirements (features) are the foundation of your traceability matrix. This guide shows how to create and manage requirements in TraceRTM.

## What Are Requirements?

In TraceRTM, requirements are artifacts that describe what your system should do. They include:

- **Features**: High-level capabilities
- **User Stories**: User-centric requirements
- **Epics**: Large features that span multiple sprints
- **Sub-features**: Detailed breakdowns

## Creating Your First Feature

### Using the CLI

```bash
# Create a simple feature
tracertm create feature "User Authentication"

# Create with more details
tracertm create feature "User Authentication" \
  --description "Implement secure login with OAuth2" \
  --priority high \
  --owner alice@example.com

# Output:
# Created: FEAT-001 "User Authentication"
```

### Using Python SDK

```python
from tracertm import TraceRTMClient

client = TraceRTMClient()

feature = client.create_item(
    title="User Authentication",
    item_type="feature",
    description="Implement secure login with OAuth2 support",
    priority="high",
    owner="alice@example.com",
    metadata={
        "sprint": "2024-Q4-S3",
        "story_points": 8,
        "acceptance_criteria": [
            "Users can log in with email/password",
            "OAuth2 with Google and GitHub",
            "Session management with JWT"
        ]
    }
)

print(f"Created: {feature.id}")  # FEAT-001
```

### Using Local Storage (Markdown)

Create a file directly in `artifacts/features/`:

```markdown
<!-- artifacts/features/FEAT-001.md -->
---
id: FEAT-001
title: User Authentication
type: feature
status: draft
priority: high
owner: alice@example.com
created_at: 2024-12-07T10:00:00Z
metadata:
  sprint: "2024-Q4-S3"
  story_points: 8
---

# User Authentication

Implement secure user login with OAuth2 support.

## Description

Users need to authenticate to access protected resources. The system
should support multiple authentication methods.

## Acceptance Criteria

- [ ] Users can log in with email/password
- [ ] OAuth2 integration with Google
- [ ] OAuth2 integration with GitHub
- [ ] JWT-based session management
- [ ] Password reset via email
- [ ] Account lockout after failed attempts

## Notes

Consider rate limiting on login endpoints to prevent brute force attacks.
```

## Feature Hierarchy

Create parent-child relationships for complex features:

```bash
# Create parent feature (epic)
tracertm create feature "Authentication System" --id FEAT-001

# Create child features
tracertm create feature "Email Login" --parent FEAT-001
tracertm create feature "OAuth2 Integration" --parent FEAT-001
tracertm create feature "Password Reset" --parent FEAT-001
```

Result:
```
FEAT-001: Authentication System
├── FEAT-002: Email Login
├── FEAT-003: OAuth2 Integration
└── FEAT-004: Password Reset
```

### Python SDK

```python
# Create epic
epic = client.create_item(
    title="Authentication System",
    item_type="feature"
)

# Create child features
for title in ["Email Login", "OAuth2 Integration", "Password Reset"]:
    client.create_item(
        title=title,
        item_type="feature",
        parent_id=epic.id
    )
```

## Feature States

Features move through workflow states:

| State | Description | Next States |
|-------|-------------|-------------|
| `draft` | Initial, incomplete | `ready_for_dev` |
| `ready_for_dev` | Approved for development | `in_development` |
| `in_development` | Being implemented | `in_review` |
| `in_review` | Code review | `ready_for_qa` |
| `ready_for_qa` | Ready for testing | `in_qa` |
| `in_qa` | Being tested | `done` |
| `done` | Completed | - |

### Transitioning States

```bash
# Move feature to next state
tracertm transition FEAT-001 ready_for_dev

# Check current state
tracertm show FEAT-001 --field status
```

```python
client.transition_item("FEAT-001", "ready_for_dev")
```

## Listing and Filtering

### List All Features

```bash
# List all features
tracertm list --type feature

# Filter by status
tracertm list --type feature --status in_progress

# Filter by owner
tracertm list --type feature --owner alice@example.com

# Filter by priority
tracertm list --type feature --priority high
```

### Python SDK

```python
# Get all features
features = client.get_items(item_type="feature")

# With filters
active_features = client.get_items(
    item_type="feature",
    status=["draft", "in_progress", "in_review"],
    owner="alice@example.com"
)

# Search by text
results = client.search_items("authentication", item_type="feature")
```

## Updating Features

```bash
# Update title
tracertm update FEAT-001 --title "User Authentication v2"

# Update priority
tracertm update FEAT-001 --priority critical

# Add to metadata
tracertm update FEAT-001 --metadata '{"deadline": "2024-12-31"}'
```

```python
client.update_item(
    "FEAT-001",
    title="User Authentication v2",
    priority="critical",
    metadata={"deadline": "2024-12-31"}
)
```

## Bulk Operations

Import multiple features at once:

```bash
# Import from CSV
tracertm import features.csv --type feature

# Import from JSON
tracertm import features.json
```

CSV format:
```csv
title,description,priority,owner
User Login,Email/password login,high,alice@example.com
Password Reset,Reset via email,medium,bob@example.com
OAuth2 Login,Google and GitHub OAuth,high,alice@example.com
```

## Best Practices

### 1. Write Clear Titles

- Bad: "Login"
- Good: "User Authentication with Email/Password"

### 2. Include Acceptance Criteria

Make requirements testable:

```markdown
## Acceptance Criteria

- [ ] User can enter email and password
- [ ] Invalid credentials show error message
- [ ] Successful login redirects to dashboard
- [ ] Session persists across browser refresh
```

### 3. Use Consistent IDs

Configure ID prefixes in your project:

```yaml
# .tracertm/config.yaml
defaults:
  id_prefix:
    feature: FEAT
    epic: EPIC
    story: US
```

### 4. Link Early

Start linking to tests and code as soon as they exist:

```bash
tracertm link FEAT-001 TEST-001 --type verified_by
tracertm link FEAT-001 CODE-001 --type realized_by
```

## Next Steps

- [Creating Test Cases](/docs/getting-started/first-project/test-cases) - Link tests to requirements
- [Establishing Traceability](/docs/getting-started/first-project/traceability) - Build the trace graph
- [Data Model](/docs/getting-started/core-concepts/data-model) - Artifact structure details

