Authoring Requirements

Authoring Requirements

Overview

Write technology-agnostic functional requirements, identify edge cases, and define measurable success criteria. Focus on WHAT the system does and WHY, never HOW it's implemented.

When to Use

• Starting a new feature specification
• Documenting acceptance criteria for user stories
• Defining API contracts at the business logic level
• Creating requirements for stakeholder review
• When existing requirements are vague or missing structure
• Translating informal feature requests into formal requirements

When NOT to Use

• Implementation planning - Use design docs or architecture decisions instead
• Technical architecture decisions - Use ADRs or technical design documents
• When requirements already exist and are validated - Don't duplicate work
• API endpoint specifications - Use humaninloop:patterns-api-contracts instead
• Data model design - Use humaninloop:patterns-entity-modeling instead
• User story authoring - Use humaninloop:authoring-user-stories instead (this skill focuses on the underlying requirements)

Functional Requirements Format

Write requirements using the FR-XXX format with RFC 2119 keywords:

## Functional Requirements

- **FR-001**: System MUST [specific capability]
- **FR-002**: Users MUST be able to [specific action]
- **FR-003**: System SHOULD [recommended behavior]
- **FR-004**: System MAY [optional capability]

RFC 2119 Keywords

See RFC-2119-KEYWORDS.md for detailed usage guidance.

FR Numbering Rules

1. Sequential numbering: FR-001, FR-002, FR-003...
2. No gaps in sequence
3. Three-digit padding (001, not 1)
4. Group related requirements together

Writing Technology-Agnostic Requirements

Good (what):

• "System MUST notify users when their subscription expires"
• "Users MUST be able to export their data in a portable format"

Bad (how):

• "System MUST send email via SendGrid when subscription expires"
• "Users MUST be able to download a JSON export from the /api/export endpoint"

Edge Cases

Identify 3-5 boundary conditions that need explicit handling:

## Edge Cases

1. **System limits**: What happens at maximum capacity?
2. **Invalid input**: How are malformed requests handled?
3. **External failures**: What if dependencies are unavailable?
4. **Concurrent access**: How are race conditions prevented?
5. **Permission boundaries**: What happens with unauthorized access?

Edge Case Categories

See EDGE-CASES.md for detailed patterns.

Success Criteria Format

Define 3-5 measurable outcomes using SC-XXX format:

## Success Criteria

- **SC-001**: Users complete the task creation flow in under 2 minutes
- **SC-002**: 95% of users successfully create their first recurring task
- **SC-003**: Support tickets related to task scheduling decrease by 50%

Success Criteria Rules

1. Technology-agnostic: No API metrics, database stats, or code coverage
2. User/business focused: Observable by stakeholders
3. Measurable: Quantifiable where possible
4. Outcome-oriented: What changes, not what's built

Good:

• "Users complete the workflow in under 2 minutes"
• "Error rate for task creation drops below 5%"
• "User satisfaction score increases to 4.5/5"

Bad:

• "API responds in under 200ms"
• "Database queries execute in under 50ms"
• "Code coverage exceeds 80%"

Key Entities (Optional)

When the feature involves data, describe entities conceptually:

## Key Entities

### RecurringPattern
Represents the schedule for a repeating task.

**Attributes:**
- Frequency (how often: daily, weekly, monthly)
- Interval (every N occurrences)
- End condition (never, after N times, on date)

**Relationships:**
- Belongs to one Task
- Generates many TaskInstances

Entity Description Rules

• Describe purpose, not schema
• List attributes as concepts, not columns
• Focus on relationships, not foreign keys
• No data types, constraints, or indexes

Validation Script

Validate requirement format with the included script:

python scripts/validate-requirements.py path/to/spec.md

The script checks:

• FR-XXX format and sequential numbering
• RFC 2119 keywords present
• SC-XXX format and sequential numbering
• Technology-agnostic language

Quality Checklist

Before finalizing, verify:

• All FRs use RFC 2119 keywords (MUST/SHOULD/MAY)
• FR numbers are sequential with no gaps
• No technology or implementation details mentioned
• 3-5 edge cases identified
• All SCs are measurable outcomes
• SCs focus on user/business value
• Entities described conceptually (if applicable)

Common Mistakes

Technology Leakage

❌ "System MUST use PostgreSQL for storage" ✅ "System MUST persist data durably"

Implementation Details

❌ "MUST implement using the Observer pattern" ✅ "System MUST notify relevant components when state changes"

Unmeasurable Criteria

❌ "System MUST be fast" or "MUST be user-friendly" ✅ "Users MUST complete the flow in under 2 minutes"

Missing RFC 2119 Keywords

❌ "System will notify users" ✅ "System MUST notify users" (use MUST/SHOULD/MAY)

Technical Metrics as Success Criteria

❌ "API latency MUST be under 100ms" ✅ "Users MUST perceive responses as instantaneous"

Confusing Requirements with User Stories

❌ "As a user, I want to see my balance" ✅ "System MUST display current balance to authenticated users" (FR) + separate user story

Scope Creep in Edge Cases

❌ Listing 20+ edge cases covering every hypothetical ✅ Focus on 3-5 high-impact boundary conditions

Converted and distributed by TomeVault — claim your Tome and manage your conversions.