sop-rfc2119

What this skill does

# RFC 2119 Keywords for SOPs

RFC 2119 defines keywords for indicating requirement levels in specifications. Using these keywords in SOPs creates precise, unambiguous instructions that AI agents can execute deterministically.

## Key Concepts

### The RFC 2119 Keywords

RFC 2119 defines these keywords for requirement levels:

| Keyword | Meaning | Usage |
|---------|---------|-------|
| **MUST** | Absolute requirement | Non-negotiable steps that must be performed |
| **MUST NOT** | Absolute prohibition | Actions that are forbidden |
| **SHOULD** | Strong recommendation | Preferred approach, but alternatives may exist |
| **SHOULD NOT** | Strong discouragement | Discouraged, but may be acceptable in specific cases |
| **MAY** | Optional | Truly optional actions at agent's discretion |

### Why Use RFC 2119 in SOPs

1. **Eliminates Ambiguity**: Clear distinction between required and optional steps
2. **Predictable Execution**: Agents know exactly what is mandatory vs. recommended
3. **Better Error Handling**: Violations of MUST/MUST NOT trigger immediate failures
4. **Consistent Interpretation**: Standard keywords understood across implementations

## Best Practices

### Using MUST

**MUST** indicates absolute requirements. Use for:

- Critical safety or security steps
- Steps that affect data integrity
- Prerequisites that block subsequent steps
- Validation that prevents errors

```markdown
## Steps

1. You MUST verify all tests pass before deployment
2. You MUST backup the database before running migrations
3. You MUST validate user input before processing
4. You MUST check authentication before accessing resources
```

**When Not to Use MUST:**

- ❌ Stylistic preferences: "You MUST use single quotes"
- ❌ Minor optimizations: "You MUST use const instead of let"
- ✅ Use SHOULD instead for preferences

### Using MUST NOT

**MUST NOT** indicates absolute prohibitions. Use for:

- Security violations
- Data corruption risks
- Breaking changes without migration
- Actions that violate invariants

```markdown
## Steps

1. You MUST NOT commit secrets to version control
2. You MUST NOT modify production data without backup
3. You MUST NOT skip type checking before deployment
4. You MUST NOT proceed if validation fails
```

**Examples:**

```markdown
## Security Requirements

- You MUST NOT log sensitive user data (passwords, tokens, PII)
- You MUST NOT disable security features in production
- You MUST NOT expose internal error details to users
- You MUST NOT use user input directly in SQL queries

## Data Integrity

- You MUST NOT delete data without backup verification
- You MUST NOT modify schema without migration path
- You MUST NOT skip transaction rollback on errors
- You MUST NOT cache data without expiration
```

### Using SHOULD

**SHOULD** indicates strong recommendations. Use for:

- Best practices that improve quality
- Performance optimizations
- Code style preferences
- Recommended but not required steps

```markdown
## Steps

1. You SHOULD add logging for debugging
2. You SHOULD include usage examples in documentation
3. You SHOULD run linter before committing
4. You SHOULD use meaningful variable names
```

**SHOULD vs. MUST:**

```markdown
## Type Safety (MUST - affects correctness)
- You MUST add type annotations to public APIs
- You MUST validate types at runtime boundaries

## Code Quality (SHOULD - improves maintainability)
- You SHOULD add type annotations to internal functions
- You SHOULD use strict TypeScript configuration
```

### Using SHOULD NOT

**SHOULD NOT** indicates discouragement. Use for:

- Anti-patterns to avoid
- Suboptimal but sometimes necessary approaches
- Deprecated patterns being phased out

```markdown
## Steps

1. You SHOULD NOT use global variables (use dependency injection)
2. You SHOULD NOT catch all errors (catch specific exceptions)
3. You SHOULD NOT use magic numbers (define constants)
4. You SHOULD NOT nest callbacks deeply (use async/await)
```

**With Justification:**

```markdown
## Code Patterns

- You SHOULD NOT use eval() for parsing (security risk)
  - Exception: If you MUST use eval(), sanitize input and run in sandbox

- You SHOULD NOT use var (use const or let)
  - Exception: Supporting legacy browsers may require var

- You SHOULD NOT use any type in TypeScript (defeats type safety)
  - Exception: Interfacing with untyped libraries may require any
```

### Using MAY

**MAY** indicates truly optional actions. Use for:

- Optional enhancements
- User preferences
- Non-critical additions
- Context-dependent choices

```markdown
## Steps

1. You MAY add code comments for complex logic
2. You MAY include performance benchmarks
3. You MAY use helper utilities for common operations
4. You MAY add additional test cases beyond minimum coverage
```

**MAY vs. SHOULD:**

```markdown
## Documentation (SHOULD - recommended)
- You SHOULD document public APIs
- You SHOULD include README with setup instructions

## Additional Documentation (MAY - optional)
- You MAY add architecture diagrams
- You MAY include design decision records
- You MAY create video tutorials
```

## Examples

### Example 1: Code Review SOP with RFC 2119

```markdown
# Review Pull Request for Security

## Steps

1. Analyze authentication and authorization
   - You MUST verify authentication is required for protected routes
   - You MUST check authorization logic prevents privilege escalation
   - You SHOULD use role-based access control (RBAC)
   - You MAY suggest additional security layers

2. Review input validation
   - You MUST verify all user input is validated
   - You MUST confirm SQL queries use parameterization
   - You MUST NOT allow unescaped user input in templates
   - You SHOULD validate input both client and server side

3. Check secret management
   - You MUST NOT approve code with hardcoded secrets
   - You MUST verify secrets use environment variables
   - You SHOULD check secrets are not logged
   - You MAY recommend secret rotation policies

4. Assess error handling
   - You MUST verify errors don't expose sensitive information
   - You SHOULD check errors are logged appropriately
   - You SHOULD NOT allow generic catch-all error handlers
   - You MAY suggest specific error recovery strategies
```

### Example 2: TDD Implementation SOP with RFC 2119

```markdown
# Implement Feature Using Test-Driven Development

## Steps

1. Write failing test (RED)
   - You MUST write test before implementation code
   - You MUST run test to verify it fails
   - You MUST confirm failure message describes expected behavior
   - You SHOULD use descriptive test names
   - You MAY add multiple test cases for edge cases

2. Write minimal implementation (GREEN)
   - You MUST write simplest code to pass test
   - You MUST run test to verify it passes
   - You MUST NOT add functionality beyond test requirements
   - You SHOULD NOT optimize prematurely
   - You MAY add code comments for complex logic

3. Refactor (REFACTOR)
   - You MUST keep all tests passing during refactoring
   - You MUST run tests after each refactoring step
   - You SHOULD extract duplicated code
   - You SHOULD improve naming and structure
   - You SHOULD NOT change test behavior
   - You MAY add performance optimizations if needed

4. Repeat cycle
   - You MUST complete red-green-refactor for each requirement
   - You SHOULD commit after each complete cycle
   - You MAY combine related test cases
```

### Example 3: Deployment SOP with RFC 2119

```markdown
# Deploy Application to Production

## Prerequisites

- You MUST have production credentials configured
- You MUST verify all tests passed on staging
- You SHOULD have reviewed recent changes
- You MAY have notified team of deployment

## Steps

1. Pre-deployment verification
   - You MUST verify staging deployment is healthy
   - You MUST check database migrations are ready
   - You MUST confirm rollback plan is documented
   - You SHOULD review monitoring dashboards
   - You MAY run additional smoke tests

2. E