211 lines
12 KiB
Markdown
211 lines
12 KiB
Markdown
# 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:
|
|
|
|
```plaintext
|
|
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.]]
|