| name | requirement-analysis |
| description | Protocol and template for analyzing feature requests and producing structured requirement documents. Guides the BA agent through discovery, clarification, research, drafting, and validation phases. Output is a markdown document that team-lead and workers can read to understand exactly what to build. |
| user-invokable | false |
Requirement Analysis Protocol
When you receive a feature request, follow this protocol to produce a structured
requirement document before any development begins.
Phase 1: Discover
Understand the request and current codebase state before asking questions.
- Read the feature request — identify the core intent, not just surface words
- Explore the codebase — use Glob, Grep, Read to understand:
- What related features already exist?
- What entities/models are involved?
- What API endpoints exist in this area?
- What UI components could be reused?
- Check Apidog MCP — query for existing API specs related to this feature
- Note gaps — what's unclear, ambiguous, or missing from the request?
Phase 2: Clarify
Ask the user targeted questions to fill gaps. Rules:
- 1-2 questions at a time — never overwhelm with a wall of questions
- Prefer multiple choice — easier for users to answer than open-ended
- Show your reasoning — explain why you're asking (what depends on the answer)
- Skip obvious questions — if the codebase already answers it, don't ask
- Iterate — ask follow-ups based on answers, don't front-load all questions
Common areas to clarify:
- User roles and permissions (who can do this?)
- Edge cases (what happens when X is empty/max/invalid?)
- Business rules (pricing logic, quantity limits, approval workflows)
- Scope boundaries (what's in v1 vs later?)
- Integration points (third-party services, existing features affected)
Phase 3: Research
Deep-dive into technical feasibility based on clarified requirements.
- Map to existing code — which files/modules will be affected?
- Identify reusable patterns — existing components, services, types to leverage
- Check for conflicts — will this feature change existing behavior?
- Assess data model impact — new tables? New fields on existing models?
- Verify Apidog specs — do existing contracts need updates?
Phase 4: Draft
Write the requirement document using the template below. Save to:
docs/requirements/REQ-<NNN>-<short-description>.md
Naming convention:
NNN = sequential number (001, 002, ...)short-description = kebab-case, 2-4 words- Examples:
REQ-001-product-reviews.md, REQ-002-bulk-ordering.md
If docs/requirements/ doesn't exist, create it.
Phase 5: Validate
Present the completed document to the user for review.
- Summarize key decisions — highlight the most important choices made
- Flag assumptions — anything you assumed without explicit confirmation
- Ask for approval — user must confirm before handing off to team-lead
- Iterate if needed — revise sections based on feedback
After approval, tell the user:
Requirement document saved to docs/requirements/REQ-<NNN>-<description>.md.
To start development, invoke team-lead: /agent team-lead
Requirement Document Template
Use this exact structure. Scale each section to its complexity — a few sentences
if straightforward, detailed if nuanced. Omit sections only if truly not applicable
(mark as "N/A — [reason]").
# REQ-<NNN>: <Feature Title>
**Status**: Draft | Approved | In Development | Done
**Created**: <YYYY-MM-DD>
**Author**: business-analyst
---
## 1. Context & Background
[Why this feature is needed. What problem it solves. What prompted the request.
Reference any existing features or user feedback that led to this.]
## 2. User Stories
- As a [role], I want [action], so that [benefit].
- As a [role], I want [action], so that [benefit].
## 3. Acceptance Criteria
For each user story, define testable criteria:
### Story: [story title]
- **Given** [precondition], **when** [action], **then** [expected result].
- **Given** [precondition], **when** [action], **then** [expected result].
## 4. Domain Model
Entities and relationships affected by this feature:
| Entity | New/Modified | Key Fields | Relationships |
| ------ | -------------- | ------------------ | -------------------------- |
| [name] | [new/modified] | [field: type, ...] | [belongs to X, has many Y] |
## 5. API Contracts
Endpoints needed (reference Apidog specs where they exist):
| Method | Path | Request Body | Response | Notes |
| -------------- | ---------- | -------------- | -------- | -------------------------- |
| [GET/POST/...] | [/api/...] | [shape or N/A] | [shape] | [new/existing, Apidog ref] |
## 6. UI/UX Requirements
Screens and interactions:
- **[Screen name]**: [description of what the user sees and can do]
- **[Screen name]**: [description]
Key interactions:
- [interaction description — e.g., "clicking Add to Cart shows confirmation toast"]
## 7. Business Rules
| Rule | Description | Example |
| ---- | ------------------ | --------------------------------------------- |
| [ID] | [rule description] | [concrete example showing the rule in action] |
## 8. Technical Considerations
- **Dependencies**: [new packages, services, or infrastructure needed]
- **Migrations**: [database schema changes required]
- **Performance**: [any performance concerns or requirements]
- **Security**: [authentication, authorization, data protection needs]
## 9. Risk Assessment
| Risk | Likelihood | Impact | Mitigation |
| ------------------ | -------------- | -------------- | ----------------- |
| [risk description] | [Low/Med/High] | [Low/Med/High] | [how to mitigate] |
## 10. Out of Scope
Explicitly excluded from this feature (may be addressed later):
- [item 1 — reason for exclusion]
- [item 2 — reason for exclusion]
Quality Checklist
Before finalizing the document, verify:
