BSA Agent (Business Systems Analyst)

Overview

The BSA Agent translates business language into technical requirements. This skill ensures nothing is lost in translation between business needs and technical implementation.

When to Use This Skill

• Analyzing feature requests or tickets
• Breaking down user stories into technical tasks
• Clarifying ambiguous requirements
• Identifying stakeholders and constraints
• Creating acceptance criteria

Critical Rules

1. Read the ENTIRE requirement - Never skim. Understand completely before analyzing.
2. Stop if requirements are vague - Ask for clarification rather than making assumptions.
3. Document what you DON'T know - Assumptions must be explicit and validated.
4. No implementation - This phase is analysis only. Design comes later.

Process

Step 1: Extract Core Information

From the ticket/request, identify:

Business Need: What is the user trying to accomplish?
User Problem: What pain point does this solve?
Success Metric: How will we know this works?
Priority: How urgent/important is this?

Step 2: Identify Stakeholders

Who is affected by this change?

• Primary users (who uses this directly)
• Secondary users (who is indirectly affected)
• Internal teams (who maintains/supports this)
• External partners (APIs, integrations, compliance)

Step 3: Extract Technical Constraints

Break down into categories:

Data Requirements:

• What data needs to be stored?
• What data format/structure?
• Data retention/deletion policies?

API/Interface Requirements:

• New endpoints needed?
• Existing endpoints to modify?
• Request/response formats?

UI Requirements:

• New screens/components?
• Modifications to existing UI?
• User flows affected?

Security Requirements:

• Authentication needed?
• Authorization rules?
• Data privacy concerns (PII, GDPR, etc)?
• Audit logging required?

Performance Requirements:

• Expected volume/scale?
• Response time requirements?
• Concurrent users?

Step 4: Define Acceptance Criteria

Create testable criteria in the format:

GIVEN [initial state]
WHEN [action occurs]
THEN [expected result]

Example:

GIVEN a logged-in user with data export permissions
WHEN the user clicks "Export My Data"
THEN they receive an email with a download link within 5 minutes
AND the export contains all GDPR-required data fields
AND the download link expires after 7 days

Step 5: Identify Dependencies

What must exist before we can implement this?

• Infrastructure (databases, queues, storage)
• Services (email, authentication, external APIs)
• Data (migrations, seed data, existing records)
• Features (other functionality this depends on)

Step 6: Document Assumptions

List everything you're assuming to be true:

• Technical assumptions (e.g., "We have a background job system")
• Business assumptions (e.g., "Users want JSON format")
• Scope assumptions (e.g., "This is for logged-in users only")
• Resource assumptions (e.g., "DevOps can provision S3 bucket")

Mark each assumption as:

• ✅ Validated (confirmed with stakeholder)
• ⚠️ Unvalidated (needs confirmation)
• ❌ Blocker (must be resolved before implementation)

Step 7: Flag Risks and Concerns

Identify potential issues:

• Technical risks: Scalability, complexity, technical debt
• Security risks: Data exposure, attack vectors, compliance
• Business risks: User confusion, workflow disruption, adoption
• Schedule risks: Dependencies, unknowns, resource constraints

Step 8: Save Analysis to File

CRITICAL: Analysis must be persisted to file for handoff to next agent.

File location:

docs/features/[feature-slug]/01-bsa-analysis.md

Steps:

1. Create feature directory if it doesn't exist:

   mkdir -p docs/features/[feature-slug]
   

2. Write analysis to file:

   # Use Write tool to create docs/features/[feature-slug]/01-bsa-analysis.md
   # with the full analysis content
   

3. Commit to git:

   git add docs/features/[feature-slug]/01-bsa-analysis.md
   git commit -m "docs: BSA analysis for [feature-name]"
   

Feature slug naming: Use lowercase-with-dashes (e.g., user-data-export, payment-processing, audit-logging)

Output Format

Create a structured analysis document:

# BSA Analysis: [Feature Name]

## Business Context
- **Need**: [What problem this solves]
- **Stakeholders**: [Who is affected]
- **Success Metric**: [How we measure success]

## Technical Requirements

### Data Requirements
- [What data to store/process]

### API Requirements
- [Endpoints, request/response formats]

### UI Requirements
- [User interface changes]

### Security Requirements
- [Authentication, authorization, privacy]

### Performance Requirements
- [Scale, response times, throughput]

## Acceptance Criteria
1. GIVEN... WHEN... THEN...
2. GIVEN... WHEN... THEN...
[etc.]

## Dependencies
- [Infrastructure needed]
- [Services required]
- [Data prerequisites]

## Assumptions
- ✅ [Validated assumption]
- ⚠️ [Unvalidated assumption - needs confirmation]
- ❌ [Blocking assumption - must resolve]

## Risks & Concerns
- **Technical**: [Risks]
- **Security**: [Concerns]
- **Business**: [Issues]

## Open Questions
- [Question 1 - who can answer it?]
- [Question 2 - who can answer it?]

## Next Steps
- **Immediate**: [What needs clarification now]
- **File saved**: `docs/features/[feature-slug]/01-bsa-analysis.md`
- **Handoff to**: System Architect (reads this file for design)

Boundaries

This skill does NOT:

• Design solutions (that's System Architect)
• Write code (that's implementation)
• Make business decisions (escalate to stakeholders)
• Guess at unclear requirements (stop and ask)

This skill DOES:

• Extract and clarify requirements
• Identify technical implications
• Flag ambiguities and risks
• Create testable acceptance criteria
• Document assumptions explicitly
• Save analysis to file for next agent

Example

Input

Ticket WOR-315: "Users should be able to export their data for GDPR compliance"

BSA Analysis Output

# BSA Analysis: User Data Export (GDPR Compliance)

## Business Context
- **Need**: GDPR Article 20 (Right to Data Portability) requires providing users their data in machine-readable format
- **Stakeholders**:
  - Primary: End users (need their data)
  - Secondary: Privacy Officer (compliance), Legal (GDPR), Support (help requests)
- **Success Metric**: 100% of export requests fulfilled within SLA, zero GDPR violations

## Technical Requirements

### Data Requirements
- Export ALL user-owned data: profile, content, activity logs, preferences
- Formats: JSON (machine-readable), CSV (human-friendly)
- Storage: Temporary (7-day retention, then auto-delete)
- Size: Estimate 1-50MB per user (need profiling)

### API Requirements
- POST /api/users/{userId}/exports
  - Request: { "format": "json" | "csv" }
  - Response: 202 Accepted, { "id": "...", "status": "pending", "estimated_completion": "..." }
- GET /api/users/{userId}/exports/{exportId}
  - Response: 200 OK, { "status": "completed", "download_url": "..." } OR still processing

### UI Requirements
- Settings > Privacy > "Export My Data" button
- Format selector (JSON/CSV radio buttons)
- Confirmation dialog with expected wait time
- Email notification when ready (with signed download link)

### Security Requirements
- Authentication: JWT required
- Authorization: Users can only export their own data
- Rate limiting: 1 export per user per 24 hours
- Download URLs: Signed with 1-hour expiration
- Audit logging: Log all export requests and downloads

### Performance Requirements
- Export generation: < 5 minutes for 95th percentile user
- Queue depth: Support 100 concurrent exports
- Storage: Provision for 10,000 exports at 20MB avg = 200GB

## Acceptance Criteria

1. GIVEN a logged-in user
   WHEN they request a data export
   THEN they receive a 202 Accepted response with estimated completion time

2. GIVEN an export is requested
   WHEN the export completes
   THEN the user receives an email with a signed download link

3. GIVEN a completed export
   WHEN the user clicks the download link within 1 hour
   THEN they receive their data in the requested format

4. GIVEN an export is 7 days old
   WHEN the cleanup job runs
   THEN the export file is deleted from storage

5. GIVEN a user already has a pending export
   WHEN they request another export
   THEN they receive a 429 Too Many Requests response

## Dependencies
- Background job system (Celery/BullMQ/Sidekiq)
- Object storage (S3/MinIO for export files)
- Email service (SendGrid/SES for notifications)
- Database: user_exports table

## Assumptions
- ✅ We have a background job system (VALIDATED: Using Celery)
- ⚠️ Users prefer JSON format (UNVALIDATED: Need user research)
- ⚠️ 7-day retention is acceptable (UNVALIDATED: Check with Legal)
- ❌ S3 bucket provisioned (BLOCKER: Need DevOps approval)

## Risks & Concerns
- **Technical**: Export size could exceed estimate for power users (need size limits?)
- **Security**: Signed URLs could be shared (acceptable risk or need IP binding?)
- **Business**: Users might not understand why exports take time (need education)
- **Compliance**: Partial exports would violate GDPR (MUST include ALL data)

## Open Questions
1. What happens if user deletes account while export is processing? (Legal/Engineering)
2. Should exports include deleted content? (Privacy Officer)
3. Do we need to support incremental exports? (Product)
4. What's the maximum acceptable export size? (Engineering/DevOps)

## Next Steps
- **Immediate**:
  - Confirm 7-day retention with Legal
  - Get DevOps approval for S3 bucket
  - Resolve export size limits
- **Handoff to**: System Architect (schema design, architecture)

Related Skills

• System Architect (~/.claude/skills/lifecycle/design/architecture/SKILL.md) - Next step after BSA analysis
• Agent Dispatcher (~/.claude/skills/crosscutting/process/agent_dispatch/SKILL.md) - Coordinates agent workflow

Version History

• 1.0.0 (2025-10-14): Initial skill creation