From b26f82297951c43532bdc8a95414aae9054c02f7 Mon Sep 17 00:00:00 2001 From: Jonah Schulte Date: Fri, 26 Dec 2025 14:02:41 -0500 Subject: [PATCH] feat: add standalone gap-analysis workflow - Audit completed stories to verify claims match code - Validate any story without starting development - Detect false positives (marked done but not implemented) - Batch mode to audit multiple stories - Generate audit reports for team review Applies to both BMM and BMGD modules --- .../gap-analysis/instructions.xml | 367 ++++++++++++++++++ .../4-production/gap-analysis/workflow.yaml | 23 ++ .../gap-analysis/instructions.xml | 367 ++++++++++++++++++ .../gap-analysis/workflow.yaml | 23 ++ 4 files changed, 780 insertions(+) create mode 100644 src/modules/bmgd/workflows/4-production/gap-analysis/instructions.xml create mode 100644 src/modules/bmgd/workflows/4-production/gap-analysis/workflow.yaml create mode 100644 src/modules/bmm/workflows/4-implementation/gap-analysis/instructions.xml create mode 100644 src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml diff --git a/src/modules/bmgd/workflows/4-production/gap-analysis/instructions.xml b/src/modules/bmgd/workflows/4-production/gap-analysis/instructions.xml new file mode 100644 index 00000000..4af6db50 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/gap-analysis/instructions.xml @@ -0,0 +1,367 @@ + + The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml + You MUST have already loaded and processed: {installed_path}/workflow.yaml + Communicate all responses in {communication_language} + + + + Use {{story_file}} directly + Read COMPLETE story file + Extract story_key from filename or metadata + + + + + 🔍 **Gap Analysis - Story Task Validation** + + This workflow validates story tasks against your actual codebase. + + **Use Cases:** + - Audit "done" stories to verify they match reality + - Validate story tasks before starting development + - Check if completed work was actually implemented + + **Provide story to validate:** + + + Enter story file path, story key (e.g., "1-2-auth"), or status to scan (e.g., "done", "review", "in-progress"): + + + Use provided file path as {{story_file}} + Read COMPLETE story file + Extract story_key from filename + + + + + Search {story_dir} for file matching pattern {{story_key}}.md + Set {{story_file}} to found file path + Read COMPLETE story file + + + + + 🔎 Scanning sprint-status.yaml for stories with status: {{user_input}}... + + + Load the FULL file: {{sprint_status}} + Parse development_status section + Find all stories where status equals {{user_input}} + + + 📋 No stories found with status: {{user_input}} + + Available statuses: backlog, ready-for-dev, in-progress, review, done + + HALT + + + + Found {{count}} stories with status {{user_input}}: + + {{list_of_stories}} + + Which story would you like to validate? [Enter story key or 'all']: + + + Set {{batch_mode}} = true + Store list of all story keys to validate + Set {{story_file}} to first story in list + Read COMPLETE story file + + + + + Set {{story_file}} to selected story path + Read COMPLETE story file + + + + + + Set {{story_file}} to found story path + Read COMPLETE story file + + + + + + ⚠ī¸ No sprint-status.yaml found. Please provide direct story file path. + HALT + + + + + + + + 🔍 CODEBASE REALITY CHECK - Validate tasks against actual code! + + 📊 **Analyzing Story: {{story_key}}** + + Scanning codebase to validate tasks... + + + + Parse story sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Status + Extract all tasks and subtasks from story file + Identify technical areas mentioned in tasks (files, classes, functions, services, components) + + + Determine scan targets from task descriptions: + - For "Create X" tasks: Check if X already exists + - For "Implement Y" tasks: Search for Y functionality + - For "Add Z" tasks: Verify Z is missing + - For test tasks: Check for existing test files + + Use Glob to find relevant files matching patterns from tasks (e.g., **/*.ts, **/*.tsx, **/*.test.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 code that tasks claim to create but already exists + + + ❌ What's Missing: + - List features mentioned in tasks but NOT found in codebase + - Identify claimed implementations that don't exist + - Note tasks marked complete but code missing + + + + For each task in the story, determine: + - ACCURATE: Task matches reality (code exists if task is checked, missing if unchecked) + - FALSE POSITIVE: Task checked [x] but code doesn't exist (BS detection!) + - FALSE NEGATIVE: Task unchecked [ ] but code already exists + - NEEDS UPDATE: Task description doesn't match current implementation + + Generate validation report with: + - Tasks that are accurate + - Tasks that are false positives (marked done but not implemented) ⚠ī¸ + - Tasks that are false negatives (not marked but already exist) + - Recommended task updates + + + + 📋 SHOW TRUTH - Compare story claims vs codebase reality + + + 📊 **Gap Analysis Results: {{story_key}}** + + **Story Status:** {{story_status}} + + --- + + **Codebase Scan Results:** + + ✅ **What Actually Exists:** + {{list_of_existing_files_features_with_details}} + + ❌ **What's Actually Missing:** + {{list_of_missing_elements_despite_claims}} + + --- + + **Task Validation:** + + {{if_any_accurate_tasks}} + ✅ **Accurate Tasks** ({{count}}): + {{list_tasks_that_match_reality}} + {{endif}} + + {{if_any_false_positives}} + ⚠ī¸ **FALSE POSITIVES** ({{count}}) - Marked done but NOT implemented: + {{list_tasks_marked_complete_but_code_missing}} + **WARNING:** These tasks claim completion but code doesn't exist! + {{endif}} + + {{if_any_false_negatives}} + ℹī¸ **FALSE NEGATIVES** ({{count}}) - Not marked but ALREADY exist: + {{list_tasks_unchecked_but_code_exists}} + {{endif}} + + {{if_any_needs_update}} + 🔄 **NEEDS UPDATE** ({{count}}) - Task description doesn't match implementation: + {{list_tasks_needing_description_updates}} + {{endif}} + + --- + + 📝 **Proposed Story Updates:** + + {{if_false_positives_found}} + **CRITICAL - Uncheck false positives:** + {{list_tasks_to_uncheck_with_reasoning}} + {{endif}} + + {{if_false_negatives_found}} + **Check completed work:** + {{list_tasks_to_check_with_verification}} + {{endif}} + + {{if_task_updates_needed}} + **Update task descriptions:** + {{list_task_description_updates}} + {{endif}} + + {{if_gap_analysis_section_missing}} + **Add Gap Analysis section** documenting findings + {{endif}} + + --- + + **Story Accuracy Score:** {{percentage_of_accurate_tasks}}% ({{accurate_count}}/{{total_count}}) + + + + + + 🚨 **WARNING:** This story is marked {{story_status}} but has FALSE POSITIVES! + + {{count}} task(s) claim completion but code doesn't exist. + This story may have been prematurely marked complete. + + **Recommendation:** Update story status to 'in-progress' and complete missing work. + + + + + + + **What would you like to do?** + + Options: + [U] Update - Apply proposed changes to story file + [A] Audit Report - Save findings to report file without updating story + [N] No Changes - Just show me the findings + [R] Review Details - Show me more details about specific findings + [C] Continue to Next - Move to next story (batch mode only) + [Q] Quit - Exit gap analysis + + + + + Update story file with proposed changes: + - Uncheck false positive tasks + - Check false negative tasks + - Update task descriptions as needed + - Add or update "Gap Analysis" section with findings + - Add Change Log entry: "Gap analysis performed - tasks validated against codebase ({{date}})" + + + Story has false positives. Update status to 'in-progress'? [Y/n]: + + Update story Status to 'in-progress' + + Update sprint-status.yaml status for this story to 'in-progress' + + + + + ✅ Story file updated with gap analysis findings. + + - {{changes_count}} task(s) updated + - Gap Analysis section added/updated + - Accuracy score: {{accuracy_percentage}}% + + **File:** {{story_file}} + + + + Continue to next story? [Y/n]: + + Load next story from batch list + Analyze next story + + + + HALT - Gap analysis complete + + + + + Generate audit report file: {{story_dir}}/gap-analysis-report-{{story_key}}-{{date}}.md + Include full findings, accuracy scores, recommendations + 📄 Audit report saved: {{report_file}} + + This report can be shared with team for review. + Story file was NOT modified. + + + + Continue to next story? [Y/n]: + + Load next story from batch list + Analyze next story + + + + HALT - Gap analysis complete + + + + + ℹī¸ Findings displayed only. No files modified. + HALT - Gap analysis complete + + + + + Which findings would you like more details about? (specify task numbers, file names, or areas): + Provide detailed analysis of requested areas using Read tool for deeper code inspection + After review, re-present the decision options + Continue based on user's subsequent choice + + + + + Load next story from batch list + Analyze next story + + + + ⚠ī¸ Not in batch mode. Only one story to validate. + HALT + + + + + 👋 Gap analysis session ended. + + {{if batch_mode}}Processed {{processed_count}}/{{total_count}} stories.{{endif}} + + HALT + + + + + ✅ **Gap Analysis Complete, {user_name}!** + + {{if_single_story}} + **Story Analyzed:** {{story_key}} + **Accuracy Score:** {{accuracy_percentage}}% + **Actions Taken:** {{actions_summary}} + {{endif}} + + {{if_batch_mode}} + **Batch Analysis Summary:** + - Stories analyzed: {{processed_count}} + - Average accuracy: {{avg_accuracy}}% + - False positives found: {{total_false_positives}} + - Stories updated: {{updated_count}} + {{endif}} + + **Next Steps:** + - Review updated stories + - Address any false positives found + - Run dev-story for stories needing work + + + + diff --git a/src/modules/bmgd/workflows/4-production/gap-analysis/workflow.yaml b/src/modules/bmgd/workflows/4-production/gap-analysis/workflow.yaml new file mode 100644 index 00000000..5175a5da --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/gap-analysis/workflow.yaml @@ -0,0 +1,23 @@ +name: gap-analysis +description: "Validate story tasks against actual codebase - audit completed stories or validate before development" +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/_bmad/bmgd/config.yaml" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +implementation_artifacts: "{config_source}:implementation_artifacts" +story_dir: "{implementation_artifacts}" + +# Workflow components +installed_path: "{project-root}/_bmad/bmgd/workflows/4-production/gap-analysis" +instructions: "{installed_path}/instructions.xml" + +# Variables +story_file: "" # User provides story file path or auto-discover +sprint_status: "{implementation_artifacts}/sprint-status.yaml" +project_context: "**/project-context.md" + +standalone: true + +web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/gap-analysis/instructions.xml b/src/modules/bmm/workflows/4-implementation/gap-analysis/instructions.xml new file mode 100644 index 00000000..4af6db50 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/gap-analysis/instructions.xml @@ -0,0 +1,367 @@ + + The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml + You MUST have already loaded and processed: {installed_path}/workflow.yaml + Communicate all responses in {communication_language} + + + + Use {{story_file}} directly + Read COMPLETE story file + Extract story_key from filename or metadata + + + + + 🔍 **Gap Analysis - Story Task Validation** + + This workflow validates story tasks against your actual codebase. + + **Use Cases:** + - Audit "done" stories to verify they match reality + - Validate story tasks before starting development + - Check if completed work was actually implemented + + **Provide story to validate:** + + + Enter story file path, story key (e.g., "1-2-auth"), or status to scan (e.g., "done", "review", "in-progress"): + + + Use provided file path as {{story_file}} + Read COMPLETE story file + Extract story_key from filename + + + + + Search {story_dir} for file matching pattern {{story_key}}.md + Set {{story_file}} to found file path + Read COMPLETE story file + + + + + 🔎 Scanning sprint-status.yaml for stories with status: {{user_input}}... + + + Load the FULL file: {{sprint_status}} + Parse development_status section + Find all stories where status equals {{user_input}} + + + 📋 No stories found with status: {{user_input}} + + Available statuses: backlog, ready-for-dev, in-progress, review, done + + HALT + + + + Found {{count}} stories with status {{user_input}}: + + {{list_of_stories}} + + Which story would you like to validate? [Enter story key or 'all']: + + + Set {{batch_mode}} = true + Store list of all story keys to validate + Set {{story_file}} to first story in list + Read COMPLETE story file + + + + + Set {{story_file}} to selected story path + Read COMPLETE story file + + + + + + Set {{story_file}} to found story path + Read COMPLETE story file + + + + + + ⚠ī¸ No sprint-status.yaml found. Please provide direct story file path. + HALT + + + + + + + + 🔍 CODEBASE REALITY CHECK - Validate tasks against actual code! + + 📊 **Analyzing Story: {{story_key}}** + + Scanning codebase to validate tasks... + + + + Parse story sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Status + Extract all tasks and subtasks from story file + Identify technical areas mentioned in tasks (files, classes, functions, services, components) + + + Determine scan targets from task descriptions: + - For "Create X" tasks: Check if X already exists + - For "Implement Y" tasks: Search for Y functionality + - For "Add Z" tasks: Verify Z is missing + - For test tasks: Check for existing test files + + Use Glob to find relevant files matching patterns from tasks (e.g., **/*.ts, **/*.tsx, **/*.test.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 code that tasks claim to create but already exists + + + ❌ What's Missing: + - List features mentioned in tasks but NOT found in codebase + - Identify claimed implementations that don't exist + - Note tasks marked complete but code missing + + + + For each task in the story, determine: + - ACCURATE: Task matches reality (code exists if task is checked, missing if unchecked) + - FALSE POSITIVE: Task checked [x] but code doesn't exist (BS detection!) + - FALSE NEGATIVE: Task unchecked [ ] but code already exists + - NEEDS UPDATE: Task description doesn't match current implementation + + Generate validation report with: + - Tasks that are accurate + - Tasks that are false positives (marked done but not implemented) ⚠ī¸ + - Tasks that are false negatives (not marked but already exist) + - Recommended task updates + + + + 📋 SHOW TRUTH - Compare story claims vs codebase reality + + + 📊 **Gap Analysis Results: {{story_key}}** + + **Story Status:** {{story_status}} + + --- + + **Codebase Scan Results:** + + ✅ **What Actually Exists:** + {{list_of_existing_files_features_with_details}} + + ❌ **What's Actually Missing:** + {{list_of_missing_elements_despite_claims}} + + --- + + **Task Validation:** + + {{if_any_accurate_tasks}} + ✅ **Accurate Tasks** ({{count}}): + {{list_tasks_that_match_reality}} + {{endif}} + + {{if_any_false_positives}} + ⚠ī¸ **FALSE POSITIVES** ({{count}}) - Marked done but NOT implemented: + {{list_tasks_marked_complete_but_code_missing}} + **WARNING:** These tasks claim completion but code doesn't exist! + {{endif}} + + {{if_any_false_negatives}} + ℹī¸ **FALSE NEGATIVES** ({{count}}) - Not marked but ALREADY exist: + {{list_tasks_unchecked_but_code_exists}} + {{endif}} + + {{if_any_needs_update}} + 🔄 **NEEDS UPDATE** ({{count}}) - Task description doesn't match implementation: + {{list_tasks_needing_description_updates}} + {{endif}} + + --- + + 📝 **Proposed Story Updates:** + + {{if_false_positives_found}} + **CRITICAL - Uncheck false positives:** + {{list_tasks_to_uncheck_with_reasoning}} + {{endif}} + + {{if_false_negatives_found}} + **Check completed work:** + {{list_tasks_to_check_with_verification}} + {{endif}} + + {{if_task_updates_needed}} + **Update task descriptions:** + {{list_task_description_updates}} + {{endif}} + + {{if_gap_analysis_section_missing}} + **Add Gap Analysis section** documenting findings + {{endif}} + + --- + + **Story Accuracy Score:** {{percentage_of_accurate_tasks}}% ({{accurate_count}}/{{total_count}}) + + + + + + 🚨 **WARNING:** This story is marked {{story_status}} but has FALSE POSITIVES! + + {{count}} task(s) claim completion but code doesn't exist. + This story may have been prematurely marked complete. + + **Recommendation:** Update story status to 'in-progress' and complete missing work. + + + + + + + **What would you like to do?** + + Options: + [U] Update - Apply proposed changes to story file + [A] Audit Report - Save findings to report file without updating story + [N] No Changes - Just show me the findings + [R] Review Details - Show me more details about specific findings + [C] Continue to Next - Move to next story (batch mode only) + [Q] Quit - Exit gap analysis + + + + + Update story file with proposed changes: + - Uncheck false positive tasks + - Check false negative tasks + - Update task descriptions as needed + - Add or update "Gap Analysis" section with findings + - Add Change Log entry: "Gap analysis performed - tasks validated against codebase ({{date}})" + + + Story has false positives. Update status to 'in-progress'? [Y/n]: + + Update story Status to 'in-progress' + + Update sprint-status.yaml status for this story to 'in-progress' + + + + + ✅ Story file updated with gap analysis findings. + + - {{changes_count}} task(s) updated + - Gap Analysis section added/updated + - Accuracy score: {{accuracy_percentage}}% + + **File:** {{story_file}} + + + + Continue to next story? [Y/n]: + + Load next story from batch list + Analyze next story + + + + HALT - Gap analysis complete + + + + + Generate audit report file: {{story_dir}}/gap-analysis-report-{{story_key}}-{{date}}.md + Include full findings, accuracy scores, recommendations + 📄 Audit report saved: {{report_file}} + + This report can be shared with team for review. + Story file was NOT modified. + + + + Continue to next story? [Y/n]: + + Load next story from batch list + Analyze next story + + + + HALT - Gap analysis complete + + + + + ℹī¸ Findings displayed only. No files modified. + HALT - Gap analysis complete + + + + + Which findings would you like more details about? (specify task numbers, file names, or areas): + Provide detailed analysis of requested areas using Read tool for deeper code inspection + After review, re-present the decision options + Continue based on user's subsequent choice + + + + + Load next story from batch list + Analyze next story + + + + ⚠ī¸ Not in batch mode. Only one story to validate. + HALT + + + + + 👋 Gap analysis session ended. + + {{if batch_mode}}Processed {{processed_count}}/{{total_count}} stories.{{endif}} + + HALT + + + + + ✅ **Gap Analysis Complete, {user_name}!** + + {{if_single_story}} + **Story Analyzed:** {{story_key}} + **Accuracy Score:** {{accuracy_percentage}}% + **Actions Taken:** {{actions_summary}} + {{endif}} + + {{if_batch_mode}} + **Batch Analysis Summary:** + - Stories analyzed: {{processed_count}} + - Average accuracy: {{avg_accuracy}}% + - False positives found: {{total_false_positives}} + - Stories updated: {{updated_count}} + {{endif}} + + **Next Steps:** + - Review updated stories + - Address any false positives found + - Run dev-story for stories needing work + + + + diff --git a/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml b/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml new file mode 100644 index 00000000..88417f98 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml @@ -0,0 +1,23 @@ +name: gap-analysis +description: "Validate story tasks against actual codebase - audit completed stories or validate before development" +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/_bmad/bmm/config.yaml" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +implementation_artifacts: "{config_source}:implementation_artifacts" +story_dir: "{implementation_artifacts}" + +# Workflow components +installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/gap-analysis" +instructions: "{installed_path}/instructions.xml" + +# Variables +story_file: "" # User provides story file path or auto-discover +sprint_status: "{implementation_artifacts}/sprint-status.yaml" +project_context: "**/project-context.md" + +standalone: true + +web_bundle: false