Create Brownfield Story Task

Purpose

Create detailed, implementation-ready stories for brownfield projects where traditional sharded PRD/architecture documents may not exist. This task bridges the gap between various documentation formats (document-project output, brownfield PRDs, epics, or user documentation) and executable stories for the Dev agent.

When to Use This Task

Use this task when:

Working on brownfield projects with non-standard documentation
Stories need to be created from document-project output
Working from brownfield epics without full PRD/architecture
Existing project documentation doesn't follow BMad v4+ structure
Need to gather additional context from user during story creation

Use create-next-story when:

Working with properly sharded PRD and v4 architecture documents
Following standard greenfield or well-documented brownfield workflow
All technical context is available in structured format

Task Execution Instructions

0. Documentation Context

Check for available documentation in this order:

Sharded PRD/Architecture (docs/prd/, docs/architecture/)
- If found, recommend using create-next-story task instead
Brownfield Architecture Document (docs/brownfield-architecture.md or similar)
- Created by document-project task
- Contains actual system state, technical debt, workarounds
Brownfield PRD (docs/prd.md)
- May contain embedded technical details
Epic Files (docs/epics/ or similar)
- Created by brownfield-create-epic task
User-Provided Documentation
- Ask user to specify location and format

1. Story Identification and Context Gathering

1.1 Identify Story Source

Based on available documentation:

From Brownfield PRD: Extract stories from epic sections
From Epic Files: Read epic definition and story list
From User Direction: Ask user which specific enhancement to implement
No Clear Source: Work with user to define the story scope

1.2 Gather Essential Context

CRITICAL: For brownfield stories, you MUST gather enough context for safe implementation. Be prepared to ask the user for missing information.

Required Information Checklist:

What existing functionality might be affected?
What are the integration points with current code?
What patterns should be followed (with examples)?
What technical constraints exist?
Are there any "gotchas" or workarounds to know about?

If any required information is missing, list the missing information and ask the user to provide it.

2. Extract Technical Context from Available Sources

2.1 From Document-Project Output

If using brownfield-architecture.md from document-project:

Technical Debt Section: Note any workarounds affecting this story
Key Files Section: Identify files that will need modification
Integration Points: Find existing integration patterns
Known Issues: Check if story touches problematic areas
Actual Tech Stack: Verify versions and constraints

2.2 From Brownfield PRD

If using brownfield PRD:

Technical Constraints Section: Extract all relevant constraints
Integration Requirements: Note compatibility requirements
Code Organization: Follow specified patterns
Risk Assessment: Understand potential impacts

2.3 From User Documentation

Ask the user to help identify:

Relevant technical specifications
Existing code examples to follow
Integration requirements
Testing approaches used in the project

3. Story Creation with Progressive Detail Gathering

3.1 Create Initial Story Structure

Start with the story template, filling in what's known:

# Story {{Enhancement Title}}

## Status: Draft

## Story

As a {{user_type}},
I want {{enhancement_capability}},
so that {{value_delivered}}.

## Context Source

- Source Document: {{document name/type}}
- Enhancement Type: {{single feature/bug fix/integration/etc}}
- Existing System Impact: {{brief assessment}}

3.2 Develop Acceptance Criteria

Critical: For brownfield, ALWAYS include criteria about maintaining existing functionality

Standard structure:

New functionality works as specified
Existing {{affected feature}} continues to work unchanged
Integration with {{existing system}} maintains current behavior
No regression in {{related area}}
Performance remains within acceptable bounds

3.3 Gather Technical Guidance

Critical: This is where you'll need to be interactive with the user if information is missing

Create Dev Technical Guidance section with available information:

## Dev Technical Guidance

### Existing System Context

[Extract from available documentation]

### Integration Approach

[Based on patterns found or ask user]

### Technical Constraints

[From documentation or user input]

### Missing Information

Critical: List anything you couldn't find that dev will need and ask for the missing information

### 4. Task Generation with Safety Checks

#### 4.1 Generate Implementation Tasks

Based on gathered context, create tasks that:

- Include exploration tasks if system understanding is incomplete
- Add verification tasks for existing functionality
- Include rollback considerations
- Reference specific files/patterns when known

Example task structure for brownfield:

```markdown
## Tasks / Subtasks

- [ ] Task 1: Analyze existing {{component/feature}} implementation
  - [ ] Review {{specific files}} for current patterns
  - [ ] Document integration points
  - [ ] Identify potential impacts

- [ ] Task 2: Implement {{new functionality}}
  - [ ] Follow pattern from {{example file}}
  - [ ] Integrate with {{existing component}}
  - [ ] Maintain compatibility with {{constraint}}

- [ ] Task 3: Verify existing functionality
  - [ ] Test {{existing feature 1}} still works
  - [ ] Verify {{integration point}} behavior unchanged
  - [ ] Check performance impact

- [ ] Task 4: Add tests
  - [ ] Unit tests following {{project test pattern}}
  - [ ] Integration test for {{integration point}}
  - [ ] Update existing tests if needed
```

5. Risk Assessment and Mitigation

CRITICAL: for brownfield - always include risk assessment

Add section for brownfield-specific risks:

## Risk Assessment

### Implementation Risks

- **Primary Risk**: {{main risk to existing system}}
- **Mitigation**: {{how to address}}
- **Verification**: {{how to confirm safety}}

### Rollback Plan

- {{Simple steps to undo changes if needed}}

### Safety Checks

- [ ] Existing {{feature}} tested before changes
- [ ] Changes can be feature-flagged or isolated
- [ ] Rollback procedure documented

6. Final Story Validation

Before finalizing:

Completeness Check:
- Story has clear scope and acceptance criteria
- Technical context is sufficient for implementation
- Integration approach is defined
- Risks are identified with mitigation
Safety Check:
- Existing functionality protection included
- Rollback plan is feasible
- Testing covers both new and existing features
Information Gaps:
- All critical missing information gathered from user
- Remaining unknowns documented for dev agent
- Exploration tasks added where needed

7. Story Output Format

Save the story with appropriate naming:

If from epic: docs/stories/epic-{n}-story-{m}.md
If standalone: docs/stories/brownfield-{feature-name}.md
If sequential: Follow existing story numbering

Include header noting documentation context:

# Story: {{Title}}

<!-- Source: {{documentation type used}} -->
<!-- Context: Brownfield enhancement to {{existing system}} -->

## Status: Draft

[Rest of story content...]

8. Handoff Communication

Provide clear handoff to the user:

Brownfield story created: {{story title}}

Source Documentation: {{what was used}}
Story Location: {{file path}}

Key Integration Points Identified:
- {{integration point 1}}
- {{integration point 2}}

Risks Noted:
- {{primary risk}}

{{If missing info}}:
Note: Some technical details were unclear. The story includes exploration tasks to gather needed information during implementation.

Next Steps:
1. Review story for accuracy
2. Verify integration approach aligns with your system
3. Approve story or request adjustments
4. Dev agent can then implement with safety checks

Success Criteria

The brownfield story creation is successful when:

Story can be implemented without requiring dev to search multiple documents
Integration approach is clear and safe for existing system
All available technical context has been extracted and organized
Missing information has been identified and addressed
Risks are documented with mitigation strategies
Story includes verification of existing functionality
Rollback approach is defined

Important Notes

This task is specifically for brownfield projects with non-standard documentation
Always prioritize existing system stability over new features
When in doubt, add exploration and verification tasks
It's better to ask the user for clarification than make assumptions
Each story should be self-contained for the dev agent
Include references to existing code patterns when available

create-brownfield-story.md 9.2 KB Histórico Raw