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

Keyword	Meaning
MUST	Absolute requirement; no exceptions
SHOULD	Recommended; valid exceptions may exist
MAY	Optional; implementation choice

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

Category	Examples
System limits	Max items, file size limits, rate limits
Invalid input	Empty fields, wrong types, boundary values
External failures	Network timeouts, service unavailable
Concurrency	Simultaneous edits, duplicate submissions
Permissions	Unauthorized access, expired tokens

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