ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0e00c081633bd14b3246fcbd1d182762f85691a4
BMAD-METHOD/bmad/bmb/workflows/audit-workflow/instructions.md
Brian Madison 54985778f2 minor fixes
2025-10-16 21:50:50 -05:00

11 KiB
Raw Blame History

Audit Workflow - Workflow Quality Audit Instructions

The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/audit-workflow/workflow.yaml

What is the path to the workflow you want to audit? (provide path to workflow.yaml or workflow folder)

Load the workflow.yaml file from the provided path Identify the workflow type (document, action, interactive, autonomous, meta) List all associated files:

  • instructions.md (required for most workflows)
  • template.md (if document workflow)
  • checklist.md (if validation exists)
  • Any data files referenced in yaml

Load all discovered files

Display summary:

  • Workflow name and description
  • Type of workflow
  • Files present
  • Module assignment
Check workflow.yaml for the standard config block:

Required variables:

  • config_source: "{project-root}/bmad/[module]/config.yaml"
  • output_folder: "{config_source}:output_folder"
  • user_name: "{config_source}:user_name"
  • communication_language: "{config_source}:communication_language"
  • date: system-generated

Validate each variable:

Config Source Check:

  • config_source is defined
  • Points to correct module config path
  • Uses {project-root} variable

Standard Variables Check:

  • output_folder pulls from config_source
  • user_name pulls from config_source
  • communication_language pulls from config_source
  • date is set to system-generated

Record any missing or incorrect config variables config_issues

If config issues found: Add to issues list with severity: CRITICAL

Extract all variables defined in workflow.yaml (excluding standard config block) Scan instructions.md for variable usage: {variable_name} pattern Scan template.md for variable usage: {{variable_name}} pattern (if exists)

Cross-reference analysis:

For each yaml variable:

  1. Is it used in instructions.md? (mark as INSTRUCTION_USED)
  2. Is it used in template.md? (mark as TEMPLATE_USED)
  3. Is it neither? (mark as UNUSED_BLOAT)

Special cases to ignore:

  • Standard config variables (config_source, output_folder, user_name, communication_language, date)
  • Workflow metadata (name, description, author)
  • Path variables (installed_path, template, instructions, validation)
  • Web bundle configuration (web_bundle block itself)

Identify unused yaml fields (bloat) Identify hardcoded values in instructions that should be variables alignment_issues

If unused variables found: Add to issues list with severity: BLOAT

Analyze instructions.md for proper config variable usage:

Communication Language Check:

  • Search for phrases like "communicate in {communication_language}"
  • Check if greetings/responses use language-aware patterns
  • Verify NO usage of {{communication_language}} in template headers

User Name Check:

  • Look for user addressing patterns using {user_name}
  • Check if summaries or greetings personalize with {user_name}
  • Verify optional usage in template metadata (not required)

Output Folder Check:

  • Search for file write operations
  • Verify all outputs go to {output_folder} or subdirectories
  • Check for hardcoded paths like "/output/" or "/generated/"

Date Usage Check:

  • Verify date is available for agent date awareness
  • Check optional usage in template metadata
  • Ensure no confusion between date and model training cutoff

Record any improper config variable usage config_usage_issues

If config usage issues found: Add to issues list with severity: IMPORTANT

If workflow.yaml contains web_bundle section:

Validate web_bundle structure:

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 file listed in web_bundle_files
  • template file listed (if document workflow)
  • validation/checklist file listed (if exists)
  • All data files referenced in yaml listed
  • All files referenced in instructions listed

Workflow Dependency Scan: Scan instructions.md for 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 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 Check for CSV, JSON, YAML, MD files referenced Verify all referenced files are in web_bundle_files

Record any missing files or incorrect paths web_bundle_issues

If web_bundle issues found: Add to issues list with severity: CRITICAL

If no web_bundle section exists: Note: "No web_bundle configured (may be intentional for local-only workflows)"

Identify bloat patterns:

Unused YAML Fields:

  • Variables defined but not used in instructions OR template
  • Duplicate fields between top-level and web_bundle section
  • Commented-out variables that should be removed

Hardcoded Values:

  • File paths that should use {output_folder}
  • Generic greetings that should use {user_name}
  • Language-specific text that should use {communication_language}
  • Static dates that should use {date}

Redundant Configuration:

  • Variables that duplicate web_bundle fields
  • Metadata repeated across sections

Calculate bloat metrics:

  • Total yaml fields: {{total_yaml_fields}}
  • Used fields: {{used_fields}}
  • Unused fields: {{unused_fields}}
  • Bloat percentage: {{bloat_percentage}}%

Record all bloat items with recommendations bloat_items

If bloat detected: Add to issues list with severity: CLEANUP

Extract all template variables from template.md: {{variable_name}} pattern Scan instructions.md for corresponding variable_name tags

Cross-reference mapping:

For each template variable:

  1. Is there a matching 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:

  1. Is there a matching template variable? (mark as USED)
  2. Is it orphaned? (mark as UNUSED_OUTPUT)

Verify variable naming conventions:

  • All template variables use snake_case
  • Variable names are descriptive (not abbreviated)
  • Standard config variables properly formatted

Record any mapping issues template_issues

If template issues found: Add to issues list with severity: IMPORTANT

Compile all findings into a structured report

Write audit report to {output_folder}/audit-report-{{workflow_name}}-{{date}}.md

Report Structure:

# Workflow Audit Report

**Workflow:** {{workflow_name}}
**Audit Date:** {{date}}
**Auditor:** Audit Workflow (BMAD v6)
**Workflow Type:** {{workflow_type}}

---

## Executive Summary

**Overall Status:** {{overall_status}}

- Critical Issues: {{critical_count}}
- Important Issues: {{important_count}}
- Cleanup Recommendations: {{cleanup_count}}

---

## 1. Standard Config Block Validation

{{config_issues}}

**Status:** {{config_status}}

---

## 2. YAML/Instruction/Template Alignment

{{alignment_issues}}

**Variables Analyzed:** {{total_variables}}
**Used in Instructions:** {{instruction_usage_count}}
**Used in Template:** {{template_usage_count}}
**Unused (Bloat):** {{bloat_count}}

---

## 3. Config Variable Usage

{{config_usage_issues}}

**Communication Language:** {{comm_lang_status}}
**User Name:** {{user_name_status}}
**Output Folder:** {{output_folder_status}}
**Date:** {{date_status}}

---

## 4. Web Bundle Validation

{{web_bundle_issues}}

**Web Bundle Present:** {{web_bundle_exists}}
**Files Listed:** {{web_bundle_file_count}}
**Missing Files:** {{missing_files_count}}

---

## 5. Bloat Detection

{{bloat_items}}

**Bloat Percentage:** {{bloat_percentage}}%
**Cleanup Potential:** {{cleanup_potential}}

---

## 6. Template Variable Mapping

{{template_issues}}

**Template Variables:** {{template_var_count}}
**Mapped Correctly:** {{mapped_count}}
**Missing Mappings:** {{missing_mapping_count}}

---

## Recommendations

### Critical (Fix Immediately)

{{critical_recommendations}}

### Important (Address Soon)

{{important_recommendations}}

### Cleanup (Nice to Have)

{{cleanup_recommendations}}

---

## Validation Checklist

Use this checklist to verify fixes:

- [ ] All standard config variables present and correct
- [ ] No unused yaml fields (bloat removed)
- [ ] Config variables used appropriately in instructions
- [ ] Web bundle includes all dependencies
- [ ] Template variables properly mapped
- [ ] File structure follows v6 conventions

---

## Next Steps

1. Review critical issues and fix immediately
2. Address important issues in next iteration
3. Consider cleanup recommendations for optimization
4. Re-run audit after fixes to verify improvements

---

**Audit Complete** - Generated by audit-workflow v1.0

Display summary to {user_name} in {communication_language} Provide path to full audit report

Would you like to:

  • View the full audit report
  • Fix issues automatically (invoke edit-workflow)
  • Audit another workflow
  • Exit

audit_report_path