ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

refactor(dev-agent): Break down workflow into modular tasks for minimal context loading 

This commit refactors the monolithic implement-story-with-review.md into focused, reusable task components to address context window concerns and improve maintainability.

New modular task structure:
- story-analysis.md (40 lines): Handles codebase search, dependency analysis, and complexity assessment
- internal-review-process.md (30 lines): Manages 6-criteria code review workflow
- memory-synthesis.md (50 lines): Extracts and validates learnings into project memory
- implement-story-with-review.md (40 lines): Simplified orchestrator that coordinates sub-tasks

Key benefits:
- Minimal context loading: Each task loads only necessary information
- Reusability: Sub-tasks can be used independently or in other workflows
- Maintainability: Easier to update individual components without affecting others
- IDE compatibility: Better support for tools with short context windows like Cursor
- Separation of concerns: Clear boundaries between analysis, review, and synthesis phases

Updated dev agent dependencies to include all new modular tasks while maintaining full workflow functionality and backward compatibility.
This commit is contained in:
kevlingo 2025-06-22 22:25:27 -04:00
parent 13caa83afb
commit e220638116
5 changed files with 380 additions and 142 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
bmad-core/agents/dev.md
View File

@ -64,6 +64,9 @@ task-execution:
dependencies: dependencies:
tasks: tasks:
- implement-story-with-review - implement-story-with-review
- story-analysis
- internal-review-process
- memory-synthesis
- execute-checklist - execute-checklist
checklists: checklists:
- story-dod-checklist - story-dod-checklist

189
bmad-core/tasks/implement-story-with-review.md
View File

@ -1,160 +1,65 @@
# Task: Implement Story with Integrated Review # Implement Story with Review
## Purpose ## Purpose
To execute a user story with a proactive analysis and review cycle, ensuring alignment with existing codebase patterns, modern standards, and a high level of quality before completion. Orchestrate story implementation with integrated analysis, review, and memory synthesis workflows using modular sub-tasks for optimal context management.
## 1. Story Initiation & Analysis Phase ## Overview
[[LLM: Upon receiving a story and before writing any implementation code, execute these steps sequentially.]] This orchestrator coordinates three specialized tasks:
- **story-analysis**: Performs codebase search, dependency analysis, and complexity assessment
- **internal-review-process**: Executes systematic code review when complexity thresholds are exceeded
- **memory-synthesis**: Extracts and synthesizes learnings into persistent project memory
1. **Check for User Override**: ## Section 1: Analysis Phase
- First, check if the user has explicitly requested to force Review Mode for this story (e.g., "Implement this story in review mode").
- If so, immediately declare: "**User has forced Review Mode for this story.**" and proceed to step 5, skipping the complexity assessment. Log this in the `Dev Notes`.
2. **Establish Temporal Context**:
- Check `checkCurrentDate` setting in `core-config.yml`. If `true`, run `get-Date -Format "yyyy-MM-dd"` and store the current year. Announce the year being used for context-setting (e.g., "Operating with standards context for the year 2024."). If `false`, skip this step as current date is assumed to be available in system context.
3. **Internal Codebase Analysis**:
- **Action**: Use the built-in IDE semantic search capabilities.
- **Query**: Search the entire codebase for implementations, functions, components, or patterns that are semantically related to the user story's title, description, and Acceptance Criteria.
- **Goal**: Identify code for potential reuse, and understand existing patterns relevant to the new work. Log these findings internally for use during implementation.
4. **Dependency & Standards Analysis with Version-Based Criticality Assessment**:
- Read the `package.json` (or equivalent) to identify currently installed libraries relevant to the story.
- **Version Criticality Analysis**:
- Compare dependency versions against model training cutoff (typically 2024 for current models)
- Flag packages with versions newer than training data or using "latest"/"^" specifiers
- Identify completely new packages not in model's training data
- [[LLM: **Attempt Internet Search:** If critical versions detected OR for general best practices research, perform a targeted internet search for "best practices for [library/feature] in [current year]".]]
- [[LLM: **On Success:** Silently incorporate the findings and proceed to the next step.]]
- [[LLM: **On Failure with Critical Versions Detected:**
1. **Announce the critical situation:** "I detected [library] version [X.Y.Z] which is newer than my training data (cutoff: [date]). Without MCP search tools, I cannot safely implement features using this version."
2. **Explain the risk:** "Proceeding without current knowledge could result in deprecated patterns, security vulnerabilities, or broken implementations."
3. **Request explicit decision:** "Please enable MCP search tools or confirm you want me to proceed with potentially outdated patterns. Type 'proceed-anyway' to continue at your own risk."
4. **HALT and await user response.** Only continue after explicit user confirmation.]]
- [[LLM: **On Failure with Non-Critical Research:**
1. **Announce the situation:** "I am currently unable to access the internet to research the latest standards for this task."
2. **Offer a choice:** "This appears to be non-critical research. I can proceed using best practices from my existing training data."
3. **Request confirmation:** "Please let me know if you'd like me to continue or if you prefer to enable MCP search tools first."
4. **HALT and await user response.** Continue based on user preference.]]
5. **Initial Complexity Assessment & Mode Declaration**:
- Calculate a "Story Complexity" score using Fibonacci scale (1, 2, 3, 5, 8, 13).
- If Review Mode was forced by the user OR if `Story Complexity` > `agentThresholdStory`, declare: "**Entering high-scrutiny 'Review Mode' for this story. Each task will be individually assessed.**"
- Otherwise, declare: "**Story complexity is within standard limits. Each task will still be individually assessed for complexity.**"
- Log the complexity score (if calculated) and the reason for the mode in the story's `Dev Notes`.
**Fibonacci Complexity Guidelines:** **Execute `story-analysis` task** to perform:
- **1**: Trivial changes (typos, simple styling) - User override checking and temporal context establishment
- **2**: Minor feature additions (new button, basic validation) - Codebase semantic search for existing patterns and implementations
- **3**: Standard feature implementation (form handling, API calls) - Dependency analysis with version-based criticality assessment
- **5**: Complex features (authentication, data processing) - Story complexity assessment using Fibonacci scale
- **8**: Major architectural changes (new services, database schema) - Mode declaration (Review Mode vs. Standard Mode)
- **13**: High-risk/high-uncertainty work (new frameworks, complex integrations)
### Version Analysis Guidelines The analysis phase will create artifacts in the story's `Dev Notes` that inform subsequent implementation decisions.
**Critical Version Indicators** (Require MCP search): ## Section 2: Task Execution Phase
- Package versions released after model training cutoff
- "latest", "^", or "~" version specifiers for major dependencies
- Completely new packages/frameworks not in training data
- Major version bumps (e.g., React 17→19, Node 16→20)
**Non-Critical Research** (Optional MCP search): For each task in the story's task list:
- Established libraries within training data timeframe
- Minor version updates with backward compatibility
- General coding patterns and best practices
- Documentation and styling techniques
## 2. Unified Task Execution Phase 1. **Load Analysis Results**: Reference the analysis artifacts created in Section 1
2. **Task Complexity Assessment**: Evaluate current task complexity using Fibonacci scale
3. **Conditional Implementation Path**:
- **If task complexity > `agentThresholdTask`**: Execute `internal-review-process` task
- **Else**: Implement directly using analysis findings for code reuse opportunities
4. **Testing and Completion**: Write and pass required tests, mark task complete
[[LLM: Proceed with the `Tasks / Subtasks` list from the story file one by one. The following logic applies to EVERY task.]] ## Section 3: Story Finalization
<< For each task in the story's task list: >> 1. **Execute DoD Checklist**: Run `story-dod-checklist` task
2. **Address Issues**: Resolve any checklist failures
3. **Update Status**: Change story status to `Review`
1. **Mandatory Task Complexity Assessment**: ## Section 4: Memory Synthesis
- Evaluate the complexity of the *current task* using Fibonacci scale (1, 2, 3, 5, 8, 13), leveraging the initial semantic search results.
- Compare the `Task Complexity` score against the `agentThresholdTask` value from `core-config.yml`.
2. **Conditional Implementation Path**: **Execute `memory-synthesis` task** to perform:
- **If `Task Complexity` > `agentThresholdTask`**: - Comprehensive knowledge extraction from all Dev Notes
- Announce: "**Task complexity is high. Activating internal review process.**" - Memory validation against existing project memory
- Execute the **Internal Review Process (Section 3)** for this task. - Conflict detection and resolution
- **Else (Task Complexity is low)**: - Project memory file updates
- Announce: "**Task complexity is low. Implementing directly.**"
- Implement the task, continuously referencing the initial analysis for code reuse opportunities.
3. **Testing and Completion**: ## Task Dependencies
- Once the task is implemented (either directly or after passing review), write and pass all required tests.
- Mark the task checkbox as complete: `[x]`.
## 3. The Internal Review Process (Self-Critique) This orchestrator requires access to:
- `story-analysis` task for initial analysis
- `internal-review-process` task for high-complexity reviews
- `memory-synthesis` task for learning extraction
- `story-dod-checklist` task for final validation
- `core-config.yml` for threshold configurations
- Story file for task list and Dev Notes sections
[[LLM: When activated for a high-complexity task, adopt the 'Reviewer' persona for self-critique. This is a Chain-of-Thought process.]] ## Benefits of Modular Approach
1. **Enact Reviewer Persona**: State "Activating The Reviewer for self-critique." - **Minimal Context**: Each sub-task loads only necessary information
2. **Propose Implementation**: As the `dev` agent, write the proposed code for the task. - **Reusability**: Sub-tasks can be used independently or in other workflows
3. **Critique as Reviewer**: As "The Reviewer," analyze the proposed code against the following criteria: - **Maintainability**: Easier to update individual components
* **Code Duplication**: "Does this logic already exist in [file/function from semantic search]? If so, fail." - **Testability**: Each component can be validated separately
* **Syntax & Errors**: "Are there obvious syntax, linting, or TypeScript errors? If so, fail." - **Flexibility**: Different orchestration patterns possible for different scenarios
* **Standards Alignment**: "Does this align with the project's coding standards and the patterns discovered in the initial analysis? If not, fail."
* **Security Vulnerabilities**: "Does this introduce security risks (input validation, authentication, data exposure, hardcoded secrets)? If so, fail."
* **Performance Impact**: "Could this cause performance issues (N+1 queries, memory leaks, inefficient algorithms, excessive resource usage)? If so, fail."
* **Architecture Compliance**: "Does this violate separation of concerns, SOLID principles, or established architectural patterns? If so, fail."
4. **Handle Review Failure**: If any check fails, as "The Reviewer," provide specific, actionable feedback. Then, as the `dev` agent, go back to step 2 to create a revised implementation. Repeat this loop until the code is approved.
5. **Log a Successful Review**: Once "The Reviewer" approves the code, generate a summary for the `Dev Notes` section of the story:
```markdown
**Internal Review Summary for Task [Task #]**
- **Submissions**: [Number]
- **Failed Attempts**:
- **Attempt 1**: [Describe problematic code briefly and why it failed, e.g., "Created duplicate login logic already present in `auth.service.ts`." or "Introduced SQL injection vulnerability in user query."]
- **Attempt N**: ...
- **Final Solution**: [Describe the approved approach, e.g., "Refactored to use the existing `authenticateUser` function from `auth.service.ts` with proper input sanitization."]
- **Lessons Learned**: [Note any new patterns or insights, e.g., "All authentication logic must be centralized in the auth service; direct token manipulation is an anti-pattern in this codebase. Always validate user inputs before database queries."]
```
## 4. Finalize Story
[[LLM: After all tasks are marked `[x]`, run the `story-dod-checklist`. Do not proceed until the checklist is passed.]]
- Execute the `story-dod-checklist` task.
- Address any issues found during the self-check.
- Once the checklist is fully passed, change the story status to `Review`.
## 5. Memory Synthesis & Validation
[[LLM: This is the final, mandatory step. It now includes a holistic analysis of the entire Dev Notes section to capture all potential knowledge.]]
1. **Enact Synthesizer Persona**: Announce "Finalizing work. Switching to Memory Synthesizer persona to distill and validate learnings from all notes."
2. **Comprehensive Knowledge Extraction (Two-Pass Analysis)**:
[[LLM: First, extract high-confidence, explicit lessons. Then, perform a broader scan for implicit knowledge.]]
- **Pass 1: Explicit Lessons**: Parse the `Dev Notes` section for all `Internal Review Summary` blocks. Extract the "Lessons Learned," "Final Solution," and "Failed Attempts" content. These are your high-priority, explicit memories.
- **Pass 2: Implicit Lessons**: Read the *entire* `Dev Notes` section again (including `Completion Notes`, `Debug Log References`, and `Change Log`). Use LLM intelligence to identify potential patterns or learnings that were not part of a formal review. Look for:
- Unexpected workarounds or solutions.
- Reasons for deviating from the original plan.
- Notes about dependency versions or compatibility issues.
- Discoveries of project-specific conventions or "gotchas".
- *Prompt Guidance: "Based on these notes, what would a senior developer tell a new team member to watch out for in this codebase?"*
3. **Synthesize and Deduplicate**:
- Generalize all extracted lessons (from both passes) into a preliminary list of `new_memories_to_process`.
- **Deduplicate this list**: If an implicit lesson from Pass 2 is a rephrasing of an explicit lesson from Pass 1, discard the implicit one and keep the more detailed, explicit version.
4. **Load Existing Memory Context**:
[[LLM: Perform this file read *once* before the validation loop.]]
- Read the entire contents of `.bmad-core/data/bmad-project-memory.md` into a temporary context variable, `existing_memories`. If the file doesn't exist, this variable will be empty.
5. **Reconcile Memories (In-Memory Loop)**:
[[LLM: Initialize an empty list called `finalized_memories` and a list called `conflicts_to_log`. Now, for each unique `new_memory` in the deduplicated list, perform the validation against the loaded `existing_memories` context.]]
- **Check for Conflicts**:
- **Direct Contradiction:** Does the `new_memory` directly contradict a memory in `existing_memories`?
- **Superseding Pattern:** Does the `new_memory` replace an older pattern?
- **Redundancy:** Is the `new_memory` a rephrasing of an existing memory?
- **Process Validation Result**:
- **If a Direct Contradiction is found**: Add a warning to the `conflicts_to_log` list.
- **If a Superseding Pattern is found**: Mark the older memory in `existing_memories` for deprecation and add the `new_memory` to `finalized_memories`.
- **If Redundant**: Do nothing.
- **If No Conflict (Clear)**: Add the `new_memory` to `finalized_memories`.
6. **Commit Changes to File**:
[[LLM: After the loop is complete, perform the file write operations.]]
- If the `finalized_memories` list is not empty or if any existing memories were marked for deprecation:
- Modify the `existing_memories` context in-memory (deprecating old entries, adding new ones from `finalized_memories`).
- Update the "Last Synthesized" timestamp.
- Write the entire, updated memory context back to `.bmad-core/data/bmad-project-memory.md`, overwriting the file.
- If the `conflicts_to_log` list is not empty:
- Append each conflict as a high-priority warning to the current story's `Dev Notes`:
> `**MEMORY CONFLICT DETECTED:** The lesson "[new lesson]" from this story contradicts the existing memory "[conflicting memory]" from Story [source]. Human review is required to resolve this inconsistency.`
7. **Conclude**: Announce "Memory synthesis and validation complete. Story is finalized and ready for review."

100
bmad-core/tasks/internal-review-process.md Normal file
View File

@ -0,0 +1,100 @@
# Internal Review Process Task
## Purpose
Perform systematic code review using industry-standard criteria to ensure quality, security, performance, and architectural compliance.
## When to Use
This task should be executed when:
- Task complexity exceeds `agentThresholdTask` from `core-config.yml`
- User explicitly requests review mode
- Story complexity exceeds `agentThresholdStory`
## Process
### Section 1: Task Complexity Assessment
1. **Mandatory Task Complexity Assessment**:
- Evaluate the complexity of the *current task* using Fibonacci scale (1, 2, 3, 5, 8, 13), leveraging the initial semantic search results.
- Compare the `Task Complexity` score against the `agentThresholdTask` value from `core-config.yml`.
2. **Review Decision**:
- If `Task Complexity` > `agentThresholdTask`, proceed with internal review process.
- If `Task Complexity` ≤ `agentThresholdTask`, implement directly without review loop.
- Log the complexity score and decision in the story's `Dev Notes`.
### Section 2: Implementation & Review Loop
3. **Critique as Reviewer**: As "The Reviewer," analyze the proposed code against the following criteria:
* **Code Duplication**: "Does this logic already exist in [file/function from semantic search]? If so, fail."
* **Syntax & Errors**: "Are there obvious syntax, linting, or TypeScript errors? If so, fail."
* **Standards Alignment**: "Does this align with the project's coding standards and the patterns discovered in the initial analysis? If not, fail."
* **Security Vulnerabilities**: "Does this introduce security risks (input validation, authentication, data exposure, hardcoded secrets)? If so, fail."
* **Performance Impact**: "Could this cause performance issues (N+1 queries, memory leaks, inefficient algorithms, excessive resource usage)? If so, fail."
* **Architecture Compliance**: "Does this violate separation of concerns, SOLID principles, or established architectural patterns? If so, fail."
4. **Review Outcome**:
- **If any criteria fail**: Reject the code, explain the specific failure, and iterate with improvements.
- **If all criteria pass**: Accept the code and proceed to implementation.
- **Maximum iterations**: Limit to 3 attempts to prevent infinite loops.
5. **Review Summary Documentation**:
- Document the review process in the story's `Dev Notes`:
```markdown
**Internal Review Summary for Task [Task #]**
- **Submissions**: [Number]
- **Failed Attempts**:
- **Attempt 1**: [Describe problematic code briefly and why it failed, e.g., "Created duplicate login logic already present in `auth.service.ts`." or "Introduced SQL injection vulnerability in user query."]
- **Attempt N**: ...
- **Final Solution**: [Describe the approved approach, e.g., "Refactored to use the existing `authenticateUser` function from `auth.service.ts` with proper input sanitization."]
- **Lessons Learned**: [Note any new patterns or insights, e.g., "All authentication logic must be centralized in the auth service; direct token manipulation is an anti-pattern in this codebase. Always validate user inputs before database queries."]
```
## Review Criteria Details
### Code Duplication
- Check against semantic search results from analysis phase
- Identify existing functions, components, or patterns
- Ensure reuse over recreation
### Syntax & Errors
- Validate language-specific syntax
- Check for linting violations
- Verify TypeScript type safety
### Standards Alignment
- Ensure consistency with project coding standards
- Follow established patterns from codebase analysis
- Maintain architectural consistency
### Security Vulnerabilities
- Input validation and sanitization
- Authentication and authorization checks
- Data exposure prevention
- Hardcoded secrets detection
### Performance Impact
- Database query optimization (N+1 prevention)
- Memory leak prevention
- Algorithm efficiency
- Resource usage optimization
### Architecture Compliance
- Separation of concerns validation
- SOLID principles adherence
- Established pattern compliance
- Modularity and maintainability
## Output
- Review decision (pass/fail with specific criteria)
- Detailed failure explanations for iterations
- Final review summary in Dev Notes
- Lessons learned for future reference
## Dependencies
- Access to `core-config.yml` for threshold settings
- Results from story analysis (semantic search, patterns)
- Code implementation to review
- Story file for Dev Notes documentation

145
bmad-core/tasks/memory-synthesis.md Normal file
View File

@ -0,0 +1,145 @@
# Memory Synthesis Task
## Purpose
Extract and synthesize learnings from development work into persistent project memory for future reference and continuous improvement.
## When to Use
This task should be executed:
- At the completion of every story implementation
- When manually triggered via `*mem-synth` orchestrator command
- When adding specific memories via `*mem-add` orchestrator command
## Process
### Section 1: Memory Synthesizer Activation
1. **Activate Memory Synthesizer Persona**:
- Switch to "Memory Synthesizer" role for objective analysis
- Focus on extracting generalizable learnings rather than specific implementation details
### Section 2: Knowledge Extraction (Two-Pass Analysis)
2. **First Pass - Explicit Learnings**:
- Scan all `Dev Notes` sections in the story file
- Look for explicit lessons learned, patterns discovered, or insights documented
- Extract formal review summaries and their conclusions
- Identify documented anti-patterns or best practices
3. **Second Pass - Implicit Learnings**:
- Analyze implementation decisions and their outcomes
- Identify patterns in complexity assessments and review failures
- Extract insights from dependency analysis and version considerations
- Note architectural decisions and their rationale
### Section 3: Memory Validation & Synthesis
4. **Memory Candidate Generation**:
- Transform specific learnings into generalizable principles
- Focus on actionable insights that apply beyond the current story
- Ensure memories are concise but comprehensive
- Format as clear, actionable statements
5. **Conflict Detection & Validation**:
- Load existing project memory from `.bmad-core/data/bmad-project-memory.md`
- Check each memory candidate against existing memories
- Identify potential conflicts or contradictions
- Resolve conflicts by:
- Updating existing memory with new insights
- Creating more nuanced memory that encompasses both perspectives
- Flagging genuine contradictions for user review
6. **Memory Quality Assessment**:
- Ensure memories are:
- **Specific enough** to be actionable
- **General enough** to apply to future work
- **Clear and unambiguous** in their guidance
- **Non-contradictory** with existing project knowledge
### Section 4: Memory Integration
7. **Memory File Update**:
- Append validated new memories to the project memory file
- Maintain chronological order with clear attribution
- Use consistent formatting for easy parsing
- Preserve existing memory structure and organization
8. **Integration Verification**:
- Verify the updated memory file is well-formed
- Ensure no duplicate or contradictory entries exist
- Confirm all new memories are properly integrated
## Memory Quality Standards
### Good Memory Examples
- "Authentication logic should be centralized in the auth service; direct token manipulation is an anti-pattern in this codebase"
- "Always validate user inputs before database queries to prevent SQL injection vulnerabilities"
- "Complex UI components (Fibonacci 5+) should include unit tests for state management logic"
### Poor Memory Examples (Too Specific)
- "The login button should be blue" (too specific to one implementation)
- "Use React 18.2.0 for this project" (version-specific, not generalizable)
- "File UserService.ts needs refactoring" (specific file reference)
### Memory Conflict Resolution
**Duplicate Detection**:
- Identify memories that convey the same principle
- Merge similar memories into more comprehensive statements
- Preserve the most actionable version
**Contradiction Handling**:
- Flag genuine contradictions for user review
- Provide context for conflicting approaches
- Suggest resolution strategies when possible
**Memory Evolution**:
- Update existing memories with new insights
- Refine general principles based on specific experiences
- Maintain memory relevance and accuracy
## Output Format
### Memory File Structure
```markdown
# Project Memory
## Development Patterns
- [Memory about coding patterns and practices]
## Architecture Decisions
- [Memory about architectural choices and rationale]
## Quality Standards
- [Memory about testing, review, and quality practices]
## Technology Insights
- [Memory about specific technologies, libraries, and tools]
## Process Learnings
- [Memory about development process and workflow insights]
```
### Memory Entry Format
```markdown
- **[Category]**: [Actionable memory statement] (Source: Story [ID], [Date])
```
## Error Handling
### Memory Validation Failures
- **Duplicate**: "I've already got this noted, great minds think alike!"
- **Contradiction**: "Hmm, this conflicts with what I learned in Story X. Want to discuss which approach is better?"
- **Invalid**: "This seems too specific to generalize. Could you rephrase it as a broader principle?"
- **Success**: "Great insight! I've added this to our project memory."
### File Access Issues
- Gracefully handle missing memory file (create new one)
- Handle file permission issues with clear error messages
- Provide fallback options when file operations fail
## Dependencies
- Access to story file with Dev Notes sections
- Read/write access to `.bmad-core/data/bmad-project-memory.md`
- Understanding of project context and patterns
- Ability to perform semantic analysis of development notes

85
bmad-core/tasks/story-analysis.md Normal file
View File

@ -0,0 +1,85 @@
# Story Analysis Task
## Purpose
Perform comprehensive analysis of a story before implementation, including codebase search, dependency analysis, and complexity assessment.
## Process
### Section 1: Pre-Analysis Setup
1. **Check for User Override**:
- If the user has explicitly requested "Review Mode" (e.g., "Please use review mode for this story"), skip complexity assessment and proceed directly to review mode.
2. **Establish Temporal Context**:
- Check `checkCurrentDate` setting in `core-config.yml`. If `true`, run `get-Date -Format "yyyy-MM-dd"` and store the current year. Announce the year being used for context-setting (e.g., "Operating with standards context for the year 2024."). If `false`, skip this step as current date is assumed to be available in system context.
3. **Codebase Semantic Search**:
- Perform a semantic search across the codebase for patterns, functions, or components related to the story's requirements.
- Focus on finding existing implementations that might be relevant, duplicated, or need to be extended.
- Log findings for later reference during implementation.
### Section 2: Dependency & Version Analysis
4. **Dependency & Standards Analysis with Version-Based Criticality Assessment**:
- Read the `package.json` (or equivalent) to identify currently installed libraries relevant to the story.
- **Version Criticality Analysis**:
- Compare dependency versions against model training cutoff (typically 2024 for current models)
- Flag packages with versions newer than training data or using "latest"/"^" specifiers
- Identify completely new packages not in model's training data
- [[LLM: **Attempt Internet Search:** If critical versions detected OR for general best practices research, perform a targeted internet search for "best practices for [library/feature] in [current year]".]]
- [[LLM: **On Success:** Silently incorporate the findings and proceed to the next step.]]
- [[LLM: **On Failure with Critical Versions Detected:**
1. **Announce the critical situation:** "I detected [library] version [X.Y.Z] which is newer than my training data (cutoff: [date]). Without MCP search tools, I cannot safely implement features using this version."
2. **Explain the risk:** "Proceeding without current knowledge could result in deprecated patterns, security vulnerabilities, or broken implementations."
3. **Request explicit decision:** "Please enable MCP search tools or confirm you want me to proceed with potentially outdated patterns. Type 'proceed-anyway' to continue at your own risk."
4. **HALT and await user response.** Only continue after explicit user confirmation.]]
- [[LLM: **On Failure with Non-Critical Research:**
1. **Announce the situation:** "I am currently unable to access the internet to research the latest standards for this task."
2. **Offer a choice:** "This appears to be non-critical research. I can proceed using best practices from my existing training data."
3. **Request confirmation:** "Please let me know if you'd like me to continue or if you prefer to enable MCP search tools first."
4. **HALT and await user response.** Continue based on user preference.]]
### Section 3: Complexity Assessment
5. **Initial Complexity Assessment & Mode Declaration**:
- Calculate a "Story Complexity" score using Fibonacci scale (1, 2, 3, 5, 8, 13).
- If Review Mode was forced by the user OR if `Story Complexity` > `agentThresholdStory`, declare: "**Entering high-scrutiny 'Review Mode' for this story. Each task will be individually assessed.**"
- Otherwise, declare: "**Story complexity is within standard limits. Each task will still be individually assessed for complexity.**"
- Log the complexity score (if calculated) and the reason for the mode in the story's `Dev Notes`.
**Fibonacci Complexity Guidelines:**
- **1**: Trivial changes (typos, simple styling)
- **2**: Minor feature additions (new button, basic validation)
- **3**: Standard feature implementation (form handling, API calls)
- **5**: Complex features (authentication, data processing)
- **8**: Major architectural changes (new services, database schema)
- **13**: High-risk/high-uncertainty work (new frameworks, complex integrations)
### Version Analysis Guidelines
**Critical Version Indicators** (Require MCP search):
- Package versions released after model training cutoff
- "latest", "^", or "~" version specifiers for major dependencies
- Completely new packages/frameworks not in training data
- Major version bumps (e.g., React 17→19, Node 16→20)
**Non-Critical Research** (Optional MCP search):
- Established libraries within training data timeframe
- Minor version updates with backward compatibility
- General coding patterns and best practices
- Documentation and styling techniques
## Output
Create analysis artifacts in the story's `Dev Notes` section:
- Semantic search findings
- Dependency analysis results
- Complexity assessment and mode declaration
- Any critical version warnings or research limitations
## Dependencies
- Access to `core-config.yml` for configuration settings
- Codebase search capabilities
- Package management file access (package.json, etc.)
- Optional: MCP search tools for dependency research