From db05fb7ae73e8221b174efad8d43b20c9f45791f Mon Sep 17 00:00:00 2001 From: Jonah Schulte Date: Fri, 26 Dec 2025 14:02:13 -0500 Subject: [PATCH] feat: add mandatory gap analysis to dev-story workflow - Add Step 1.5 gap analysis before development starts - Scan codebase to validate draft tasks against reality - Propose task refinements (add/modify/remove) - Six user options: approve, auto-accept, reject, edit, skip, review - Update story file with Gap Analysis section - Prevents duplicate implementations in batch planning Applies to both BMM and BMGD modules --- .../4-production/dev-story/instructions.xml | 158 ++++++++++++++++++ .../dev-story/instructions.xml | 158 ++++++++++++++++++ 2 files changed, 316 insertions(+) diff --git a/src/modules/bmgd/workflows/4-production/dev-story/instructions.xml b/src/modules/bmgd/workflows/4-production/dev-story/instructions.xml index 47e76f07..13b2b004 100644 --- a/src/modules/bmgd/workflows/4-production/dev-story/instructions.xml +++ b/src/modules/bmgd/workflows/4-production/dev-story/instructions.xml @@ -134,6 +134,164 @@ ASK user to clarify or HALT + + 🔍 MANDATORY GAP ANALYSIS - Validate draft tasks against actual codebase reality! + This step ensures tasks reflect current codebase state, preventing duplicate implementations and missed dependencies. + + + Extract story requirements, acceptance criteria, and draft tasks from story file + Identify technical areas mentioned in tasks (files, classes, functions, services, components) + + + Determine scan targets from task descriptions: + - For file creation tasks: Check if files already exist + - For feature implementation tasks: Search for related code patterns + - For integration tasks: Verify dependencies exist + + Use Glob to find relevant files matching patterns from tasks (e.g., **/*.ts, **/*.tsx, **/*.test.ts, **/*.service.ts) + Use Grep to search for specific classes, functions, or components mentioned in tasks + Use Read to verify implementation details and functionality in key discovered files + + + Document scan results: + + **CODEBASE REALITY:** + ✅ What Exists: + - List verified files, classes, functions, services found + - Note implementation completeness (partial vs full) + - Identify reusable code that tasks should leverage + + + ❌ What's Missing: + - List requirements mentioned in tasks but not found in codebase + - Identify missing dependencies that tasks assume exist + - Note gaps that need addressing + + + + Compare draft tasks to codebase reality: + For each draft task, determine: + - KEEP AS-IS: Task matches reality (nothing exists, creation needed) + - MODIFY: Task needs adjustment (file/feature exists, should extend/modify instead of create) + - REMOVE: Task already complete (feature fully implemented, tests pass) + - ADD: New prerequisite discovered (missing dependency needs creating first) + + Generate refined task list with clear reasoning for each change + + + + 📊 **Gap Analysis Complete** + + **Codebase Scan Results:** + + ✅ **What Exists:** + {{list_of_existing_files_features_with_details}} + + ❌ **What's Missing:** + {{list_of_missing_elements_from_requirements}} + + --- + + 📝 **Proposed Task Updates:** + + {{if_any_added_tasks}} + **ADDED TASKS** (new prerequisites discovered): + {{list_added_tasks_with_reasoning}} + {{endif}} + + {{if_any_modified_tasks}} + **MODIFIED TASKS** (adjusted for codebase reality): + {{list_modified_tasks_showing_before_and_after}} + {{endif}} + + {{if_any_removed_tasks}} + **REMOVED TASKS** (already complete): + {{list_removed_tasks_with_verification}} + {{endif}} + + {{if_no_changes}} + **NO CHANGES NEEDED** - Draft tasks accurately reflect current codebase state. + {{endif}} + + --- + + + + **Approve these task updates?** + + Options: + [Y] Yes - Update story file with refined tasks and proceed with implementation + [A] Auto-accept - Apply changes and auto-accept all future task refinements this session + [n] No - Keep original draft tasks as-is (not recommended - risk of duplicate code) + [e] Edit - Let me manually adjust the proposed tasks + [s] Skip - Something looks wrong, skip this story + [r] Review - Show me more details about specific findings before deciding + + + + Initialize {{gap_analysis_auto_accept}} = false + + + + Update story file with refined tasks in Tasks/Subtasks section + Add new "Gap Analysis" section to story file with findings: + - Scan timestamp + - What Exists summary + - What's Missing summary + - Task changes applied + + Add Change Log entry: "Tasks refined based on codebase gap analysis ({{date}})" + ✅ Story updated with refined tasks. Proceeding to implementation... + Continue to step 2 + + + + Set {{gap_analysis_auto_accept}} = true + Update story file with refined tasks in Tasks/Subtasks section + Add new "Gap Analysis" section to story file with findings + Add Change Log entry: "Tasks refined based on codebase gap analysis ({{date}})" + ✅ Story updated with refined tasks. Auto-accept enabled for this session. + Continue to step 2 + + + + ⚠️ **Warning:** Proceeding with original draft tasks without validation. + Risk: Tasks may create duplicate code or miss existing implementations. + Add note to Dev Agent Record: "Gap analysis performed but user chose to keep draft tasks" + Continue to step 2 with original draft tasks + + + + Please describe how you want to adjust the proposed tasks, or provide your own task list: + Allow user to refine proposed tasks interactively + Update story file with user's adjusted task list + Add Gap Analysis section documenting user's custom refinements + Add Change Log entry: "Tasks manually refined after gap analysis ({{date}})" + ✅ Story updated with your custom tasks. Proceeding to implementation... + Continue to step 2 + + + + 🛑 Story skipped - review findings and story manually before re-attempting. + Add note to Dev Agent Record: "Development halted - gap analysis revealed issues requiring manual review" + HALT - do not proceed with implementation + + + + Which findings would you like more details about? (specify file names, tasks, or areas of concern) + Provide detailed analysis of requested areas using Read tool for deeper inspection + After review, re-present the approval options + Continue based on user's subsequent choice + + + + + ✅ Draft tasks accurately reflect codebase state - no refinement needed. Proceeding... + Add Gap Analysis section to story documenting verification performed + Continue to step 2 + + + Load all available context to inform implementation diff --git a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml index 40c56244..41c1bd69 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml @@ -134,6 +134,164 @@ ASK user to clarify or HALT + + 🔍 MANDATORY GAP ANALYSIS - Validate draft tasks against actual codebase reality! + This step ensures tasks reflect current codebase state, preventing duplicate implementations and missed dependencies. + + + Extract story requirements, acceptance criteria, and draft tasks from story file + Identify technical areas mentioned in tasks (files, classes, functions, services, components) + + + Determine scan targets from task descriptions: + - For file creation tasks: Check if files already exist + - For feature implementation tasks: Search for related code patterns + - For integration tasks: Verify dependencies exist + + Use Glob to find relevant files matching patterns from tasks (e.g., **/*.ts, **/*.tsx, **/*.test.ts, **/*.service.ts) + Use Grep to search for specific classes, functions, or components mentioned in tasks + Use Read to verify implementation details and functionality in key discovered files + + + Document scan results: + + **CODEBASE REALITY:** + ✅ What Exists: + - List verified files, classes, functions, services found + - Note implementation completeness (partial vs full) + - Identify reusable code that tasks should leverage + + + ❌ What's Missing: + - List requirements mentioned in tasks but not found in codebase + - Identify missing dependencies that tasks assume exist + - Note gaps that need addressing + + + + Compare draft tasks to codebase reality: + For each draft task, determine: + - KEEP AS-IS: Task matches reality (nothing exists, creation needed) + - MODIFY: Task needs adjustment (file/feature exists, should extend/modify instead of create) + - REMOVE: Task already complete (feature fully implemented, tests pass) + - ADD: New prerequisite discovered (missing dependency needs creating first) + + Generate refined task list with clear reasoning for each change + + + + 📊 **Gap Analysis Complete** + + **Codebase Scan Results:** + + ✅ **What Exists:** + {{list_of_existing_files_features_with_details}} + + ❌ **What's Missing:** + {{list_of_missing_elements_from_requirements}} + + --- + + 📝 **Proposed Task Updates:** + + {{if_any_added_tasks}} + **ADDED TASKS** (new prerequisites discovered): + {{list_added_tasks_with_reasoning}} + {{endif}} + + {{if_any_modified_tasks}} + **MODIFIED TASKS** (adjusted for codebase reality): + {{list_modified_tasks_showing_before_and_after}} + {{endif}} + + {{if_any_removed_tasks}} + **REMOVED TASKS** (already complete): + {{list_removed_tasks_with_verification}} + {{endif}} + + {{if_no_changes}} + **NO CHANGES NEEDED** - Draft tasks accurately reflect current codebase state. + {{endif}} + + --- + + + + **Approve these task updates?** + + Options: + [Y] Yes - Update story file with refined tasks and proceed with implementation + [A] Auto-accept - Apply changes and auto-accept all future task refinements this session + [n] No - Keep original draft tasks as-is (not recommended - risk of duplicate code) + [e] Edit - Let me manually adjust the proposed tasks + [s] Skip - Something looks wrong, skip this story + [r] Review - Show me more details about specific findings before deciding + + + + Initialize {{gap_analysis_auto_accept}} = false + + + + Update story file with refined tasks in Tasks/Subtasks section + Add new "Gap Analysis" section to story file with findings: + - Scan timestamp + - What Exists summary + - What's Missing summary + - Task changes applied + + Add Change Log entry: "Tasks refined based on codebase gap analysis ({{date}})" + ✅ Story updated with refined tasks. Proceeding to implementation... + Continue to step 2 + + + + Set {{gap_analysis_auto_accept}} = true + Update story file with refined tasks in Tasks/Subtasks section + Add new "Gap Analysis" section to story file with findings + Add Change Log entry: "Tasks refined based on codebase gap analysis ({{date}})" + ✅ Story updated with refined tasks. Auto-accept enabled for this session. + Continue to step 2 + + + + ⚠️ **Warning:** Proceeding with original draft tasks without validation. + Risk: Tasks may create duplicate code or miss existing implementations. + Add note to Dev Agent Record: "Gap analysis performed but user chose to keep draft tasks" + Continue to step 2 with original draft tasks + + + + Please describe how you want to adjust the proposed tasks, or provide your own task list: + Allow user to refine proposed tasks interactively + Update story file with user's adjusted task list + Add Gap Analysis section documenting user's custom refinements + Add Change Log entry: "Tasks manually refined after gap analysis ({{date}})" + ✅ Story updated with your custom tasks. Proceeding to implementation... + Continue to step 2 + + + + 🛑 Story skipped - review findings and story manually before re-attempting. + Add note to Dev Agent Record: "Development halted - gap analysis revealed issues requiring manual review" + HALT - do not proceed with implementation + + + + Which findings would you like more details about? (specify file names, tasks, or areas of concern) + Provide detailed analysis of requested areas using Read tool for deeper inspection + After review, re-present the approval options + Continue based on user's subsequent choice + + + + + ✅ Draft tasks accurately reflect codebase state - no refinement needed. Proceeding... + Add Gap Analysis section to story documenting verification performed + Continue to step 2 + + + Load all available context to inform implementation