diff --git a/bmad-core/agents/dev.md b/bmad-core/agents/dev.md index a862d6f5..3ffd199f 100644 --- a/bmad-core/agents/dev.md +++ b/bmad-core/agents/dev.md @@ -64,6 +64,9 @@ task-execution: dependencies: tasks: - implement-story-with-review + - story-analysis + - internal-review-process + - memory-synthesis - execute-checklist checklists: - story-dod-checklist diff --git a/bmad-core/tasks/implement-story-with-review.md b/bmad-core/tasks/implement-story-with-review.md index 5e01a9cc..5a615d05 100644 --- a/bmad-core/tasks/implement-story-with-review.md +++ b/bmad-core/tasks/implement-story-with-review.md @@ -1,160 +1,65 @@ -# Task: Implement Story with Integrated Review +# Implement Story with Review ## 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**: - - 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`. +## Section 1: Analysis Phase -**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) +**Execute `story-analysis` task** to perform: +- User override checking and temporal context establishment +- Codebase semantic search for existing patterns and implementations +- Dependency analysis with version-based criticality assessment +- Story complexity assessment using Fibonacci scale +- Mode declaration (Review Mode vs. Standard Mode) -### 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): -- 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) +## Section 2: Task Execution Phase -**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 +For each task in the story's task list: -## 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**: - - 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`. +## Section 4: Memory Synthesis -2. **Conditional Implementation Path**: - - **If `Task Complexity` > `agentThresholdTask`**: - - Announce: "**Task complexity is high. Activating internal review process.**" - - Execute the **Internal Review Process (Section 3)** for this task. - - **Else (Task Complexity is low)**: - - Announce: "**Task complexity is low. Implementing directly.**" - - Implement the task, continuously referencing the initial analysis for code reuse opportunities. +**Execute `memory-synthesis` task** to perform: +- Comprehensive knowledge extraction from all Dev Notes +- Memory validation against existing project memory +- Conflict detection and resolution +- Project memory file updates -3. **Testing and Completion**: - - Once the task is implemented (either directly or after passing review), write and pass all required tests. - - Mark the task checkbox as complete: `[x]`. +## Task Dependencies -## 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." -2. **Propose Implementation**: As the `dev` agent, write the proposed code for the task. -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. **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." \ No newline at end of file +- **Minimal Context**: Each sub-task loads only necessary information +- **Reusability**: Sub-tasks can be used independently or in other workflows +- **Maintainability**: Easier to update individual components +- **Testability**: Each component can be validated separately +- **Flexibility**: Different orchestration patterns possible for different scenarios diff --git a/bmad-core/tasks/internal-review-process.md b/bmad-core/tasks/internal-review-process.md new file mode 100644 index 00000000..39194391 --- /dev/null +++ b/bmad-core/tasks/internal-review-process.md @@ -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 diff --git a/bmad-core/tasks/memory-synthesis.md b/bmad-core/tasks/memory-synthesis.md new file mode 100644 index 00000000..9440936d --- /dev/null +++ b/bmad-core/tasks/memory-synthesis.md @@ -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 diff --git a/bmad-core/tasks/story-analysis.md b/bmad-core/tasks/story-analysis.md new file mode 100644 index 00000000..26274528 --- /dev/null +++ b/bmad-core/tasks/story-analysis.md @@ -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