12 KiB

Raw Blame History

Create Next Story Task

Purpose

To identify the next logical story based on project progress and epic definitions, and then to prepare a comprehensive, self-contained, and actionable story file using the Story Template. This task ensures the story is enriched with all necessary technical context, requirements, and acceptance criteria, making it ready for efficient implementation by a Developer Agent with minimal need for additional research.

Inputs for this Task

Access to the project's documentation repository, specifically:
- docs/index.md (hereafter "Index Doc")
- All Epic files - located in one of these locations:
  - Primary: docs/prd/epic-{n}-{description}.md (e.g., epic-1-foundation-core-infrastructure.md)
  - Secondary: docs/epics/epic-{n}-{description}.md
  - User-specified location if not found in above paths
- Existing story files in docs/stories/
- Full-Stack Architecture Document (docs/full-stack-architecture.md)
- UI/UX Specification Document (docs/ui-ux-spec.md)
The .bmad-core/templates/story-tmpl.md (hereafter "Story Template")
The .bmad-core/checklists/story-draft-checklist.md (hereafter "Story Draft Checklist")
User confirmation to proceed with story identification and, if needed, to override warnings about incomplete prerequisite stories.

Task Execution Instructions

1. Identify Next Story for Preparation

1.1 Locate Epic Files

First, determine where epic files are located:
- Check docs/prd/ for files matching pattern epic-{n}-*.md
- If not found, check docs/epics/ for files matching pattern epic-{n}-*.md
- If still not found, ask user: "Unable to locate epic files. Please specify the path where epic files are stored."
Note: Epic files follow naming convention epic-{n}-{description}.md (e.g., epic-1-foundation-core-infrastructure.md)

1.2 Review Existing Stories

Review docs/stories/ to find the highest-numbered story file.
If a highest story file exists ({lastEpicNum}.{lastStoryNum}.story.md):
- Verify its Status is 'Done' (or equivalent).
- If not 'Done', present an alert to the user:
```
ALERT: Found incomplete story:
File: {lastEpicNum}.{lastStoryNum}.story.md
Status: [current status]

Would you like to:
1. View the incomplete story details (instructs user to do so, agent does not display)
2. Cancel new story creation at this time
3. Accept risk & Override to create the next story in draft

Please choose an option (1/2/3):
```
- Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
- If proceeding: Look for the Epic File for {lastEpicNum} (e.g., epic-{lastEpicNum}-*.md) and check for a story numbered {lastStoryNum + 1}. If it exists and its prerequisites (per Epic File) are met, this is the next story.
- Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for epic-{lastEpicNum + 1}-*.md, then epic-{lastEpicNum + 2}-*.md, etc.) whose prerequisites are met.
If no story files exist in docs/stories/:
- The next story is the first story in the first epic file (look for epic-1-*.md, then epic-2-*.md, etc.) whose prerequisites are met.
If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".

2. Gather Core Story Requirements (from Epic File)

For the identified story, open its parent Epic File (e.g., epic-{epicNum}-*.md from the location identified in step 1.1).
Extract: Exact Title, full Goal/User Story statement, initial list of Requirements, all Acceptance Criteria (ACs), and any predefined high-level Tasks.
Keep a record of this original epic-defined scope for later deviation analysis.

3. Review Previous Story and Extract Dev Notes

LLM: This step is CRITICAL for continuity and learning from implementation experience

If this is not the first story (i.e., previous story exists):
- Read the previous story file: docs/stories/{prevEpicNum}.{prevStoryNum}.story.md
- Pay special attention to:
  - Dev Agent Record sections (especially Completion Notes and Debug Log References)
  - Any deviations from planned implementation
  - Technical decisions made during implementation
  - Challenges encountered and solutions applied
  - Any "lessons learned" or notes for future stories
- Extract relevant insights that might inform the current story's preparation

4. Gather & Synthesize Architecture Context from Consolidated Documentation

LLM: CRITICAL - You MUST gather technical details from the consolidated architecture document. NEVER make up technical details not found in this document.

4.1 Review Full-Stack Architecture Document

Read docs/full-stack-architecture.md to understand the complete system architecture
Extract relevant sections based on story type:
- Tech Stack section - Technology constraints and versions
- Data Models section - Data structures and validation rules
- REST API Spec section - API endpoint specifications
- Components section - UI component specifications
- Database Schema section - Database design and relationships
- Frontend Architecture section - Component structure and patterns
- Backend Architecture section - Service patterns and structure
- Testing Strategy section - Testing requirements and strategies

4.2 Review UI/UX Specification (For Frontend Stories)

For stories involving UI components, user flows, or frontend functionality:
- Read docs/ui-ux-spec.md to understand design requirements and user experience patterns
- Extract relevant sections:
  - User Personas & Use Cases - Understanding target users and their workflows
  - Design System & Visual Language - Component styling and design patterns
  - Core User Flows & Interaction Patterns - Specific user journey requirements
  - Component Library Specification - Detailed component requirements and props
  - Accessibility Implementation - WCAG compliance and accessibility requirements
  - Responsive Design Strategy - Mobile-first design patterns and breakpoints
Skip this step for backend-only stories with no UI components

4.3 Extract Story-Specific Technical Details

LLM: As you read the document, extract ONLY the information directly relevant to implementing the current story. Do NOT include general information unless it directly impacts the story implementation.

For Backend Stories: Focus on service architecture, data models, API specs, database schema For Frontend Stories: Focus on component architecture, state management, routing, UI specifications For Full-Stack Stories: Extract relevant information from both domains

For the current story, extract:

Specific data models, schemas, or structures the story will use
API endpoints the story must implement or consume
Component specifications for UI elements in the story
File paths and naming conventions for new code
Testing requirements specific to the story's features
Security or performance considerations affecting the story

4.4 Document Source References

LLM: ALWAYS cite the source document and section for each technical detail you include. This helps the dev agent verify information if needed.

Format references as: [Source: full-stack-architecture.md#{section}] or [Source: ui-ux-spec.md#{section}] Examples:

[Source: full-stack-architecture.md#tech-stack-section]
[Source: ui-ux-spec.md#component-library-specification]

5. Verify Project Structure Alignment

Cross-reference the story's requirements and anticipated file manipulations with the project structure information from docs/full-stack-architecture.md.
Ensure any file paths, component locations, or module names implied by the story align with defined structures.
Document any structural conflicts, necessary clarifications, or undefined components/paths in a "Project Structure Notes" section within the story draft.

6. Populate Story Template with Full Context

Create a new story file: docs/stories/{epicNum}.{storyNum}.story.md.
Use the Story Template to structure the file.
Fill in:
- Story {EpicNum}.{StoryNum}: {Short Title Copied from Epic File}
- Status: Draft
- Story (User Story statement from Epic)
- Acceptance Criteria (ACs) (from Epic, to be refined if needed based on context)
Dev Technical Guidance section (CRITICAL):

LLM: This section MUST contain ONLY information extracted from the architecture and UI/UX specification documents. NEVER invent or assume technical details.
- Include ALL relevant technical details gathered from Steps 3 and 4, organized by category:
  - Previous Story Insights: Key learnings or considerations from the previous story
  - Architecture Context: Relevant patterns and constraints [Source: full-stack-architecture.md#{relevant-section}]
  - Tech Stack Requirements: Specific technologies and versions [Source: full-stack-architecture.md#{tech-stack-section}]
  - Data Models: Specific schemas, validation rules, relationships [Source: full-stack-architecture.md#{data-models-section}]
  - API Specifications: Endpoint details, request/response formats, auth requirements [Source: full-stack-architecture.md#{api-spec-section}]
  - Component Specifications: UI component details, props, state management [Source: full-stack-architecture.md#{frontend-architecture-section}]
  - UI/UX Requirements: Design system requirements, user flows, accessibility requirements [Source: ui-ux-spec.md#{relevant-section}] (for frontend stories)
  - File Locations: Exact paths where new code should be created based on project structure
  - Testing Requirements: Specific test cases or strategies [Source: full-stack-architecture.md#{testing-strategy-section}]
  - Technical Constraints: Version requirements, performance considerations, security rules
- Every technical detail MUST include its source reference: [Source: full-stack-architecture.md#{section}] or [Source: ui-ux-spec.md#{section}]
- If information for a category is not found in the architecture docs, explicitly state: "No specific guidance found in architecture docs"
Tasks / Subtasks section:
- Generate a detailed, sequential list of technical tasks based ONLY on:
  - Requirements from the Epic
  - Technical constraints from full-stack-architecture.md
  - Testing requirements from full-stack-architecture.md testing strategy section
- Each task must reference relevant architecture documentation
- Include unit testing as explicit subtasks based on testing strategy
- Link tasks to ACs where applicable (e.g., Task 1 (AC: 1, 3))
Add notes on project structure alignment or discrepancies found in Step 5.
Prepare content for the "Deviation Analysis" based on any conflicts between epic requirements and architecture constraints.

7. Run Story Draft Checklist

Execute the Story Draft Checklist against the prepared story
Document any issues or gaps identified
Make necessary adjustments to meet quality standards
Ensure all technical guidance is properly sourced from architecture and UI/UX specification docs

8. Finalize Story File

Review all sections for completeness and accuracy
Verify all source references are included for technical details
Ensure tasks align with both epic requirements and architecture constraints
Update status to "Draft"
Save the story file to docs/stories/{epicNum}.{storyNum}.story.md

9. Report Completion

Provide a summary to the user including:

Story created: {epicNum}.{storyNum} - {Story Title}
Status: Draft
Key technical components included from full-stack-architecture.md and ui-ux-spec.md (if applicable)
Any deviations or conflicts noted between epic requirements and architecture constraints
Recommendations for story review before approval
Next steps: Story should be reviewed by PO for approval before dev work begins

LLM: Remember - The success of this task depends on extracting real, specific technical details from the consolidated full-stack-architecture.md document and ui-ux-spec.md (for frontend stories). The dev agent should have everything they need in the story file without having to search through multiple documents.

12 KiB Raw Blame History