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.

1. Read the feature request — identify the core intent, not just surface words
2. 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?
3. Check Apidog MCP — query for existing API specs related to this feature
4. 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.

1. Map to existing code — which files/modules will be affected?
2. Identify reusable patterns — existing components, services, types to leverage
3. Check for conflicts — will this feature change existing behavior?
4. Assess data model impact — new tables? New fields on existing models?
5. 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.

1. Summarize key decisions — highlight the most important choices made
2. Flag assumptions — anything you assumed without explicit confirmation
3. Ask for approval — user must confirm before handing off to team-lead
4. 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:

• Every User Story has at least 1 Acceptance Criteria
• Every entity in Domain Model is referenced in User Stories
• API Contracts are consistent with Apidog specs (if existing)
• Business Rules cover edge cases (empty states, limits, permissions)
• Out of Scope is explicit — no ambiguity about what's NOT included
• No implementation details in requirements (what, not how)
• Status is set to "Draft" until user approves