From 336e395f001cf22beace0331070959cc449576d6 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 10 Feb 2026 20:22:05 -0700 Subject: [PATCH] fix: address PR review findings and rename shadowed output_folder variable - Fix single/double brace mismatch for {implementation_artifacts} in create-story instructions.xml (F1) - Remove escaped asterisks in glob patterns in retrospective instructions.md (F2) - Eliminate redundant {config_source} re-resolution for story_location in sprint-planning workflow.yaml (F5) - Add explicit instruction to discover previous_story_num by scanning artifacts instead of leaving it undefined (#7) - Rename output_folder to project_knowledge in document-project workflows to stop shadowing the canonical core config variable (#13) Co-Authored-By: Claude Opus 4.6 --- .../create-story/instructions.xml | 3 ++- .../retrospective/instructions.md | 6 ++--- .../sprint-planning/workflow.yaml | 4 +-- .../document-project/instructions.md | 12 ++++----- .../templates/project-scan-report-schema.json | 4 +-- .../workflows/document-project/workflow.yaml | 2 +- .../workflows/deep-dive-instructions.md | 8 +++--- .../document-project/workflows/deep-dive.yaml | 2 +- .../workflows/full-scan-instructions.md | 26 +++++++++---------- .../document-project/workflows/full-scan.yaml | 2 +- 10 files changed, 35 insertions(+), 34 deletions(-) diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml index 41a610f2f..f9433371f 100644 --- a/src/bmm/workflows/4-implementation/create-story/instructions.xml +++ b/src/bmm/workflows/4-implementation/create-story/instructions.xml @@ -192,7 +192,8 @@ (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story - Business context and value - Success criteria - Load previous story file: {{implementation_artifacts}}/{{epic_num}}-{{previous_story_num}}-*.md **PREVIOUS STORY INTELLIGENCE:** - + Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}} + Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md **PREVIOUS STORY INTELLIGENCE:** - Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established Extract all learnings that could impact current story implementation diff --git a/src/bmm/workflows/4-implementation/retrospective/instructions.md b/src/bmm/workflows/4-implementation/retrospective/instructions.md index 27bbd2587..06ee7c68b 100644 --- a/src/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/bmm/workflows/4-implementation/retrospective/instructions.md @@ -171,7 +171,7 @@ Bob (Scrum Master): "Before we start the team discussion, let me review all the Charlie (Senior Dev): "Good idea - those dev notes always have gold in them." -For each story in epic {{epic_number}}, read the complete story file from {implementation_artifacts}/{{epic_number}}-{{story_num}}-\*.md +For each story in epic {{epic_number}}, read the complete story file from {implementation_artifacts}/{{epic_number}}-{{story_num}}-*.md Extract and analyze from each story: @@ -366,7 +366,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what Attempt to load next epic using selective loading strategy: **Try sharded first (more specific):** -Check if file exists: {planning_artifacts}/epic\*/epic-{{next_epic_num}}.md +Check if file exists: {planning_artifacts}/epic*/epic-{{next_epic_num}}.md Load {planning_artifacts}/*epic*/epic-{{next_epic_num}}.md @@ -375,7 +375,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what **Fallback to whole document:** -Check if file exists: {planning_artifacts}/epic\*.md +Check if file exists: {planning_artifacts}/epic*.md Load entire epics document diff --git a/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml b/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml index 79c364150..6c5d22d64 100644 --- a/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml +++ b/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml @@ -23,8 +23,8 @@ project_name: "{config_source}:project_name" # Tracking system configuration tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello project_key: "NOKEY" # Placeholder for tracker integrations; file-system uses a no-op key -story_location: "{config_source}:implementation_artifacts" # Relative path for file-system, Future will support URL for Jira/Linear/Trello -story_location_absolute: "{config_source}:implementation_artifacts" # Absolute path for file operations +story_location: "{implementation_artifacts}" # Relative path for file-system, Future will support URL for Jira/Linear/Trello +story_location_absolute: "{implementation_artifacts}" # Absolute path for file operations # Source files (file-system only) epics_location: "{planning_artifacts}" # Directory containing epic*.md files diff --git a/src/bmm/workflows/document-project/instructions.md b/src/bmm/workflows/document-project/instructions.md index 2f567fa38..059134259 100644 --- a/src/bmm/workflows/document-project/instructions.md +++ b/src/bmm/workflows/document-project/instructions.md @@ -57,7 +57,7 @@ SMART LOADING STRATEGY: Check state file FIRST before loading any CSV files -Check for existing state file at: {output_folder}/project-scan-report.json +Check for existing state file at: {project_knowledge}/project-scan-report.json Read state file and extract: timestamps, mode, scan_level, current_step, completed_steps, project_classification @@ -107,8 +107,8 @@ Your choice [1/2/3]: - Create archive directory: {output_folder}/.archive/ - Move old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json + Create archive directory: {project_knowledge}/.archive/ + Move old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json Set resume_mode = false Continue to Step 0.5 @@ -120,7 +120,7 @@ Your choice [1/2/3]: Display: "Found old state file (>24 hours). Starting fresh scan." - Archive old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json + Archive old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json Set resume_mode = false Continue to Step 0.5 @@ -128,7 +128,7 @@ Your choice [1/2/3]: -Check if {output_folder}/index.md exists +Check if {project_knowledge}/index.md exists Read existing index.md to extract metadata (date, project structure, parts count) @@ -195,7 +195,7 @@ Your choice [1/2/3]: - Mode: {{workflow_mode}} - Scan Level: {{scan_level}} -- Output: {output_folder}/index.md and related files +- Output: {project_knowledge}/index.md and related files {{#if status_file_found}} **Status Updated:** diff --git a/src/bmm/workflows/document-project/templates/project-scan-report-schema.json b/src/bmm/workflows/document-project/templates/project-scan-report-schema.json index 8133e15fd..69e059833 100644 --- a/src/bmm/workflows/document-project/templates/project-scan-report-schema.json +++ b/src/bmm/workflows/document-project/templates/project-scan-report-schema.json @@ -45,9 +45,9 @@ "type": "string", "description": "Absolute path to project root directory" }, - "output_folder": { + "project_knowledge": { "type": "string", - "description": "Absolute path to output folder" + "description": "Absolute path to project knowledge folder" }, "completed_steps": { "type": "array", diff --git a/src/bmm/workflows/document-project/workflow.yaml b/src/bmm/workflows/document-project/workflow.yaml index 4667d7c0b..be9600c24 100644 --- a/src/bmm/workflows/document-project/workflow.yaml +++ b/src/bmm/workflows/document-project/workflow.yaml @@ -6,7 +6,7 @@ author: "BMad" # Critical variables config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:project_knowledge" +project_knowledge: "{config_source}:project_knowledge" user_name: "{config_source}:user_name" communication_language: "{config_source}:communication_language" document_output_language: "{config_source}:document_output_language" diff --git a/src/bmm/workflows/document-project/workflows/deep-dive-instructions.md b/src/bmm/workflows/document-project/workflows/deep-dive-instructions.md index c88dfb08b..637621c4c 100644 --- a/src/bmm/workflows/document-project/workflows/deep-dive-instructions.md +++ b/src/bmm/workflows/document-project/workflows/deep-dive-instructions.md @@ -194,7 +194,7 @@ This will read EVERY file in this area. Proceed? [y/n] Load complete deep-dive template from: {installed_path}/templates/deep-dive-template.md Fill template with all collected data from steps 13b-13d -Write filled template to: {output_folder}/deep-dive-{{sanitized_target_name}}.md +Write filled template to: {project_knowledge}/deep-dive-{{sanitized_target_name}}.md Validate deep-dive document completeness deep_dive_documentation @@ -241,7 +241,7 @@ Detailed exhaustive analysis of specific areas: ## Deep-Dive Documentation Complete! ✓ -**Generated:** {output_folder}/deep-dive-{{target_name}}.md +**Generated:** {project_knowledge}/deep-dive-{{target_name}}.md **Files Analyzed:** {{file_count}} **Lines of Code Scanned:** {{total_loc}} **Time Taken:** ~{{duration}} @@ -255,7 +255,7 @@ Detailed exhaustive analysis of specific areas: - Related code and reuse opportunities - Implementation guidance -**Index Updated:** {output_folder}/index.md now includes link to this deep-dive +**Index Updated:** {project_knowledge}/index.md now includes link to this deep-dive ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -278,7 +278,7 @@ Your choice [1/2]: All deep-dive documentation complete! -**Master Index:** {output_folder}/index.md +**Master Index:** {project_knowledge}/index.md **Deep-Dives Generated:** {{deep_dive_count}} These comprehensive docs are now ready for: diff --git a/src/bmm/workflows/document-project/workflows/deep-dive.yaml b/src/bmm/workflows/document-project/workflows/deep-dive.yaml index a333cc4bf..c7b85c031 100644 --- a/src/bmm/workflows/document-project/workflows/deep-dive.yaml +++ b/src/bmm/workflows/document-project/workflows/deep-dive.yaml @@ -8,7 +8,7 @@ parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.y # Critical variables inherited from parent config_source: "{project-root}/_bmad/bmb/config.yaml" -output_folder: "{config_source}:output_folder" +project_knowledge: "{config_source}:project_knowledge" user_name: "{config_source}:user_name" date: system-generated diff --git a/src/bmm/workflows/document-project/workflows/full-scan-instructions.md b/src/bmm/workflows/document-project/workflows/full-scan-instructions.md index 1340f75ec..8a3621d21 100644 --- a/src/bmm/workflows/document-project/workflows/full-scan-instructions.md +++ b/src/bmm/workflows/document-project/workflows/full-scan-instructions.md @@ -43,7 +43,7 @@ This workflow uses a single comprehensive CSV file to intelligently document you -Check if {output_folder}/index.md exists +Check if {project_knowledge}/index.md exists Read existing index.md to extract metadata (date, project structure, parts count) @@ -127,7 +127,7 @@ Your choice [1/2/3] (default: 1): Display: "Using Exhaustive Scan (reading all source files)" -Initialize state file: {output_folder}/project-scan-report.json +Initialize state file: {project_knowledge}/project-scan-report.json Every time you touch the state file, record: step id, human-readable summary (what you actually did), precise timestamp, and any outputs written. Vague phrases are unacceptable. Write initial state: { @@ -136,7 +136,7 @@ Your choice [1/2/3] (default: 1): "mode": "{{workflow_mode}}", "scan_level": "{{scan_level}}", "project_root": "{{project_root_path}}", -"output_folder": "{{output_folder}}", +"project_knowledge": "{{project_knowledge}}", "completed_steps": [], "current_step": "step_1", "findings": {}, @@ -325,7 +325,7 @@ findings.batches_completed: [ Build API contracts catalog -IMMEDIATELY write to: {output_folder}/api-contracts-{part_id}.md +IMMEDIATELY write to: {project_knowledge}/api-contracts-{part_id}.md Validate document has all required sections Update state file with output generated PURGE detailed API data, keep only: "{{api_count}} endpoints documented" @@ -346,7 +346,7 @@ findings.batches_completed: [ Build database schema documentation -IMMEDIATELY write to: {output_folder}/data-models-{part_id}.md +IMMEDIATELY write to: {project_knowledge}/data-models-{part_id}.md Validate document completeness Update state file with output generated PURGE detailed schema data, keep only: "{{table_count}} tables documented" @@ -805,7 +805,7 @@ When a document SHOULD be generated but wasn't (due to quick scan, missing data, Show summary of all generated files: -Generated in {{output_folder}}/: +Generated in {{project_knowledge}}/: {{file_list_with_sizes}} @@ -823,7 +823,7 @@ Generated in {{output_folder}}/: 3. Extract document metadata from each match for user selection -Read {output_folder}/index.md +Read {project_knowledge}/index.md Scan for incomplete documentation markers: Step 1: Search for exact pattern "_(To be generated)_" (case-sensitive) @@ -1065,9 +1065,9 @@ Enter number(s) separated by commas (e.g., "1,3,5"), or type 'all': ## Project Documentation Complete! ✓ -**Location:** {{output_folder}}/ +**Location:** {{project_knowledge}}/ -**Master Index:** {{output_folder}}/index.md +**Master Index:** {{project_knowledge}}/index.md 👆 This is your primary entry point for AI-assisted development **Generated Documentation:** @@ -1076,9 +1076,9 @@ Enter number(s) separated by commas (e.g., "1,3,5"), or type 'all': **Next Steps:** 1. Review the index.md to familiarize yourself with the documentation structure -2. When creating a brownfield PRD, point the PRD workflow to: {{output_folder}}/index.md -3. For UI-only features: Reference {{output_folder}}/architecture-{{ui_part_id}}.md -4. For API-only features: Reference {{output_folder}}/architecture-{{api_part_id}}.md +2. When creating a brownfield PRD, point the PRD workflow to: {{project_knowledge}}/index.md +3. For UI-only features: Reference {{project_knowledge}}/architecture-{{ui_part_id}}.md +4. For API-only features: Reference {{project_knowledge}}/architecture-{{api_part_id}}.md 5. For full-stack features: Reference both part architectures + integration-architecture.md **Verification Recap:** @@ -1101,6 +1101,6 @@ When ready to plan new features, run the PRD workflow and provide this index as - Write final state file -Display: "State file saved: {{output_folder}}/project-scan-report.json" +Display: "State file saved: {{project_knowledge}}/project-scan-report.json" diff --git a/src/bmm/workflows/document-project/workflows/full-scan.yaml b/src/bmm/workflows/document-project/workflows/full-scan.yaml index f62aba9b2..272baedda 100644 --- a/src/bmm/workflows/document-project/workflows/full-scan.yaml +++ b/src/bmm/workflows/document-project/workflows/full-scan.yaml @@ -8,7 +8,7 @@ parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.y # Critical variables inherited from parent config_source: "{project-root}/_bmad/bmb/config.yaml" -output_folder: "{config_source}:output_folder" +project_knowledge: "{config_source}:project_knowledge" user_name: "{config_source}:user_name" date: system-generated