Initial commit
This commit is contained in:
Zhongwei Li
310
skills/spec-author/guides/business-requirement.md
Normal file
310
skills/spec-author/guides/business-requirement.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user