--- id: onboard.analyze-requirements version: 2.0.0 category: onboard experimental: true name: Analyze Requirements description: Generic requirements analysis for PRD generation or backlog decomposition tags: - requirements-analysis - user-stories - complexity-estimation model_requirements: min_context: 128000 recommended: - gpt-5.5 agents: - product-manager dependencies: requires: - context.use-modern-cli-tools inputs: - name: source_document description: Source document to analyze (specifications or PRD) type: object required: true - name: source_type description: Type of source being analyzed type: string required: true validation: enum: ['specifications', 'prd'] - name: project_type description: Project type (greenfield, brownfield, etc.) type: string required: false - name: granularity description: Analysis granularity (for backlog context) type: string required: false validation: enum: ['fine', 'medium', 'coarse'] outputs: - requirement_analysis - complexity_estimate - user_stories - dependency_graph - complexity_map - traceability_matrix tokens: avg: 5000 max: 10000 min: 3000 --- # Analyze Requirements ## Objective Analyze requirements from different sources to produce user stories, complexity estimates, and dependency mapping. ## CRITICAL: Output Format Requirement **You MUST output ONLY valid JSON. Do NOT output markdown, do NOT wrap in code blocks, do NOT add any text before or after the JSON.** Your response must be a single JSON object matching the schema defined in the "Output Format" section at the end of this prompt. ## Context Awareness Based on `source_type` parameter: **"specifications"** (PRD Creation Context): - Input: Raw specifications or user-provided requirements - Goal: Transform into structured requirements for PRD document - Output depth: Foundational analysis (identify requirements, categorize, estimate) - Next stage: PRD generation **"prd"** (Backlog Creation Context): - Input: Existing PRD with structured requirements (FR-XXX, NFR-XXX, US-XXX) - Goal: Enrich requirements with analysis for task decomposition - Output depth: Detailed analysis (dependencies, complexity, technical implications) - Next stage: Task breakdown --- ## Instructions ### Step 0: Determine Analysis Approach Based on `source_type`: **If source_type = "specifications"**: - Extract requirements from unstructured or semi-structured specs - Create requirement IDs (FR-001, FR-002, etc.) - Focus on identification and categorization - Generate initial user stories **If source_type = "prd"**: - Requirements already structured with IDs - Focus on dependency mapping and complexity analysis - Validate/enhance existing user stories - Identify technical requirements in detail --- ### Step 1: Extract or Load Requirements **If source_type = "specifications"**: Parse `source_document` to extract requirements: - Identify all functional requirements (what the system should do) - Identify non-functional requirements (performance, security, scalability) - Identify user needs and personas - Assign IDs: FR-001, FR-002... (functional), NFR-001, NFR-002... (non-functional) - Extract or infer priorities (P0, P1, P2) **If source_type = "prd"**: Load structured requirements from `source_document`: - `source_document.requirements_list.functional` - All FR-XXX items - `source_document.requirements_list.non_functional` - All NFR-XXX items - `source_document.requirements_list.user_stories` - All US-XXX items (if present) - Requirements already have IDs and priorities --- ### Step 2: Categorize Requirements by Domain Organize requirements into functional domains: **Domains**: 1. **Frontend**: UI/UX, components, interactions, responsive design 2. **Backend**: APIs, business logic, data processing, integrations 3. **Data**: Models, schemas, migrations, persistence, queries 4. **Infrastructure**: Deployment, scaling, monitoring, security, DevOps 5. **Testing**: Coverage strategies, automation, test types 6. **Documentation**: User guides, API docs, architecture diagrams **For each requirement**: - Assign primary domain - Identify secondary domains if cross-cutting - Note if requirement spans multiple domains (integration points) **Example categorization**: ```text FR-001: "Create and assign tasks" - Primary domain: Backend (API endpoint, business logic) - Secondary domains: Frontend (UI form), Data (task model) ``` ### Step 3: Generate or Enhance User Stories **If source_type = "specifications"**: For each P0 and P1 functional requirement, create user stories from scratch: **Format**: "As a [user type], I want to [action], so that [benefit]" **Guidelines**: - Be specific about user type (from personas) - Use action verbs (create, view, update, delete, search, etc.) - Articulate clear benefit (why this matters) - Keep stories atomic (single feature/capability) - Ensure stories are independently valuable **Example**: ```markdown FR-001: Create and assign tasks **User Story 1.1**: As a team lead, I want to create new tasks with title, description, and deadline, so that I can organize work for my team. **User Story 1.2**: As a team lead, I want to assign tasks to specific team members, so that everyone knows their responsibilities. **User Story 1.3**: As a team member, I want to see tasks assigned to me, so that I know what work I need to complete. ``` **Multiple users**: - Create separate stories for different user types - E.g., "As an admin..." vs. "As a standard user..." **Complex requirements**: - Break into multiple stories - Each story should be deliverable in 1-2 sprints **If source_type = "prd"**: User stories may already exist in `source_document.requirements_list.user_stories`: - **If present**: Validate and enhance existing stories (add missing details, improve clarity) - **If missing or incomplete**: Generate stories for requirements that lack them - **Focus on P0 requirements first**, then P1 --- ### Step 4: Define Acceptance Criteria For each user story, define clear, testable acceptance criteria: **Format**: Use Given-When-Then or scenario-based **Given-When-Then**: ```text Given [initial context] When [action occurs] Then [expected outcome] ``` **Example**: ```markdown **User Story 1.1 Acceptance Criteria**: 1. Given I am a logged-in team lead When I click "New Task" and fill in title, description, deadline Then a new task is created and appears in the task list 2. Given I am creating a task When I leave the title field empty Then I see an error "Title is required" 3. Given I created a task with a deadline When the deadline is reached Then the task is highlighted as overdue ``` **Checklist format** (alternative): ```markdown - [ ] User can create task with title, description, deadline - [ ] Title is required (error shown if empty) - [ ] Description is optional - [ ] Deadline must be future date - [ ] Task appears in list immediately after creation - [ ] Overdue tasks are highlighted ``` **Coverage**: - Happy path (normal flow) - Edge cases (empty fields, invalid data) - Error scenarios (network failure, validation errors) - Non-functional aspects (performance, accessibility) ### Step 5: Estimate Complexity For each requirement, estimate complexity: **Complexity levels**: 1. **Simple** (1 point): - < 1 day - Single component - No dependencies - Well-understood pattern - Examples: UI label change, simple form, basic CRUD 2. **Medium** (3 points): - 1-3 days - Multiple components (2-4) - Some dependencies - Moderate complexity - Examples: Integration with external API, multi-step form, report generation 3. **Complex** (5 points): - 3-5 days - Many components (5+) - Multiple dependencies - Cross-cutting concerns - Examples: Real-time features, complex algorithm, data migration 4. **Very Complex** (8 points): - > 5 days - System-wide impact - Many dependencies - High risk/uncertainty - Examples: Authentication system, multi-tenant architecture, performance optimization **Factors affecting complexity**: - Number of components involved - Dependencies on other requirements - Integration complexity - Data model changes - Performance/scalability challenges - Security considerations - Testing effort - Documentation needs **Total complexity**: ```plaintext Total Story Points = Sum of all requirement complexities ``` **Granularity consideration** (for source_type = "prd"): If `granularity` parameter is provided: - **fine**: Bias toward lower complexity scores (more granular breakdown expected) - **medium**: Balanced complexity assessment (default) - **coarse**: Bias toward higher complexity scores (epic-level tasks expected) --- ### Step 6: Map Dependencies Identify dependencies between requirements: **Dependency types**: 1. **Prerequisite**: A must be done before B - Example: "User authentication" before "Task assignment" 2. **Related**: A and B are related but order doesn't matter - Example: "Email notifications" and "In-app notifications" 3. **Blocking**: A blocks B (cannot proceed without A) - Example: "Database schema" blocks "API endpoints" 4. **External**: Depends on external system/team - Example: "Slack integration" depends on Slack API **Dependency graph**: Create adjacency list or matrix: ```text FR-001 (Create tasks) → [] (no dependencies) FR-002 (Assign tasks) → [FR-001] (requires task creation) FR-003 (Task notifications) → [FR-002] (requires assignments) FR-004 (Slack integration) → [FR-003] (requires notifications) ``` **Critical path**: - Identify longest dependency chain - Highlight requirements on critical path - These must be prioritized **Parallel work**: - Identify requirements with no dependencies - These can be worked on simultaneously - Optimize for parallelization **Dependency depth**: **If source_type = "specifications"**: - Focus on high-level dependencies between major requirements - Identify external dependencies early **If source_type = "prd"**: - Map detailed dependencies for task decomposition - Include soft dependencies and recommended sequences - Identify parallel work opportunities --- ### Step 7: Identify Technical Requirements Extract technical requirements implied by functional requirements: **API endpoints**: - List required endpoints - Define HTTP methods, paths, request/response formats - Example: `POST /api/tasks`, `GET /api/tasks/:id` **Database schema changes**: - New tables/collections - Schema migrations - Indexes required - Data relationships **Authentication/Authorization**: - Required permissions - Role-based access control (RBAC) - OAuth scopes - API key requirements **Integration points**: - External APIs to call - Webhooks to implement - Message queues - Event streams **Performance targets**: - Response time requirements - Throughput needs - Concurrent user support - Data volume expectations **Security requirements**: - Encryption (at rest, in transit) - Input validation - Rate limiting - Audit logging **Technical depth**: **If source_type = "specifications"**: - High-level technical requirements sufficient - Focus on major architectural decisions - Identify key technology choices **If source_type = "prd"**: - Detailed technical requirements for implementation - Specific API endpoints, schemas, integrations - Performance targets and security requirements - Infrastructure and deployment needs --- ### Step 8: Generate Complexity Estimate Aggregate complexity across all requirements: **By priority**: ```plaintext P0 (Must Have): X story points P1 (Should Have): Y story points P2 (Nice to Have): Z story points Total: X + Y + Z story points ``` **By domain**: ```plaintext Frontend: A points Backend: B points Data: C points Infrastructure: D points Testing: E points Documentation: F points ``` **Estimated timeline**: ```plaintext Assuming team velocity of V points/sprint: Minimum sprints = P0 points / V Expected sprints = (P0 + P1) points / V Maximum sprints = (P0 + P1 + P2) points / V ``` **Risk assessment**: - High complexity requirements (8 points): [count] - External dependencies: [count] - Critical path length: [count] requirements --- ### Step 9: Generate Requirements Traceability Matrix Create a comprehensive traceability matrix to ensure complete coverage and identify scope gaps. **Purpose**: - Verify every source requirement has corresponding user stories - Ensure all user stories have acceptance criteria - Map requirements to technical artefacts (APIs, database, integrations) - Identify orphaned artefacts or missing coverage - Prevent scope gaps through bi-directional tracing **Matrix Structure**: For each requirement, trace: 1. **Forward Traceability** (Source → Implementation): - Requirement ID → User Stories → Acceptance Criteria → Technical Artefacts 2. **Backward Traceability** (Implementation → Source): - Technical Artefact → User Story → Requirement ID **Coverage Analysis**: For each requirement, calculate coverage status: - **full**: All expected artefacts present (user stories, acceptance criteria, technical requirements) - **partial**: Some artefacts missing (e.g., user story exists but no acceptance criteria) - **missing**: No downstream artefacts created **Gap Detection**: Identify and report: 1. **Orphaned user stories**: Stories not linked to any requirement 2. **Requirements without stories**: Source requirements lacking user stories 3. **Stories without acceptance criteria**: User stories missing testable criteria 4. **Untraceable technical artefacts**: APIs/schemas not linked to requirements 5. **Cross-cutting gaps**: NFRs without implementation strategy **Traceability Depth**: **If source_type = "specifications"**: - Focus on requirement → user story mapping - Identify gaps early for PRD refinement - Flag ambiguous requirements needing clarification **If source_type = "prd"**: - Full traceability including technical artefacts - Validate completeness for task decomposition - Ensure every requirement has implementation path **Coverage Metrics**: ```plaintext Requirements Coverage: - Total requirements: N - Fully covered: X (X/N * 100%) - Partially covered: Y (Y/N * 100%) - Missing coverage: Z (Z/N * 100%) User Story Coverage: - Total user stories: M - With acceptance criteria: A (A/M * 100%) - Without acceptance criteria: B (B/M * 100%) Technical Coverage: - Requirements with API endpoints: P% - Requirements with database changes: Q% - Requirements with integration points: R% ``` --- ## Output Format **CRITICAL: Your response MUST be ONLY valid JSON. No markdown, no explanations, no prose. Just the JSON object.** The output schema is enforced by the pipeline via `outputs:` frontmatter. Produce a JSON object with the following top-level keys: - `requirement_analysis` — categorised requirements by domain with user stories, technical requirements, and acceptance criteria - `complexity_estimate` — point estimates by priority and domain, sprint timeline, and risk factors - `user_stories` — flat list of all user stories with requirement traceability - `dependency_graph` — requirement IDs mapped to their prerequisite requirement IDs - `complexity_map` — per-requirement complexity level, points, and risk rating - `traceability_matrix` — bi-directional requirement traces, coverage summary, and identified gaps ## Success Criteria - ✅ All P0/P1 requirements categorized by domain - ✅ User stories generated for each requirement - ✅ Acceptance criteria defined and testable - ✅ Complexity estimated for each requirement - ✅ Dependencies mapped - ✅ Technical requirements extracted - ✅ Total complexity calculated - ✅ Estimated timeline provided - ✅ Traceability matrix generated with full bi-directional tracing - ✅ Coverage gaps identified and documented - ✅ All requirements have minimum 70% coverage or gaps flagged ## Notes **Context-specific considerations**: **For source_type = "specifications"**: - Focus on requirement discovery and categorization - User stories provide foundation for PRD - Complexity estimates inform project scoping - Output feeds directly into PRD generation - Allow for some ambiguity (will be refined in PRD) **For source_type = "prd"**: - Requirements already structured - focus on enrichment - Dependency mapping critical for task ordering - Technical requirements guide implementation - Output feeds directly into task decomposition - Expect high level of detail and precision **Universal considerations**: - User stories should be reviewed with stakeholders - Complexity estimates are estimates - expect variance - Granularity parameter (when provided) guides analysis depth **Traceability matrix considerations**: - Review identified gaps with stakeholders before proceeding - High-severity gaps (requirement_without_stories) should block task decomposition - Medium-severity gaps (stories_without_criteria) can be addressed in parallel - Low-severity gaps (orphaned_artefact) are informational only - Coverage percentage below 70% indicates significant scope risk - Cross-cutting requirements (security, performance, accessibility) require explicit mapping ## REMINDER: Output Requirements **Output ONLY the JSON object. No markdown, no code blocks, no explanatory text. Start directly with `{` and end with `}`.**