diff --git a/docs/audit-report-tech-spec-2025-10-21.md b/docs/audit-report-tech-spec-2025-10-21.md deleted file mode 100644 index 0959de0f..00000000 --- a/docs/audit-report-tech-spec-2025-10-21.md +++ /dev/null @@ -1,431 +0,0 @@ -# Workflow Audit Report - -**Workflow:** tech-spec -**Audit Date:** 2025-10-21 -**Auditor:** Audit Workflow (BMAD v6) -**Workflow Type:** Document (template-based) -**Workflow Path:** /Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/4-implementation/epic-tech-context - ---- - -## Executive Summary - -**Overall Status:** ⚠️ ISSUES FOUND - Requires fixes before production use - -**Issue Breakdown:** - -- Critical Issues: **2** -- Important Issues: **1** -- Cleanup Recommendations: **4** - -**Primary Concerns:** - -1. Web bundle missing critical workflow dependencies -2. Output path hardcoded instead of using config variable -3. Configuration bloat (40% unused variables) - ---- - -## 1. Standard Config Block Validation - -### ✅ Status: PASS - -All required standard config variables are present and correctly formatted: - -**Required Variables:** - -- ✅ `config_source: "{project-root}/bmad/bmm/config.yaml"` -- ✅ `output_folder: "{config_source}:output_folder"` -- ✅ `user_name: "{config_source}:user_name"` -- ✅ `communication_language: "{config_source}:communication_language"` -- ✅ `date: system-generated` - -**Additional Config Variables Found:** - -- ⚠️ `document_output_language` (non-standard, potentially unused) -- ⚠️ `user_skill_level` (non-standard, potentially unused) - -**Recommendation:** Verify usage of additional config variables or remove if unused. - ---- - -## 2. YAML/Instruction/Template Alignment - -### ❌ Issues Found: Configuration Bloat - -**Variables Analyzed:** 5 custom fields -**Used in Instructions:** 3 -**Used in Template:** N/A (config variables) -**Unused (Bloat):** 2 - -### Unused Variables (BLOAT): - -1. **`document_output_language`** - - Location: workflow.yaml line 10 - - Status: Defined but never referenced in instructions.md or template.md - - Impact: Configuration bloat - - **Action Required:** Remove from yaml - -2. **`user_skill_level`** - - Location: workflow.yaml line 11 - - Status: Defined but never referenced in instructions.md or template.md - - Impact: Configuration bloat - - **Action Required:** Remove from yaml - -### Properly Used Variables: - -- ✅ `output_folder` → Used in instructions.md (lines 12, 129) -- ✅ `user_name` → Used in instructions.md (lines 143, 166) and template.md (line 4) -- ✅ `communication_language` → Used in instructions.md (line 6) -- ✅ `date` → Used in template.md (line 3) and output file naming -- ✅ `non_interactive` → Used in instructions.md (lines 8, 66, 68) - -**Bloat Metrics:** - -- Total custom yaml fields: 5 -- Used fields: 3 -- Unused fields: 2 -- **Bloat Percentage: 40%** - ---- - -## 3. Config Variable Usage - -### Overall Status: ⚠️ IMPORTANT ISSUE FOUND - -**Communication Language:** - -- ✅ Properly used on line 6: `Communicate all responses in {communication_language}` -- ✅ No inappropriate usage in template headers -- Status: **CORRECT** - -**User Name:** - -- ✅ Used for personalization on lines 143, 166 -- ✅ Optional metadata usage in template (line 4) -- Status: **CORRECT** - -**Output Folder:** - -- ✅ Properly used for file searches (lines 12, 129) -- ❌ **ISSUE:** `default_output_file` hardcodes path instead of using variable - - Current: `"{project-root}/docs/tech-spec-epic-{{epic_id}}.md"` - - Should be: `"{output_folder}/tech-spec-epic-{{epic_id}}.md"` - - Impact: Ignores user's configured output folder preference - - Severity: **IMPORTANT** - -**Date:** - -- ✅ System-generated and available -- ✅ Used in template metadata (line 3) -- ✅ Used in output file naming -- Status: **CORRECT** - -### Action Required: - -**Fix default_output_file in workflow.yaml:** - -```yaml -# Current (line 29): -default_output_file: "{project-root}/docs/tech-spec-epic-{{epic_id}}.md" - -# Should be: -default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md" -``` - ---- - -## 4. Web Bundle Validation - -### 🚨 Status: CRITICAL ISSUES FOUND - -**Current Web Bundle Configuration:** - -```yaml -web_bundle: - name: 'tech-spec' - description: '...' - author: 'BMAD BMM' - web_bundle_files: - - 'bmad/bmm/workflows/4-implementation/epic-tech-context/template.md' - - 'bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md' - - 'bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md' -``` - -### Path Validation: - -- ✅ All paths use bmad/-relative format (NOT {project-root}) -- ✅ No {config_source} variables in web_bundle section -- ✅ Paths match actual file locations - -### Completeness Check: - -- ✅ instructions.md listed -- ✅ template.md listed (document workflow) -- ✅ checklist.md listed - -### 🚨 Critical Issues: - -**Issue 1: Missing Workflow Dependency** - -- Severity: **CRITICAL** -- Location: instructions.md line 133 -- Problem: Workflow invokes `workflow-status` but dependency not in web_bundle_files -- Invocation: `` -- Missing files: - - `bmad/bmm/workflows/workflow-status/workflow.yaml` - - `bmad/bmm/workflows/workflow-status/instructions.md` (if exists) - -**Issue 2: Missing existing_workflows Field** - -- Severity: **CRITICAL** -- Problem: When `` calls exist, web_bundle MUST include `existing_workflows` field -- Current: Field not present -- Required: Mapping of workflow variables to paths - -### Required Fix: - -```yaml -web_bundle: - name: 'tech-spec' - description: 'Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping' - author: 'BMAD BMM' - existing_workflows: - - workflow_status: 'bmad/bmm/workflows/workflow-status/workflow.yaml' - web_bundle_files: - - 'bmad/bmm/workflows/4-implementation/epic-tech-context/template.md' - - 'bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md' - - 'bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md' - - 'bmad/bmm/workflows/workflow-status/workflow.yaml' - - 'bmad/bmm/workflows/workflow-status/instructions.md' -``` - -**Web Bundle Status:** - -- Web Bundle Present: ✅ Yes -- Files Listed: 3 -- Missing Files: 2+ -- Completeness: ❌ **INCOMPLETE** - ---- - -## 5. Bloat Detection - -### Bloat Summary - -**Unused YAML Fields: 2** - -1. `document_output_language` - - Type: Config variable - - Usage: Not referenced anywhere - - Recommendation: **Remove** - -2. `user_skill_level` - - Type: Config variable - - Usage: Not referenced anywhere - - Recommendation: **Remove** - -**Hardcoded Values: 1** - -3. `default_output_file` path - - Current: `{project-root}/docs/tech-spec-epic-{{epic_id}}.md` - - Should use: `{output_folder}` - - Impact: Ignores user configuration - - Recommendation: **Fix to use {output_folder}** - -**Redundant Configuration: 3 fields** - -4. Metadata duplication between top-level and web_bundle: - - `name` appears on yaml line 1 AND web_bundle line 36 - - `description` appears on yaml line 2 AND web_bundle line 37 - - `author` appears on yaml line 3 AND web_bundle line 38 - - Recommendation: **Remove duplication** (keep in one location) - -### Bloat Metrics: - -- Total custom yaml fields analyzed: 5 -- Used fields: 3 -- Unused fields: 2 -- **Bloat Percentage: 40%** -- Redundant metadata fields: 3 -- **Cleanup Potential: HIGH** (~30% configuration reduction possible) - ---- - -## 6. Template Variable Mapping - -### ✅ Status: EXCELLENT - No Issues - -**Template Variables:** 20 -**Mapped via template-output:** 15 -**Config Variables:** 2 -**Runtime Variables:** 3 -**Missing Mappings:** 0 -**Orphaned Outputs:** 0 - -### All Template Variables Accounted For: - -**Generated via template-output (15):** - -- overview, objectives_scope, system_arch_alignment -- services_modules, data_models, apis_interfaces, workflows_sequencing -- nfr_performance, nfr_security, nfr_reliability, nfr_observability -- dependencies_integrations -- acceptance_criteria, traceability_mapping -- risks_assumptions_questions, test_strategy - -**Standard Config Variables (2):** - -- date (system-generated) -- user_name (from config) - -**Runtime/Extracted Variables (3):** - -- epic_title (extracted from PRD) -- epic_id (extracted from PRD) - -### Validation: - -- ✅ All variables use snake_case naming -- ✅ Variable names are descriptive and clear -- ✅ Logical grouping in template-output sections -- ✅ No orphaned template-output tags -- ✅ Complete 1:1 mapping coverage - -**No action required** - Template variable mapping is exemplary. - ---- - -## Recommendations - -### 🚨 Critical (Fix Immediately) - -**Priority 1: Fix Web Bundle Dependencies** - -- Add `existing_workflows` field to web_bundle section -- Include workflow-status workflow files in web_bundle_files -- Impact: Without this, workflow cannot be bundled for web use -- File: `workflow.yaml` lines 35-43 - -**Priority 2: Add Missing Workflow Files** - -- Include: `bmad/bmm/workflows/workflow-status/workflow.yaml` -- Include: `bmad/bmm/workflows/workflow-status/instructions.md` (if exists) -- Impact: Web bundle incomplete, workflow invocations will fail -- File: `workflow.yaml` web_bundle_files section - ---- - -### ⚠️ Important (Address Soon) - -**Priority 3: Fix Output Path Configuration** - -- Change `default_output_file` to use `{output_folder}` variable -- Current: `{project-root}/docs/tech-spec-epic-{{epic_id}}.md` -- Fixed: `{output_folder}/tech-spec-epic-{{epic_id}}.md` -- Impact: Respects user's configured output preferences -- File: `workflow.yaml` line 29 - ---- - -### 🧹 Cleanup (Nice to Have) - -**Priority 4: Remove Unused Config Variables** - -- Remove: `document_output_language` (line 10) -- Remove: `user_skill_level` (line 11) -- Impact: Reduces configuration bloat by 40% -- File: `workflow.yaml` config section - -**Priority 5: Eliminate Metadata Duplication** - -- Remove duplicate `name`, `description`, `author` from either top-level or web_bundle -- Keep metadata in one location only -- Impact: Cleaner configuration, easier maintenance -- File: `workflow.yaml` lines 1-3 or 36-38 - ---- - -## Validation Checklist - -Use this checklist to verify fixes: - -- [ ] **Web Bundle:** existing_workflows field added with workflow_status mapping -- [ ] **Web Bundle:** workflow-status/workflow.yaml added to web_bundle_files -- [ ] **Config:** default_output_file uses {output_folder} instead of hardcoded path -- [ ] **Bloat:** document_output_language removed from yaml -- [ ] **Bloat:** user_skill_level removed from yaml -- [ ] **Redundancy:** Metadata duplication eliminated -- [ ] **Re-test:** Workflow executes successfully after fixes -- [ ] **Re-audit:** Run audit-workflow again to verify all issues resolved - ---- - -## Workflow Structure Assessment - -### Strengths: - -- ✅ Excellent template variable mapping (20 variables, 0 orphans) -- ✅ Proper use of standard config variables -- ✅ Clear step-by-step instructions with proper XML structure -- ✅ Good integration with workflow-status for progress tracking -- ✅ Comprehensive validation checklist -- ✅ Non-interactive mode support (#yolo mode) - -### Areas for Improvement: - -- ❌ Web bundle configuration incomplete (missing dependencies) -- ❌ Output path doesn't respect user configuration -- ⚠️ Configuration bloat (40% unused variables) -- ⚠️ Metadata duplication - ---- - -## Next Steps - -### Immediate Actions: - -1. **Fix Critical Issues** (Est. 15 minutes) - - Add existing_workflows field to web_bundle - - Add workflow-status files to web_bundle_files - - Verify workflow-status workflow exists at specified path - -2. **Fix Important Issues** (Est. 5 minutes) - - Update default_output_file to use {output_folder} - - Test output file creation with different config values - -3. **Cleanup Configuration** (Est. 10 minutes) - - Remove document_output_language from yaml - - Remove user_skill_level from yaml - - Eliminate metadata duplication - -4. **Verify Fixes** (Est. 10 minutes) - - Re-run audit-workflow to confirm all issues resolved - - Test workflow execution end-to-end - - Verify web bundle generation works - -### Recommended Testing: - -```bash -# After fixes, test the workflow -/bmad:bmm:workflows:tech-spec - -# Re-audit to verify -/bmad:bmb:agents:bmad-builder -> *audit-workflow -``` - ---- - -## Conclusion - -The **tech-spec** workflow has a solid foundation with excellent template variable mapping and proper instruction structure. However, **critical web bundle issues** must be resolved before production use, and the hardcoded output path should be fixed to respect user configuration. - -**Estimated Fix Time:** 30-40 minutes - -**Recommended Priority:** HIGH - Address critical issues before next release - ---- - -**Audit Complete** ✅ -Generated by: audit-workflow v1.0 -Powered by: BMAD Core v6-alpha diff --git a/docs/sprint-status.yaml b/docs/sprint-status.yaml deleted file mode 100644 index 805db916..00000000 --- a/docs/sprint-status.yaml +++ /dev/null @@ -1,97 +0,0 @@ -# generated: 2025-10-21 -# project: MyPlantFamily -# project_key: MyPlantFamily -# tracking_system: file-system -# story_location: {project-root}/docs/stories - -# STATUS DEFINITIONS: -# ================== -# Epic Status: -# - backlog: Epic exists in epic file but not contexted -# - contexted: Epic tech context created (required before drafting stories) -# -# Story Status: -# - backlog: Story only exists in epic file -# - drafted: Story file created in stories folder -# - ready-for-dev: Draft approved and story context created -# - in-progress: Developer actively working on implementation -# - review: Under SM review (via review-story workflow) -# - done: Story completed -# -# Retrospective Status: -# - optional: Can be completed but not required -# - completed: Retrospective has been done -# -# WORKFLOW NOTES: -# =============== -# - Epics should be 'contexted' before stories can be 'drafted' -# - Stories can be worked in parallel if team capacity allows -# - SM typically drafts next story after previous one is 'done' to incorporate learnings -# - Dev moves story to 'review', SM reviews, then Dev moves to 'done' - -generated: 2025-10-21 -project: MyPlantFamily -project_key: MyPlantFamily -tracking_system: file-system -story_location: "{project-root}/docs/stories" - -development_status: - # Epic 1: Foundation & Core Plant Management - epic-1: backlog - 1-1-project-foundation-development-environment: backlog - 1-2-app-shell-navigation-framework: backlog - 1-3-user-authentication-account-management: backlog - 1-4-plant-data-model-species-database: backlog - 1-5-add-plant-manual-species-selection: backlog - 1-6-plant-photo-identification-integration: backlog - 1-7-plant-naming-profile-creation: backlog - 1-8-plant-collection-home-screen: backlog - 1-9-plant-detail-view: backlog - 1-10-cloud-photo-storage-display: backlog - epic-1-retrospective: optional - - # Epic 2: AI Personality System & Engagement Loop - epic-2: backlog - 2-1-personality-system-data-model: backlog - 2-2-personality-prototype-testing: backlog - 2-3-llm-integration-api-setup: backlog - 2-4-chat-interface-ui: backlog - 2-5-conversational-ai-system: backlog - 2-6-graceful-degradation-library: backlog - 2-7-response-caching-cost-optimization: backlog - 2-8-personality-driven-care-reminders: backlog - 2-9-push-notification-system: backlog - 2-10-reminder-intelligence-adaptation: backlog - 2-11-mood-system-visual-indicators: backlog - 2-12-mood-calculation-logic-time-based: backlog - 2-13-personality-introduction-onboarding: backlog - 2-14-personality-tone-testing-calibration: backlog - 2-15-emergency-tone-adjustment-system: backlog - 2-16-api-reliability-monitoring-alerts: backlog - epic-2-retrospective: optional - - # Epic 3: Care Scheduling, Photos & Growth Tracking - epic-3: backlog - 3-1-care-schedule-data-model: backlog - 3-2-auto-generated-care-schedules: backlog - 3-3-manual-care-logging: backlog - 3-4-care-history-view: backlog - 3-5-customizable-care-schedules: backlog - 3-6-photo-timeline-tracking: backlog - 3-7-health-status-visualization: backlog - 3-8-enhanced-mood-calculation-care-data: backlog - epic-3-retrospective: optional - - # Epic 4: Social Sharing & Premium Monetization - epic-4: backlog - 4-1-shareable-content-card-design-system: backlog - 4-2-share-plant-profile: backlog - 4-3-share-conversation-snippets: backlog - 4-4-share-growth-progress: backlog - 4-5-share-care-achievements: backlog - 4-6-freemium-tier-definition-enforcement: backlog - 4-7-premium-upgrade-flow-paywall: backlog - 4-8-payment-processing-subscription-management: backlog - 4-9-premium-analytics-dashboard: backlog - 4-10-trial-conversion-optimization: backlog - epic-4-retrospective: optional diff --git a/src/modules/bmb/workflows/audit-workflow/checklist.md b/src/modules/bmb/workflows/audit-workflow/checklist.md index 4698c671..55064127 100644 --- a/src/modules/bmb/workflows/audit-workflow/checklist.md +++ b/src/modules/bmb/workflows/audit-workflow/checklist.md @@ -76,6 +76,8 @@ - [ ] Repeating steps have appropriate repeat attribute (repeat="3", repeat="for-each-X", repeat="until-approved") - [ ] Conditional steps have if="condition" attribute - [ ] XML tags used correctly (, , , , , ) +- [ ] No nested tag references in content (use "action tags" not " tags") +- [ ] Tag references use descriptive text without angle brackets for clarity - [ ] Steps are focused (single goal per step) - [ ] Instructions are specific with limits ("Write 1-2 paragraphs" not "Write about") - [ ] Examples provided where helpful @@ -120,9 +122,9 @@ _List any cleanup recommendations:_ ## Audit Summary -**Total Checks:** 70 -**Passed:** **\_** / 70 -**Failed:** **\_** / 70 +**Total Checks:** 72 +**Passed:** **\_** / 72 +**Failed:** **\_** / 72 **Pass Rate:** **\_**% **Recommendation:** diff --git a/src/modules/bmb/workflows/audit-workflow/instructions.md b/src/modules/bmb/workflows/audit-workflow/instructions.md index 0daaeafb..24116169 100644 --- a/src/modules/bmb/workflows/audit-workflow/instructions.md +++ b/src/modules/bmb/workflows/audit-workflow/instructions.md @@ -115,11 +115,30 @@ Display summary: - Check optional usage in template metadata - Ensure no confusion between date and model training cutoff +**Nested Tag Reference Check:** + +- Search for XML tag references within tags (e.g., `Scan for tags`) +- Identify patterns like: ` tags`, ` calls`, `content` within content +- Common problematic tags to check: action, ask, check, template-output, invoke-workflow, goto +- Flag any instances where angle brackets appear in content describing tags + +**Best Practice:** Use descriptive text without brackets (e.g., "action tags" instead of " tags") + +**Rationale:** + +- Prevents XML parsing ambiguity +- Improves readability for humans and LLMs +- LLMs understand "action tags" = `` tags from context + +Scan instructions.md for nested tag references using pattern: <(action|ask|check|template-output|invoke-workflow|goto|step|elicit-required)> within text content +Record any instances of nested tag references with line numbers Record any improper config variable usage config_usage_issues If config usage issues found: Add to issues list with severity: IMPORTANT +If nested tag references found: +Add to issues list with severity: CLARITY (recommend using descriptive text without angle brackets) @@ -142,17 +161,17 @@ Display summary: - [ ] All files referenced in instructions listed **Workflow Dependency Scan:** -Scan instructions.md for tags +Scan instructions.md for invoke-workflow tags Extract workflow paths from invocations Verify each called workflow.yaml is in web_bundle_files **CRITICAL**: Check if existing_workflows field is present when workflows are invoked -If calls exist, existing_workflows MUST map workflow variables to paths +If invoke-workflow calls exist, existing_workflows MUST map workflow variables to paths Example: If instructions use {core_brainstorming}, web_bundle needs: existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml" **File Reference Scan:** -Scan instructions.md for file references in tags +Scan instructions.md for file references in action tags Check for CSV, JSON, YAML, MD files referenced Verify all referenced files are in web_bundle_files @@ -203,17 +222,17 @@ existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/wor Extract all template variables from template.md: {{variable_name}} pattern -Scan instructions.md for corresponding variable_name tags +Scan instructions.md for corresponding template-output tags Cross-reference mapping: **For each template variable:** -1. Is there a matching tag? (mark as MAPPED) +1. Is there a matching template-output tag? (mark as MAPPED) 2. Is it a standard config variable? (mark as CONFIG_VAR - optional) 3. Is it unmapped? (mark as MISSING_OUTPUT) -**For each tag:** +**For each template-output tag:** 1. Is there a matching template variable? (mark as USED) 2. Is it orphaned? (mark as UNUSED_OUTPUT) @@ -277,7 +296,7 @@ existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/wor --- -## 3. Config Variable Usage +## 3. Config Variable Usage & Instruction Quality {{config_usage_issues}} @@ -285,6 +304,7 @@ existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/wor **User Name:** {{user_name_status}} **Output Folder:** {{output_folder_status}} **Date:** {{date_status}} +**Nested Tag References:** {{nested_tag_count}} instances found ---