gh-onezerocompany-claude-project-basics/skills/spec-author/guides/business-requirement.md

# How to Create a Business Requirement Specification

Business Requirements (BRD) capture what problem you're solving and why it matters from a business perspective. They translate customer needs into requirements that the technical team can build against.

## Quick Start

```bash
# 1. Create a new business requirement (auto-generates next ID)
scripts/generate-spec.sh business-requirement --next descriptive-slug
# This auto-assigns the next ID (e.g., brd-002-descriptive-slug)
# File created at: docs/specs/business-requirement/brd-002-descriptive-slug.md

# 2. Fill in the sections following the guide below

# 3. Validate completeness
scripts/validate-spec.sh docs/specs/business-requirement/brd-002-descriptive-slug.md

# 4. Fix any issues and check completeness
scripts/check-completeness.sh docs/specs/business-requirement/brd-002-descriptive-slug.md
```

**Pro tip:** Use `scripts/next-id.sh business-requirement` to see what the next ID will be before creating.

## When to Write a Business Requirement

Use a Business Requirement when you need to:
- Document a new feature or capability from the user's perspective
- Articulate the business value and expected outcomes
- Define acceptance criteria that stakeholders can verify
- Create alignment across product, engineering, and business teams
- Track success after implementation with specific metrics

## Research Phase

Before writing, gather context:

### 1. Research Related Specifications
Look for related specs that inform this requirement:
```bash
# Find related business requirements
grep -r "related\|similar\|user export" docs/specs/ --include="*.md" | head -20

# Or search for related technical requirements that might already exist
scripts/list-templates.sh  # See what's already documented
```

### 2. Research External Documentation & Competitive Landscape
If available, research:
- Competitor features or how similar companies solve this problem
- Industry standards or best practices
- User research or survey data
- Customer feedback or support tickets

Use web tools if needed:
```bash
# If researching web sources, use Claude's web fetch capabilities
# to pull in external docs, API documentation, or competitive analysis
```

### 3. Understand Existing Context
- Ask: What systems or processes does this impact?
- Find: Any existing specs in `docs/specs/` that are related
- Review: Recent PRs or commits related to this domain

## Structure & Content Guide

### Metadata Section
Fill in these required fields:
- **Document ID**: Use format `BRD-XXX-short-slug` (e.g., `BRD-001-user-export`)
- **Status**: Start with "Draft", moves to "In Review" → "Approved" → "Implemented"
- **Author**: Your name
- **Created**: Today's date (YYYY-MM-DD)
- **Stakeholders**: Key people involved (Product Manager, Engineering Lead, Customer Success, etc.)
- **Priority**: Critical | High | Medium | Low

### Description Section
Answer: "What is the problem and why does it matter?"

**Background**: Provide context
- What is the current situation?
- How did we identify this need?
- Who brought it up?

**Problem Statement**: Be concise and specific
- Example: "Users cannot export their data in bulk, forcing them to perform manual exports one at a time, which is time-consuming and error-prone."

### Business Value Section
Answer: "Why should we build this?"

**Expected Outcomes**: List 2-3 measurable outcomes
- Example: "Reduce manual export time by 80%"
- Example: "Increase user retention by enabling data portability"

**Strategic Alignment**: How does this support business goals?
- Example: "Aligns with our goal to improve user experience for enterprise customers"

### Stakeholders Section
Create a table identifying who needs to sign off or provide input:
- **Business Owner**: Makes final business decisions
- **Product Owner**: Gathers and prioritizes requirements
- **End Users**: The people who will use this feature
- **Technical Lead**: Ensures technical feasibility

### User Stories Section
Write 3-5 user stories following this format:
```
As a [user role],
I want to [capability],
so that [benefit/outcome]
```

**Tips for writing user stories:**
- Use real user roles from your product (not generic "user")
- Each story should be achievable in 1-3 days of work (rough estimate)
- Include acceptance criteria inline or in a separate section

**Example:**
| ID | As a... | I want to... | So that... | Priority |
|---|---|---|---|---|
| US-1 | Data Analyst | Export data as CSV | I can analyze it in Excel | High |
| US-2 | Enterprise Admin | Bulk export all user data | I can back it up and migrate to another system | High |
| US-3 | API Client | Get exports via webhook | I can automate reports | Medium |

### Assumptions Section
List what you're assuming to be true:
- "Users have stable internet connections"
- "Exported data will be less than 100MB"
- "We can leverage the existing database export functionality"

### Constraints Section
Identify limitations:
- **Business**: Budget, timeline, market windows
- **Technical**: System limitations, platform restrictions
- **Organizational**: Team capacity, skill gaps

### Dependencies Section
What needs to happen first?
- "Data privacy review must be completed"
- "Export API implementation (prd-XXX) must be finished"

### Risks Section
What could go wrong?
- Document: Risk description, likelihood (High/Med/Low), impact (High/Med/Low), and mitigation strategy

### Acceptance Criteria Section
Define "done" from a business perspective (3-5 criteria):
```
1. Users can select data types to export (users, transactions, settings)
2. Exports complete within 2 minutes for datasets up to 100MB
3. Exported data is usable in common formats (CSV, JSON)
4. Users receive email confirmation when export is ready
5. Exported data is securely deleted after 7 days
```

### Success Metrics Section
How will you measure success after launch?

| Metric | Current Baseline | Target | Measurement Method |
|--------|------------------|--------|-------------------|
| % of power users using export | 0% | 40% | Product analytics |
| Average export time | N/A | < 2 min | Server logs |
| Support tickets about exports | TBD | < 5/week | Support system |
| User satisfaction (export feature) | N/A | > 4/5 stars | In-app survey |

### Time to Value
When do you expect to see results?
- Example: "We expect 20% adoption within the first 2 weeks post-launch based on similar features"

### Approval Section
Track who has approved this requirement:
- Business Owner approval needed before engineering begins
- Product Owner approval to confirm alignment
- Technical Lead approval to confirm feasibility

## Writing Tips

### Be Specific, Not Vague
- ❌ Bad: "Users want to export their data"
- ✅ Good: "Users want to export their transaction history as CSV within a specific date range"

### Use Concrete Examples
- Describe what the feature looks like in action
- Include sample data or screenshots if possible
- Give edge cases (what about large datasets? special characters? time zones?)

### Consider the User's Perspective
- Think about: What problem are they solving with this?
- What would make them happy or frustrated?
- What alternatives might they use if you don't build this?

### Link to Other Specs
- Reference related technical requirements (if they exist): "See [prd-XXX] for implementation details"
- Reference related design docs: "See [des-XXX] for the export flow architecture"

### Complete All TODOs
- Don't leave placeholder text like "TODO: Add metrics"
- If something isn't known, explain why and what needs to happen to find out

## Validation & Fixing Issues

### Run the Validator
```bash
scripts/validate-spec.sh docs/specs/business-requirement/brd-001-your-spec.md
```

The validator checks for:
- Title and ID properly formatted
- All required sections present
- Minimum content in critical sections
- No incomplete TODO items

### Common Issues & Fixes

**Issue**: "Missing Acceptance Criteria section"
- **Fix**: Add 3-5 clear, measurable acceptance criteria that define what "done" means

**Issue**: "User Stories only has 1-2 items (minimum 3)"
- **Fix**: Add 1-2 more user stories representing different roles or scenarios

**Issue**: "TODO items in Business Value (3 items)"
- **Fix**: Complete the Business Value section with actual expected outcomes and strategic alignment

**Issue**: "No Success Metrics defined"
- **Fix**: Add a table with specific, measurable KPIs you'll track post-launch

### Check Completeness
```bash
scripts/check-completeness.sh docs/specs/business-requirement/brd-001-your-spec.md
```

This shows:
- Overall completion percentage
- Which sections still have TODOs
- Referenced documents (if any are broken, they show up here)

## Decision-Making Framework

When writing the BRD, reason through these questions:

1. **Problem**: Is this a real problem or a nice-to-have?
   - Can you trace it back to actual user feedback?
   - How many users are affected?
   - How often do they encounter this problem?

2. **Scope**: What are we NOT building?
   - Define boundaries clearly (what's in scope vs. out of scope)
   - This helps prevent scope creep

3. **Trade-offs**: What are we accepting by building this?
   - Engineering effort cost
   - Opportunity cost (what else won't we build?)
   - Maintenance burden

4. **Success**: How will we know if this was worth building?
   - What metrics matter?
   - What's the acceptable threshold for success?

5. **Risks**: What could prevent this from working?
   - Technical risks
   - User adoption risks
   - Business/market risks

## Example: Complete Business Requirement

Here's how a complete BRD section might look:

```markdown
# [BRD-001] Bulk User Data Export

## Metadata
- **Document ID**: BRD-001-bulk-export
- **Status**: Approved
- **Author**: Jane Smith
- **Created**: 2024-01-15
- **Stakeholders**: Product Manager (Jane), Engineering Lead (Bob), Support (Maria)
- **Priority**: High

## Description

### Background
Our enterprise customers have requested the ability to bulk export user data.
Currently, they can only export one user at a time via the admin panel, which is
time-consuming for customers with hundreds of users.

### Problem Statement
Enterprise customers need to audit, back up, and migrate user data, but the
current one-at-a-time export process takes hours and is error-prone.

## Business Value

### Expected Outcomes
- Reduce manual export time for enterprise customers by 80%
- Enable customers to audit user data for compliance purposes
- Support customer data portability requests

### Strategic Alignment
Aligns with our enterprise expansion goal by improving features our target
customers need for large-scale deployments.

[... rest of sections follow template ...]
```

## Next Steps

1. **Create the spec**: `scripts/generate-spec.sh business-requirement brd-XXX-slug`
2. **Fill in each section** using this guide as reference
3. **Validate**: `scripts/validate-spec.sh docs/specs/business-requirement/brd-XXX-slug.md`
4. **Fix issues** identified by the validator
5. **Get stakeholder approval** (fill in the Approval section)
6. **Share with engineering** for technical requirement creation