From c3cf0c1fc67e0ea2764c451c4f59f9a6fcc1eb11 Mon Sep 17 00:00:00 2001 From: Darren Podolak Date: Mon, 29 Dec 2025 10:08:16 -0500 Subject: [PATCH] refactor(bmm): Convert bug-tracking to progressive disclosure workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace monolithic instructions.md with step-based micro-file architecture - Remove workflow.yaml in favor of workflow.md entry point (exec: pattern) - Extract shared sync-bug-tracking.xml task to core/tasks for reuse - Integrate bug sync into code-review and story-done workflows - Add main_config to workflow.md frontmatter per convention Follows BMB and phase 1-3 progressive disclosure conventions. 🤖 Generated with [Claude Code](https://claude.ai/claude-code) Co-Authored-By: Claude Opus 4.5 --- src/core/tasks/sync-bug-tracking.xml | 123 ++++++ .../code-review/instructions.xml | 13 + .../story-done/instructions.md | 74 +--- .../workflows/bug-tracking/instructions.md | 376 ------------------ .../bug-tracking/steps/step-01-init.md | 167 ++++++++ .../bug-tracking/steps/step-01b-continue.md | 110 +++++ .../bug-tracking/steps/step-02-sync.md | 145 +++++++ .../bug-tracking/steps/step-03-parse.md | 164 ++++++++ .../bug-tracking/steps/step-04-triage.md | 212 ++++++++++ .../bug-tracking/steps/step-05-update.md | 200 ++++++++++ .../bug-tracking/steps/step-06-complete.md | 180 +++++++++ .../bmm/workflows/bug-tracking/workflow.md | 58 +++ .../bmm/workflows/bug-tracking/workflow.yaml | 32 -- 13 files changed, 1381 insertions(+), 473 deletions(-) create mode 100644 src/core/tasks/sync-bug-tracking.xml delete mode 100644 src/modules/bmm/workflows/bug-tracking/instructions.md create mode 100644 src/modules/bmm/workflows/bug-tracking/steps/step-01-init.md create mode 100644 src/modules/bmm/workflows/bug-tracking/steps/step-01b-continue.md create mode 100644 src/modules/bmm/workflows/bug-tracking/steps/step-02-sync.md create mode 100644 src/modules/bmm/workflows/bug-tracking/steps/step-03-parse.md create mode 100644 src/modules/bmm/workflows/bug-tracking/steps/step-04-triage.md create mode 100644 src/modules/bmm/workflows/bug-tracking/steps/step-05-update.md create mode 100644 src/modules/bmm/workflows/bug-tracking/steps/step-06-complete.md create mode 100644 src/modules/bmm/workflows/bug-tracking/workflow.md delete mode 100644 src/modules/bmm/workflows/bug-tracking/workflow.yaml diff --git a/src/core/tasks/sync-bug-tracking.xml b/src/core/tasks/sync-bug-tracking.xml new file mode 100644 index 00000000..9efe6d61 --- /dev/null +++ b/src/core/tasks/sync-bug-tracking.xml @@ -0,0 +1,123 @@ + + Sync bugs.yaml and bugs.md when a story is marked done, updating related bugs to "fixed" and features to "implemented" + + + This task is invoked by workflows (story-done, code-review) after a story is marked done. + It searches bugs.yaml for bugs/features linked to the completed story and updates their status. + For multi-story features, it only marks "implemented" when ALL linked stories are done. + + + + The story key (e.g., "3-7-checkout-from-club-detail-page") + The story ID (e.g., "3.7") - used for related_story matching + Path to bugs.yaml file + Path to bugs.md file + Path to sprint-status.yaml file + Current date for timestamps + + + + List of bug IDs marked as fixed + List of feature IDs marked as implemented + List of feature IDs with incomplete stories + + + + + Load {bugs_yaml} if it exists + + Set bugs_updated = [], features_updated = [], features_pending = [] + Return early - no bug tracking to sync + + + + + Initialize: bugs_updated = [], features_updated = [], features_pending = [] + + Search for entries matching this story using ALL THREE methods: + 1. Check sprint-status.yaml for comment "# Source: bugs.yaml/feature-XXX" or "# Source: bugs.yaml/bug-XXX" on the {story_key} line - this is the MOST RELIABLE method + 2. Check related_story field in bugs.yaml matching {story_id} or {story_key} + 3. Check sprint_stories arrays in feature_requests for entries containing {story_key} + + PRIORITY: Use sprint-status comment source if present - it's explicit and unambiguous + + + + + For each matching bug: + - Update status: "triaged" or "routed" or "in-progress" → "fixed" + - Set fixed_date: {date} + - Set assigned_to: "dev-agent" (if not already set) + - Append to notes: "Auto-closed via sync-bug-tracking. Story {story_key} marked done on {date}." + - Add bug ID to bugs_updated list + + + + + + For each matching feature (via related_story OR sprint_stories): + + MULTI-STORY FEATURE CHECK: If feature has sprint_stories array with multiple entries: + 1. Extract all story keys from sprint_stories (format: "story-key: status") + 2. Load sprint-status.yaml and check development_status for EACH story + 3. Only proceed if ALL stories in sprint_stories have status "done" in sprint-status.yaml + 4. If any story is NOT done, add feature to features_pending and log: "Feature {feature_id} has incomplete stories: {incomplete_list}" + + + - Update status: "backlog" or "triaged" or "routed" or "in-progress" → "implemented" + - Set implemented_date: {date} + - Update sprint_stories entries to reflect done status + - Append to notes: "Auto-closed via sync-bug-tracking. Story {story_key} marked done on {date}." + - Add feature ID to features_updated list + + + + + + + Save updated bugs.yaml, preserving all structure and comments + + + + + + Load {bugs_md} + + + For each bug in bugs_updated: + - Find the bug entry in "# Tracked Bugs" section + - Move it to "# Fixed Bugs" section + - Add [IMPLEMENTED] tag prefix with date: "[IMPLEMENTED] bug-XXX: Title [Fixed: {date}, Verified: pending]" + + + + For each feature in features_updated: + - Find the feature entry in "# Tracked Feature Requests" section + - Move it to "# Implemented Features" section + - Add [IMPLEMENTED] tag prefix with date: "[IMPLEMENTED] feature-XXX: Title [Implemented: {date}, Verified: pending]" + + + Update statistics section if present + Save updated bugs.md + + + + + +Bug/Feature Sync Results: +{{#if bugs_updated}} +- Bugs marked fixed: {{bugs_updated}} +{{/if}} +{{#if features_updated}} +- Features marked implemented: {{features_updated}} +{{/if}} +{{#if features_pending}} +- Features with incomplete stories (not yet implemented): {{features_pending}} +{{/if}} +{{#if no_matches}} +- No related bugs/features found for story {story_key} +{{/if}} + + + + diff --git a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml index e57a940d..98294ae4 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml @@ -212,11 +212,24 @@ ℹī¸ Story status updated (no sprint tracking configured) + + + + {{story_key}} + {{story_id}} + {output_folder}/bugs.yaml + {output_folder}/bugs.md + {sprint_status} + {date} + + + **✅ Review Complete!** **Story Status:** {{new_status}} **Issues Fixed:** {{fixed_count}} **Action Items Created:** {{action_count}} + {{#if new_status == "done"}}**Bug/Feature Tracking:** Synced automatically{{/if}} {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}} diff --git a/src/modules/bmm/workflows/4-implementation/story-done/instructions.md b/src/modules/bmm/workflows/4-implementation/story-done/instructions.md index 6653c2e7..b73ae12c 100644 --- a/src/modules/bmm/workflows/4-implementation/story-done/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/story-done/instructions.md @@ -82,72 +82,16 @@ Story is marked Done in file, but sprint-status.yaml may be out of sync. -Check bugs.yaml for bugs/features linked to this story and update their status +Invoke shared task to sync bugs.yaml and bugs.md for this completed story -Load {output_folder}/bugs.yaml if it exists - - - Search for entries matching this story using ALL THREE methods: - 1. Check sprint-status.yaml comment for "# Source: bugs.yaml/feature-XXX" or "# Source: bugs.yaml/bug-XXX" on the story line - this is the MOST RELIABLE method - 2. Check related_story field matching {story_id} or {story_key} - 3. Check sprint_stories array containing entries starting with {story_key} - - PRIORITY: Use sprint-status comment source if present - it's explicit and unambiguous - - - For each matching bug: - - Update status: "triaged" or "routed" → "fixed" - - Set fixed_date: {date} - - Set assigned_to: "dev-agent" - - Append to notes: "Auto-closed via story-done workflow. Story {story_key} marked done on {date}." - - - - For each matching feature (via related_story OR sprint_stories): - - MULTI-STORY FEATURE CHECK: If feature has sprint_stories array with multiple entries: - 1. Extract all story keys from sprint_stories (format: "story-key: status") - 2. Load sprint-status.yaml and check development_status for EACH story - 3. Only proceed if ALL stories in sprint_stories have status "done" in sprint-status.yaml - 4. If any story is NOT done, skip this feature and log: "Feature {feature_id} has incomplete stories: {incomplete_list}" - - - - Update status: "backlog" or "in-progress" → "implemented" - - Set implemented_date: {date} - - Update sprint_stories entries to reflect done status - - Append to notes: "Auto-closed via story-done workflow. Story {story_key} marked done on {date}." - - - - Save updated bugs.yaml - - - Also update bugs.md: - - Move bug entries from "# Tracked Bugs" to "# Fixed Bugs" with [IMPLEMENTED] tag - - Move feature entries from "# Tracked Feature Requests" to "# Implemented Features" with [IMPLEMENTED] tag - Save updated bugs.md - - - -Bug/Feature Sync: -{{#if bugs_updated}} -- Bugs marked fixed: {{bugs_updated_list}} -{{/if}} -{{#if features_updated}} -- Features marked implemented: {{features_updated_list}} -{{/if}} -{{#if features_pending}} -- Features with incomplete stories (not yet implemented): {{features_pending_list}} -{{/if}} -{{#if no_matches}} -- No related bugs/features found for story {story_key} -{{/if}} - - - - - Skip bug tracking sync - no bugs.yaml file present - + + {story_key} + {story_id} + {bugs_yaml} + {bugs_md} + {sprint_status} + {date} + diff --git a/src/modules/bmm/workflows/bug-tracking/instructions.md b/src/modules/bmm/workflows/bug-tracking/instructions.md deleted file mode 100644 index c5395e61..00000000 --- a/src/modules/bmm/workflows/bug-tracking/instructions.md +++ /dev/null @@ -1,376 +0,0 @@ -# Bug Tracking Workflow - Triage and Route - -```xml -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 in {communication_language} with {user_name} -This workflow transforms informal bug reports (bugs.md) into structured metadata (bugs.yaml) with routing recommendations - - - - - **0a. Fetch pending bug reports from the application database:** - GET {project_url}/api/bug-reports/pending - This endpoint returns all bug reports with status 'new' (not yet synced) - Response format: { data: { reports: [...], count: number } } - Each report contains: id, title, description, reporterType, reporterName, platform, browser, pageUrl, screenshotUrl, createdAt - - - No new bug reports from app. Proceeding with manual input check... - Continue to Step 1 - - - - **0b. Format reports as markdown entries:** - For each report, create markdown entry: -```markdown -## Bug: {title} - -{description} - -Reported by: {reporterName} ({reporterType}) -Date: {createdAt formatted as YYYY-MM-DD} -Platform: {platform} / {browser} -Page: {pageUrl} -{if screenshotUrl: Screenshot: {screenshotUrl}} -``` - - - **0c. Insert into bugs.md under "# manual input" section:** - - Read the "# manual input" section location from bugs.md - - Insert the new markdown entries after the "# manual input" header - - Preserve any existing manual input entries - - Write updated bugs.md - - **0d. Mark reports as synced in database:** - POST {project_url}/api/bug-reports/mark-synced - Body: { ids: [array of synced report IDs] } - This updates status to 'synced' so reports won't be fetched again - - **Synced {count} bug report(s) from app:** -{for each report:} -- {title} (from {reporterName}) -{end for} - -Proceeding with triage... - - - - - - Resolve variables from config_source: bugs_input, bugs_output, sprint_status, epics_file - - **1a. Read "# manual input" section from bugs.md (section-based reading):** - - Grep for "# manual input" to find starting line number - - Grep for next section header ("# Tracked Bugs", "# Tracked Feature Requests", "# Fixed Bugs") to find ending line - - Read just that range using offset/limit (do NOT read entire file) - - If no closing section found within initial window, expand read range and retry - - **1b. Search bugs.yaml for existing IDs (do NOT read entire file):** - - Grep for "bug-[0-9]+" pattern to find all existing bug IDs - - Grep for "feature-[0-9]+" pattern to find all existing feature IDs - - This allows duplicate detection and next-ID generation without reading full file - - If bugs.yaml doesn't exist, create it with header/definitions from template - - Load {sprint_status} to understand current sprint context (which stories are in progress) - Load {epics_file} to map bugs to related stories/epics - - - - Parse {bugs_input} (bugs.md) to extract bug reports - CRITICAL: Only triage items from the "# manual input" section - DO NOT triage: - - Items in "# Tracked Bugs" section (already triaged) - - Items in "# Tracked Feature Requests" section (already triaged) - - Items in "# Fixed Bugs" section (already closed) - - Expected format in "# manual input" section (informal, user-written): - - Markdown headers (## Bug: Title) OR bullet lists - - Freeform descriptions - - Optional fields: reported by, date, related story - - May be incomplete (missing severity, complexity, etc.) - - Extract from each bug report in "# manual input": - - Title (required) - - Description (required - may be multi-paragraph) - - Reported by (optional - extract if mentioned) - - Reported date (optional - extract if mentioned) - - Related story (optional - extract story ID if mentioned, e.g. "2-7" or "Story 2.7") - - Platform (optional - extract if mentioned: iOS, Android, all) - - Any reproduction steps - - Compare extracted bugs with existing bugs.yaml entries: - - New bugs: Not in bugs.yaml yet (need full triage) - - Updated bugs: Already in bugs.yaml but description changed (need re-triage) - - Unchanged bugs: Already triaged, skip - If NO new bugs found in "# manual input" section: - No new bugs found in bugs.md - -All bugs have already been triaged and are tracked in bugs.yaml. - -**Options:** -1. Add new bugs to docs/bugs.md (informal format) -2. View bugs.yaml to see structured bug tracking -3. Route existing triaged bugs to workflows - - HALT - - - - For each new/updated bug, perform triage analysis: - - **3a. Generate Bug ID** - - Use grep results from Step 1b to find highest existing bug-NNN - - Assign next sequential ID (e.g., bug-006) - - Format: "bug-" + zero-padded 3-digit number - - **3b. Assess Severity** (critical, high, medium, low) - Analysis questions: - - Does it prevent core functionality? (critical) - - Does it cause crashes or data loss? (critical) - - Does it block major features? (high) - - Does it significantly degrade UX but have workaround? (high) - - Does it affect subset of users with minor impact? (medium) - - Is it cosmetic or edge case? (low) - Reference severity definitions in bugs.yaml header - - **Clarification needed for bug: {bug_title}** - -I need more information to assess severity: - -1. Does this bug prevent users from completing core flows? -2. Does the bug cause crashes or data loss? -3. How many users are affected? (all users, specific platform, edge case) -4. Is there a workaround available? - -Please provide additional context so I can properly triage this bug. - - - - **3c. Assess Complexity** (trivial, small, medium, complex) - Analysis questions: - - Is it a one-line fix? (trivial) - - Single file/component, solution obvious? (small) - - Multiple files OR requires investigation? (medium) - - Architectural change OR affects many stories? (complex) - Reference complexity definitions in bugs.yaml header - - **Clarification needed for bug: {bug_title}** - -To estimate complexity, I need: - -1. Have you identified the root cause, or does it need investigation? -2. Which file(s) or component(s) are affected? -3. Is this an isolated issue or does it affect multiple parts of the app? - -Please provide technical details if available (stack trace, repro steps, affected files). - - - - **3d. Calculate Effort Estimate** (in hours) - Based on complexity: - - trivial: 0.25 - 0.5 hours - - small: 0.5 - 2 hours - - medium: 2 - 8 hours - - complex: 8 - 16+ hours - - **3e. Determine Workflow Path** - Apply routing matrix from bugs.yaml header: - - critical + any complexity -> "correct-course" (need impact analysis) - - high + trivial -> "direct-fix" (urgent, obvious fix) - - high + small -> "tech-spec" (urgent, needs spec) - - high + medium/complex -> "correct-course" (need proper analysis) - - medium + trivial -> "direct-fix" - - medium + small -> "tech-spec" - - medium + medium/complex -> "correct-course" - - low + trivial -> "direct-fix" (defer) - - low + small/medium/complex -> "backlog" (defer) - - **3f. Map to Related Story/Epic** - If bug mentions story ID (e.g., "2-7"), use that - Otherwise, infer from description using epic keywords - Reference epics.md for story matching - - **3g. Determine Affected Platform** - From description, extract: all | ios | android | web - Default to "all" if not specified - - **3h. Set Initial Status** - - New bug -> status: "triaged" - - All other fields: null or empty (to be filled when routed/fixed) - - **3i. Add Triage Notes** - Document reasoning: - - Why this severity? (business impact, user impact) - - Why this complexity? (investigation needed, files affected) - - Why this workflow? (routing logic applied) - - Suggested next steps or investigation areas - - **3j. Assess Documentation Impact** - Evaluate if fix/feature requires updates beyond code: - - **PRD Impact** (doc_impact.prd: true/false) - Set TRUE if issue: - - Conflicts with stated product goals or objectives - - Requires changing MVP scope or feature definitions - - Adds/removes/modifies core user-facing functionality - - Changes success metrics or acceptance criteria at product level - - Affects multiple epics or cross-cutting concerns - - **Architecture Impact** (doc_impact.architecture: true/false) - Set TRUE if issue: - - Requires new system components or services - - Changes data model (new tables, schema modifications) - - Affects API contracts or integration points - - Introduces new dependencies or technology choices - - Changes authentication, authorization, or security model - - Modifies deployment or infrastructure patterns - - **UX Impact** (doc_impact.ux: true/false) - Set TRUE if issue: - - Adds new screens, modals, or navigation paths - - Changes existing user flows or interaction patterns - - Requires new UI components not in design system - - Affects accessibility or responsive behavior requirements - - Changes visual hierarchy or information architecture - - Impacts user onboarding or first-run experience - - **Documentation Notes** (doc_impact.notes) - If any impact is TRUE, briefly describe: - - Which specific sections need updates - - Nature of the change (addition, modification, removal) - - Dependencies between document updates - - - **Override workflow to correct-course** - Documentation impact requires proper change analysis before implementation - Update recommended_workflow: "correct-course" - Add to notes: "Workflow elevated to correct-course due to documentation impact" - - - - - **4a. Update bugs.yaml** - Load existing bugs.yaml structure (if exists) - For each triaged bug: - - If new bug: Add to "bugs:" section with all metadata - - If existing bug: Update metadata fields if changed - Preserve all existing bugs and closed_bugs sections - Update statistics section: - - Count bugs by severity, complexity, status, workflow - - Set last_updated to {date} - Write complete bugs.yaml file - Preserve ALL header comments and definitions - - **4b. Update bugs.md - Move triaged bugs to # Tracked Bugs section** - Use section-based reading to locate relevant sections: - - Grep for "# manual input" and "# Tracked Bugs" line numbers - - Read just those sections with offset/limit (do NOT read entire file) - For each newly triaged bug: - - REMOVE the original entry from "# manual input" section - - ADD formatted entry to "# Tracked Bugs" section (create section if missing) - - Format: "{bug_id}: {title} - {brief_description}. [Severity: {severity}, Complexity: {complexity}, Platform: {affected_platform}, Workflow: {recommended_workflow}]" - - If doc_impact flagged, add: "Doc Impact: {prd|architecture|ux as applicable}" - - Include sub-items with notes if available - For feature requests, use "# Tracked Feature Requests" section instead - Write updated bugs.md - - - - **Bug Triage Complete, {user_name}!** - -**Triaged {triaged_count} bug(s):** - -{for each triaged bug:} ---- -**{bug_id}: {bug_title}** -- **Severity:** {severity} | **Complexity:** {complexity} | **Platform:** {affected_platform} -- **Effort:** ~{effort_estimate} hours -- **Recommended Workflow:** {recommended_workflow} -- **Related:** {related_story} (Epic {related_epic}) -{if doc_impact.prd OR doc_impact.architecture OR doc_impact.ux:} -- **Documentation Impact:** {prd: Y | architecture: Y | ux: Y as applicable} - - {doc_impact.notes} -{end if} - -**Triage Reasoning:** -{triage_notes} - -{end for} - ---- - -**Updated Files:** -- docs/bugs.yaml - Structured metadata for all triaged bugs -- docs/bugs.md - Moved triaged bugs to "# Tracked Bugs" section - -**Summary:** -- Total Active Bugs: {total_active_bugs} -- Critical: {critical_count} | High: {high_count} | Medium: {medium_count} | Low: {low_count} - -{if any doc_impact flagged:} -**Documentation Updates Required:** -- PRD Impact: {prd_impact_count} item(s) -- Architecture Impact: {arch_impact_count} item(s) -- UX Impact: {ux_impact_count} item(s) - -Items with documentation impact have been routed to `correct-course` workflow. -{end if} - -**Workflow Recommendations:** -- Direct Fix ({direct_fix_count}): `/implement bug-NNN` - Quick fixes, no spec needed -- Tech-Spec ({tech_spec_count}): Create tech-spec first, then `/implement` -- Correct-Course ({correct_course_count}): Run correct-course workflow for impact analysis - ---- - -**Next Steps:** - -To implement a bug fix: -``` -/implement bug-NNN -``` - -To verify and close after testing: -``` -/verify bug-NNN -``` - -To verify all implemented bugs: -``` -/verify -``` - - - - -``` - -## Example bugs.md Format (User-Facing) - -Users can write bugs in any freeform markdown format. The workflow parses common patterns: - -**Option 1: Markdown Headers** -```markdown -## Bug: Join button doesn't work on Android - -When I tap the "Join" button, nothing happens. Tested on Samsung Galaxy S21. - -Reported by: Sarah -Date: Nov 19, 2025 -Related: Story 2.7 -``` - -**Option 2: Bullet Lists** -```markdown -- **Join button unresponsive (Android)**: Button doesn't respond to taps. Works on iOS. Probably a touch target issue. -- **App crashes offline**: If I turn off WiFi and try to create something, the app crashes. CRITICAL! -``` - -**Option 3: Numbered Lists** -```markdown -1. Typo in success message - says "sucessfully" instead of "successfully" -2. Times showing in UTC instead of local time - very confusing for users -``` - -The workflow is flexible and extracts whatever information is available, then prompts the user for missing details during triage. diff --git a/src/modules/bmm/workflows/bug-tracking/steps/step-01-init.md b/src/modules/bmm/workflows/bug-tracking/steps/step-01-init.md new file mode 100644 index 00000000..2f4fc057 --- /dev/null +++ b/src/modules/bmm/workflows/bug-tracking/steps/step-01-init.md @@ -0,0 +1,167 @@ +# Step 1: Bug Tracking Workflow Initialization + +## MANDATORY EXECUTION RULES (READ FIRST): + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete triage +- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding +- ✅ ALWAYS treat this as collaborative triage between peers +- 📋 YOU ARE A FACILITATOR, not an automatic processor +- đŸ’Ŧ FOCUS on initialization and setup only - don't look ahead to future steps +- đŸšĒ DETECT existing workflow state and handle continuation properly +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +## EXECUTION PROTOCOLS: + +- đŸŽ¯ Show your analysis before taking any action +- 💾 Initialize bugs.yaml if needed +- 📖 Track workflow state for potential continuation +- đŸšĢ FORBIDDEN to load next step until setup is complete + +## CONTEXT BOUNDARIES: + +- Variables from workflow.md are available in memory +- bugs.yaml tracks all structured bug metadata +- bugs.md is the user-facing input file +- Don't assume knowledge from other steps + +## YOUR TASK: + +Initialize the Bug Tracking workflow by detecting existing state, discovering input files, and setting up for collaborative triage. + +## INITIALIZATION SEQUENCE: + +### 1. Check for Existing Session + +First, check workflow state: + +- Look for existing `{bugs_output}` (bugs.yaml) +- If exists, grep for bugs with `status: triaged` (pending implementation) +- Check `{bugs_input}` (bugs.md) for items in "# manual input" section + +### 2. Handle Continuation (If Pending Work Exists) + +If bugs.yaml exists with triaged bugs awaiting action: + +- **STOP here** and load `./step-01b-continue.md` immediately +- Do not proceed with fresh initialization +- Let step-01b handle the continuation logic + +### 3. Fresh Workflow Setup (If No Pending Work) + +If no bugs.yaml exists OR no pending triaged bugs: + +#### A. Input File Discovery + +Discover and validate required files: + +**Required Files:** +- `{bugs_input}` (bugs.md) - User-facing bug reports + - Must have "# manual input" section for new bugs + - May have "# Tracked Bugs" and "# Fixed Bugs" sections + +**Optional Context Files:** +- `{sprint_status}` - Current sprint context (which stories are in progress) +- `{epics_file}` - For mapping bugs to related stories/epics + +#### B. Initialize bugs.yaml (If Not Exists) + +If bugs.yaml doesn't exist, create it with header structure: + +```yaml +# Bug Tracking Database +# Generated by bug-tracking workflow +# Last updated: {date} + +# Severity Definitions: +# - critical: Prevents core functionality, crashes, data loss +# - high: Blocks major features, significantly degrades UX +# - medium: Affects subset of users, minor impact with workaround +# - low: Cosmetic, edge case, or minor inconvenience + +# Complexity Definitions: +# - trivial: One-line fix, obvious solution +# - small: Single file/component, solution clear +# - medium: Multiple files OR requires investigation +# - complex: Architectural change, affects many areas + +# Workflow Routing Matrix: +# - critical + any → correct-course +# - high + trivial → direct-fix +# - high + small → tech-spec +# - high + medium/complex → correct-course +# - medium + trivial → direct-fix +# - medium + small → tech-spec +# - medium + medium/complex → correct-course +# - low + trivial → direct-fix +# - low + small/medium/complex → backlog + +bugs: [] +features: [] +closed_bugs: [] + +statistics: + total_active: 0 + by_severity: + critical: 0 + high: 0 + medium: 0 + low: 0 + last_updated: {date} +``` + +#### C. Scan for New Bugs + +Read ONLY the "# manual input" section from bugs.md: +- Grep for "# manual input" to find starting line +- Grep for next section header to find ending line +- Read just that range (do NOT read entire file) + +Count items found in manual input section. + +#### D. Complete Initialization and Report + +Report to user: + +"Welcome {user_name}! I've initialized the Bug Tracking workspace for {project_name}. + +**Files Status:** +- bugs.md: {found/created} - {count} item(s) in manual input section +- bugs.yaml: {found/created} - {active_count} active bugs tracked + +**Context Files:** +- Sprint Status: {loaded/not found} +- Epics: {loaded/not found} + +**Ready for Triage:** +{count} new item(s) found in manual input section. + +[S] Sync bug reports from API first (if app integration configured) +[C] Continue to parse and triage bugs +[Q] Quit - no new bugs to triage" + +## SUCCESS METRICS: + +✅ Existing workflow detected and handed off to step-01b correctly +✅ Fresh workflow initialized with bugs.yaml structure +✅ Input files discovered and validated +✅ Manual input section scanned for new items +✅ User informed of status and can proceed + +## FAILURE MODES: + +❌ Proceeding with fresh initialization when pending work exists +❌ Not creating bugs.yaml with proper header/definitions +❌ Reading entire bugs.md instead of just manual input section +❌ Not reporting status to user before proceeding + +❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding +❌ **CRITICAL**: Proceeding with 'C' without fully reading the next step file + +## NEXT STEP: + +- If user selects [S], load `./step-02-sync.md` to sync from API +- If user selects [C], load `./step-03-parse.md` to parse and identify new bugs +- If user selects [Q], end workflow gracefully + +Remember: Do NOT proceed until user explicitly selects an option from the menu! diff --git a/src/modules/bmm/workflows/bug-tracking/steps/step-01b-continue.md b/src/modules/bmm/workflows/bug-tracking/steps/step-01b-continue.md new file mode 100644 index 00000000..09577e6d --- /dev/null +++ b/src/modules/bmm/workflows/bug-tracking/steps/step-01b-continue.md @@ -0,0 +1,110 @@ +# Step 1b: Continue Existing Bug Tracking Session + +## MANDATORY EXECUTION RULES (READ FIRST): + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: ALWAYS read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding +- ✅ ALWAYS treat this as collaborative triage between peers +- 📋 YOU ARE A FACILITATOR, not an automatic processor +- đŸšĒ This step handles CONTINUATION of existing work +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +## EXECUTION PROTOCOLS: + +- đŸŽ¯ Summarize existing state before offering options +- 💾 Preserve all existing bugs.yaml data +- 📖 Help user understand where they left off +- đŸšĢ FORBIDDEN to lose or overwrite existing triage work + +## CONTEXT BOUNDARIES: + +- Variables from workflow.md are available in memory +- bugs.yaml contains existing structured data +- User may have triaged bugs awaiting implementation +- Don't re-triage already processed bugs + +## YOUR TASK: + +Welcome user back and summarize the current state of bug tracking, offering relevant continuation options. + +## CONTINUATION SEQUENCE: + +### 1. Load Current State + +Read bugs.yaml and extract: +- Total active bugs count +- Bugs by status (triaged, implemented, verified) +- Bugs by severity breakdown +- Bugs by recommended workflow + +### 2. Check for New Input + +Scan "# manual input" section of bugs.md: +- Count items not yet in bugs.yaml +- These are new bugs needing triage + +### 3. Present Continuation Summary + +Report to user: + +"Welcome back, {user_name}! Here's your Bug Tracking status for {project_name}. + +**Current State:** +- Active Bugs: {total_active} + - Triaged (awaiting action): {triaged_count} + - Implemented (awaiting verification): {implemented_count} +- By Severity: Critical: {critical} | High: {high} | Medium: {medium} | Low: {low} + +**Workflow Routing:** +- Direct Fix: {direct_fix_count} bug(s) +- Tech-Spec: {tech_spec_count} bug(s) +- Correct-Course: {correct_course_count} bug(s) +- Backlog: {backlog_count} bug(s) + +**New Items:** +- {new_count} new item(s) found in manual input section + +**Options:** +[T] Triage new bugs ({new_count} items) +[I] Implement a bug - `/implement bug-NNN` +[V] Verify implemented bugs - `/verify` +[L] List bugs by status/severity +[Q] Quit" + +### 4. Handle User Selection + +Based on user choice: + +- **[T] Triage**: Load `./step-03-parse.md` to process new bugs +- **[I] Implement**: Guide user to run `/implement bug-NNN` skill +- **[V] Verify**: Guide user to run `/verify` skill +- **[L] List**: Show filtered bug list, then return to menu +- **[Q] Quit**: End workflow gracefully + +## SUCCESS METRICS: + +✅ Existing state accurately summarized +✅ New items detected and counted +✅ User given clear options based on current state +✅ Appropriate next step loaded based on selection + +## FAILURE MODES: + +❌ Losing track of existing triaged bugs +❌ Re-triaging already processed bugs +❌ Not detecting new items in manual input +❌ Proceeding without user selection + +❌ **CRITICAL**: Reading only partial step file +❌ **CRITICAL**: Proceeding without explicit user menu selection + +## NEXT STEP: + +Load appropriate step based on user selection: +- [T] → `./step-03-parse.md` +- [I], [V] → Guide to relevant skill, then return here +- [L] → Display list, return to this menu +- [Q] → End workflow + +Remember: Do NOT proceed until user explicitly selects an option! diff --git a/src/modules/bmm/workflows/bug-tracking/steps/step-02-sync.md b/src/modules/bmm/workflows/bug-tracking/steps/step-02-sync.md new file mode 100644 index 00000000..08b542e4 --- /dev/null +++ b/src/modules/bmm/workflows/bug-tracking/steps/step-02-sync.md @@ -0,0 +1,145 @@ +# Step 2: Sync Bug Reports from API + +## MANDATORY EXECUTION RULES (READ FIRST): + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: ALWAYS read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding +- ✅ ALWAYS treat this as collaborative triage between peers +- 📋 YOU ARE A FACILITATOR, not an automatic processor +- 🌐 This step handles OPTIONAL API integration for in-app bug reporting +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +## EXECUTION PROTOCOLS: + +- đŸŽ¯ Attempt API sync only if configured +- 💾 Preserve existing manual input entries +- 📖 Format synced reports as markdown entries +- đŸšĢ FORBIDDEN to lose manually entered bugs + +## CONTEXT BOUNDARIES: + +- Variables from workflow.md are available in memory +- `project_url` may or may not be configured +- API endpoints are optional - gracefully handle if unavailable +- This step can be skipped if no API integration + +## YOUR TASK: + +Sync pending bug reports from the application's PostgreSQL database via API, formatting them as markdown entries in bugs.md. + +## SYNC SEQUENCE: + +### 1. Check API Configuration + +Verify `{project_url}` is configured: +- If not configured or user skipped this step, proceed to step-03 +- If configured, attempt API connection + +### 2. Fetch Pending Reports + +**API Call:** +``` +GET {project_url}/api/bug-reports/pending +``` + +**Expected Response:** +```json +{ + "data": { + "reports": [...], + "count": number + } +} +``` + +**Report Fields:** +- `id` - Database ID +- `title` - Bug title +- `description` - Bug description +- `reporterType` - Type of reporter (user, staff, admin) +- `reporterName` - Name of reporter +- `platform` - Platform (iOS, Android, web) +- `browser` - Browser if web +- `pageUrl` - URL where bug occurred +- `screenshotUrl` - Optional screenshot +- `createdAt` - Timestamp + +### 3. Handle No Reports + +If count == 0: + +"No new bug reports from the application API. + +[C] Continue to triage existing manual input +[Q] Quit - nothing to process" + +### 4. Format Reports as Markdown + +For each report, create markdown entry: + +```markdown +## Bug: {title} + +{description} + +Reported by: {reporterName} ({reporterType}) +Date: {createdAt formatted as YYYY-MM-DD} +Platform: {platform} / {browser} +Page: {pageUrl} +{if screenshotUrl: Screenshot: {screenshotUrl}} +``` + +### 5. Insert into bugs.md + +- Read the "# manual input" section location from bugs.md +- Insert new markdown entries after the "# manual input" header +- Preserve any existing manual input entries +- Write updated bugs.md + +### 6. Mark Reports as Synced + +**API Call:** +``` +POST {project_url}/api/bug-reports/mark-synced +Body: { "ids": [array of synced report IDs] } +``` + +This updates status to 'synced' so reports won't be fetched again. + +### 7. Report Sync Results + +"**Synced {count} bug report(s) from application:** + +{for each report:} +- {title} (from {reporterName}) +{end for} + +These have been added to the manual input section of bugs.md. + +[C] Continue to parse and triage all bugs +[Q] Quit" + +## SUCCESS METRICS: + +✅ API availability checked gracefully +✅ Pending reports fetched and formatted +✅ Existing manual entries preserved +✅ Reports marked as synced in database +✅ User informed of sync results + +## FAILURE MODES: + +❌ Crashing if API unavailable (should gracefully skip) +❌ Overwriting existing manual input entries +❌ Not marking reports as synced (causes duplicates) +❌ Proceeding without user confirmation + +❌ **CRITICAL**: Reading only partial step file +❌ **CRITICAL**: Proceeding without explicit user selection + +## NEXT STEP: + +After user selects [C], load `./step-03-parse.md` to parse and identify all bugs needing triage. + +Remember: Do NOT proceed until user explicitly selects [C] from the menu! diff --git a/src/modules/bmm/workflows/bug-tracking/steps/step-03-parse.md b/src/modules/bmm/workflows/bug-tracking/steps/step-03-parse.md new file mode 100644 index 00000000..4bef531a --- /dev/null +++ b/src/modules/bmm/workflows/bug-tracking/steps/step-03-parse.md @@ -0,0 +1,164 @@ +# Step 3: Parse and Identify New Bugs + +## MANDATORY EXECUTION RULES (READ FIRST): + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: ALWAYS read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding +- ✅ ALWAYS treat this as collaborative triage between peers +- 📋 YOU ARE A FACILITATOR, not an automatic processor +- 🔍 This step PARSES input only - triage happens in next step +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +## EXECUTION PROTOCOLS: + +- đŸŽ¯ Parse manual input section thoroughly +- 💾 Compare against existing bugs.yaml entries +- 📖 Extract all available information from informal reports +- đŸšĢ FORBIDDEN to start triage in this step - parsing only + +## CONTEXT BOUNDARIES: + +- Variables from workflow.md are available in memory +- bugs.yaml contains existing triaged bugs +- Only parse "# manual input" section of bugs.md +- Do NOT read entire bugs.md file + +## YOUR TASK: + +Parse the "# manual input" section of bugs.md, extract bug information, and identify which items need triage. + +## PARSE SEQUENCE: + +### 1. Read Manual Input Section + +Section-based reading of bugs.md: +- Grep for "# manual input" to find starting line number +- Grep for next section header ("# Tracked Bugs", "# Tracked Feature Requests", "# Fixed Bugs") to find ending line +- Read just that range using offset/limit (do NOT read entire file) +- If no closing section found within initial window, expand read range and retry + +### 2. Search Existing IDs in bugs.yaml + +Do NOT read entire bugs.yaml file: +- Grep for `id: bug-[0-9]+` pattern to find all existing bug IDs +- Grep for `id: feature-[0-9]+` pattern to find all existing feature IDs +- This enables duplicate detection and next-ID generation + +### 3. Parse Bug Reports + +Expected formats in manual input (informal, user-written): + +**Format A: Markdown Headers** +```markdown +## Bug: Title Here + +Description text, possibly multi-paragraph. + +Reported by: Name +Date: YYYY-MM-DD +Related: Story 2.7 +Platform: iOS +``` + +**Format B: Bullet Lists** +```markdown +- **Title (Platform)**: Description text. CRITICAL if urgent. +``` + +**Format C: Numbered Lists** +```markdown +1. Title - Description text +2. Another bug - More description +``` + +### 4. Extract Information + +For each bug report, extract: + +| Field | Required | Notes | +|-------|----------|-------| +| Title | Yes | First line or header | +| Description | Yes | May be multi-paragraph | +| Reported by | No | Extract if mentioned | +| Date | No | Extract if mentioned | +| Related story | No | e.g., "2-7", "Story 2.7" | +| Platform | No | iOS, Android, web, all | +| Reproduction steps | No | If provided | +| Severity hints | No | "CRITICAL", "urgent", etc. | + +### 5. Categorize Items + +Compare extracted bugs with existing bugs.yaml: + +- **New bugs**: Not in bugs.yaml yet (need full triage) +- **Updated bugs**: In bugs.yaml but description changed (need re-triage) +- **Feature requests**: Items that are enhancements, not bugs +- **Unchanged**: Already triaged, skip + +### 6. Handle No New Bugs + +If NO new bugs found: + +"No new bugs found in the manual input section. + +All items have already been triaged and are tracked in bugs.yaml. + +**Options:** +1. Add new bugs to docs/bugs.md (informal format) +2. View bugs.yaml to see structured bug tracking +3. Route existing triaged bugs to workflows + +[Q] Quit - nothing to triage" + +**HALT** - Do not proceed. + +### 7. Present Parsed Items + +"**Parsed {total_count} item(s) from manual input:** + +**New Bugs ({new_count}):** +{for each new bug:} +- {extracted_title} + - Description: {first 100 chars}... + - Platform: {platform or "not specified"} + - Related: {story or "not specified"} +{end for} + +**Feature Requests ({feature_count}):** +{for each feature:} +- {title} +{end for} + +**Already Triaged ({unchanged_count}):** +{list titles of skipped items} + +Ready to triage {new_count} new bug(s) and {feature_count} feature request(s). + +[C] Continue to triage +[E] Edit - re-parse with corrections +[Q] Quit" + +## SUCCESS METRICS: + +✅ Manual input section read efficiently (not entire file) +✅ All formats parsed correctly (headers, bullets, numbered) +✅ Existing bugs detected to prevent duplicates +✅ New vs updated vs unchanged correctly categorized +✅ User shown summary and can proceed + +## FAILURE MODES: + +❌ Reading entire bugs.md instead of section +❌ Missing bugs due to format not recognized +❌ Not detecting duplicates against bugs.yaml +❌ Starting triage in this step (should only parse) + +❌ **CRITICAL**: Reading only partial step file +❌ **CRITICAL**: Proceeding without user selection + +## NEXT STEP: + +After user selects [C], load `./step-04-triage.md` to perform triage analysis on each new bug. + +Remember: Do NOT proceed until user explicitly selects [C] from the menu! diff --git a/src/modules/bmm/workflows/bug-tracking/steps/step-04-triage.md b/src/modules/bmm/workflows/bug-tracking/steps/step-04-triage.md new file mode 100644 index 00000000..bd856f46 --- /dev/null +++ b/src/modules/bmm/workflows/bug-tracking/steps/step-04-triage.md @@ -0,0 +1,212 @@ +# Step 4: Triage Each Bug + +## MANDATORY EXECUTION RULES (READ FIRST): + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: ALWAYS read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding +- ✅ ALWAYS treat this as collaborative triage between peers +- 📋 YOU ARE A FACILITATOR - ask clarifying questions when needed +- đŸŽ¯ This step performs the CORE TRIAGE analysis +- ⚠ī¸ ABSOLUTELY NO TIME ESTIMATES - AI development speed varies widely +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +## EXECUTION PROTOCOLS: + +- đŸŽ¯ Triage ONE bug at a time with user confirmation +- 💾 Track triage decisions for bugs.yaml update +- 📖 Ask clarifying questions when severity/complexity unclear +- đŸšĢ FORBIDDEN to auto-triage without user review + +## CONTEXT BOUNDARIES: + +- Parsed bugs from step-03 are in memory +- Reference bugs.yaml header for severity/complexity definitions +- Reference epics.md for story mapping +- Each bug gets full triage analysis + +## YOUR TASK: + +Perform collaborative triage analysis on each parsed bug, assessing severity, complexity, effort, workflow routing, and documentation impact. + +## TRIAGE SEQUENCE (FOR EACH BUG): + +### 1. Generate Bug ID + +- Find highest existing bug-NNN from step-03 grep results +- Assign next sequential ID (e.g., bug-006) +- Format: `bug-` + zero-padded 3-digit number +- For features: `feature-` + zero-padded 3-digit number + +### 2. Assess Severity + +**Severity Levels:** +| Level | Criteria | +|-------|----------| +| critical | Prevents core functionality, crashes, data loss | +| high | Blocks major features, significantly degrades UX but has workaround | +| medium | Affects subset of users, minor impact | +| low | Cosmetic, edge case, minor inconvenience | + +**Analysis Questions:** +- Does it prevent core functionality? → critical +- Does it cause crashes or data loss? → critical +- Does it block major features? → high +- Does it significantly degrade UX but have workaround? → high +- Does it affect subset of users with minor impact? → medium +- Is it cosmetic or edge case? → low + +**If Unclear - ASK:** +"**Clarification needed for: {bug_title}** + +I need more information to assess severity: +1. Does this bug prevent users from completing core flows? +2. Does the bug cause crashes or data loss? +3. How many users are affected? (all users, specific platform, edge case) +4. Is there a workaround available? + +Please provide additional context." + +### 3. Assess Complexity + +**Complexity Levels:** +| Level | Criteria | +|-------|----------| +| trivial | One-line fix, obvious solution | +| small | Single file/component, solution clear | +| medium | Multiple files OR requires investigation | +| complex | Architectural change, affects many areas | + +**If Unclear - ASK:** +"**Clarification needed for: {bug_title}** + +To estimate complexity, I need: +1. Have you identified the root cause, or does it need investigation? +2. Which file(s) or component(s) are affected? +3. Is this isolated or does it affect multiple parts of the app? + +Please provide technical details if available." + +### 4. Determine Workflow Routing + +**Routing Matrix:** +| Severity | Complexity | Workflow | +|----------|------------|----------| +| critical | any | correct-course | +| high | trivial | direct-fix | +| high | small | tech-spec | +| high | medium/complex | correct-course | +| medium | trivial | direct-fix | +| medium | small | tech-spec | +| medium | medium/complex | correct-course | +| low | trivial | direct-fix | +| low | small+ | backlog | + +### 5. Map to Related Story/Epic + +- If bug mentions story ID (e.g., "2-7"), use that +- Otherwise, infer from description using epic keywords +- Reference epics.md for story matching +- Format: `{epic_number}-{story_number}` or null + +### 6. Determine Affected Platform + +Extract from description: +- `all` - Default if not specified +- `ios` - iOS only +- `android` - Android only +- `web` - Web only + +### 7. Assess Documentation Impact + +**PRD Impact** (`doc_impact.prd: true/false`) +Set TRUE if issue: +- Conflicts with stated product goals +- Requires changing MVP scope +- Adds/removes/modifies core functionality +- Changes success metrics +- Affects multiple epics + +**Architecture Impact** (`doc_impact.architecture: true/false`) +Set TRUE if issue: +- Requires new system components +- Changes data model (new tables, schema) +- Affects API contracts +- Introduces new dependencies +- Changes auth/security model + +**UX Impact** (`doc_impact.ux: true/false`) +Set TRUE if issue: +- Adds new screens or navigation +- Changes existing user flows +- Requires new UI components +- Affects accessibility + +**If any doc_impact is TRUE AND workflow != correct-course:** +- Override workflow to `correct-course` +- Add note: "Workflow elevated due to documentation impact" + +### 8. Add Triage Notes + +Document reasoning: +- Why this severity? (business impact, user impact) +- Why this complexity? (investigation needed, files affected) +- Why this workflow? (routing logic applied) +- Suggested next steps or investigation areas + +### 9. Present Triage for Confirmation + +"**Triage: {bug_id} - {bug_title}** + +| Field | Value | +|-------|-------| +| Severity | {severity} | +| Complexity | {complexity} | +| Platform | {platform} | +| Workflow | {recommended_workflow} | +| Related | {related_story or 'None'} | + +**Documentation Impact:** +- PRD: {yes/no} +- Architecture: {yes/no} +- UX: {yes/no} + +**Triage Notes:** +{triage_notes} + +[A] Accept triage +[M] Modify - adjust severity/complexity/workflow +[S] Skip - don't triage this item now +[N] Next bug (after accepting)" + +### 10. Handle Modifications + +If user selects [M]: +- Ask which field to modify +- Accept new value +- Re-present triage for confirmation + +## SUCCESS METRICS: + +✅ Each bug triaged with user confirmation +✅ Unclear items prompted for clarification +✅ Routing matrix applied correctly +✅ Documentation impact assessed +✅ Triage notes document reasoning + +## FAILURE MODES: + +❌ Auto-triaging without user review +❌ Not asking clarifying questions when needed +❌ Incorrect routing matrix application +❌ Missing documentation impact assessment +❌ Not documenting triage reasoning + +❌ **CRITICAL**: Reading only partial step file +❌ **CRITICAL**: Proceeding without user confirmation per bug + +## NEXT STEP: + +After ALL bugs triaged (user selected [A] or [N] for each), load `./step-05-update.md` to update bugs.yaml and bugs.md. + +Remember: Triage each bug individually with user confirmation! diff --git a/src/modules/bmm/workflows/bug-tracking/steps/step-05-update.md b/src/modules/bmm/workflows/bug-tracking/steps/step-05-update.md new file mode 100644 index 00000000..96c37977 --- /dev/null +++ b/src/modules/bmm/workflows/bug-tracking/steps/step-05-update.md @@ -0,0 +1,200 @@ +# Step 5: Update Files with Triaged Metadata + +## MANDATORY EXECUTION RULES (READ FIRST): + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: ALWAYS read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding +- ✅ ALWAYS treat this as collaborative triage between peers +- 📋 YOU ARE A FACILITATOR, not an automatic processor +- 💾 This step WRITES the triage results to files +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +## EXECUTION PROTOCOLS: + +- đŸŽ¯ Update both bugs.yaml and bugs.md atomically +- 💾 Preserve ALL existing data - append only +- 📖 Move items from manual input to tracked sections +- đŸšĢ FORBIDDEN to lose or corrupt existing data + +## CONTEXT BOUNDARIES: + +- Triage decisions from step-04 are in memory +- bugs.yaml structure defined in step-01 +- bugs.md sections: manual input, Tracked Bugs, Tracked Feature Requests, Fixed Bugs +- Preserve header comments and definitions + +## YOUR TASK: + +Write all triaged metadata to bugs.yaml and move triaged items from "# manual input" to appropriate tracked sections in bugs.md. + +## UPDATE SEQUENCE: + +### 1. Update bugs.yaml + +#### A. Load Existing Structure + +Read current bugs.yaml (if exists): +- Preserve ALL header comments and definitions +- Preserve existing `bugs:` array entries +- Preserve existing `features:` array entries +- Preserve existing `closed_bugs:` array + +#### B. Add New Bug Entries + +For each triaged bug, add to `bugs:` array: + +```yaml +- id: bug-NNN + title: "Bug title" + description: | + Full description text + Can be multi-line + severity: critical|high|medium|low + complexity: trivial|small|medium|complex + affected_platform: all|ios|android|web + recommended_workflow: direct-fix|tech-spec|correct-course|backlog + related_story: "X-Y" or null + status: triaged + reported_by: "Name" or null + reported_date: "YYYY-MM-DD" or null + triaged_date: "{date}" + doc_impact: + prd: true|false + architecture: true|false + ux: true|false + notes: "Impact description" or null + triage_notes: | + Reasoning for severity, complexity, workflow decisions + implemented_by: null + implemented_date: null + verified_by: null + verified_date: null +``` + +#### C. Add Feature Request Entries + +For features, add to `features:` array with similar structure. + +#### D. Update Statistics + +Recalculate statistics section: + +```yaml +statistics: + total_active: {count of non-closed bugs} + by_severity: + critical: {count} + high: {count} + medium: {count} + low: {count} + by_status: + triaged: {count} + implemented: {count} + verified: {count} + by_workflow: + direct-fix: {count} + tech-spec: {count} + correct-course: {count} + backlog: {count} + last_updated: "{date}" +``` + +#### E. Write bugs.yaml + +Write complete bugs.yaml file preserving all content. + +### 2. Update bugs.md + +#### A. Section-Based Reading + +Use grep to locate section line numbers: +- "# manual input" +- "# Tracked Bugs" +- "# Tracked Feature Requests" +- "# Fixed Bugs" + +Read only relevant sections with offset/limit. + +#### B. Remove from Manual Input + +For each triaged item: +- Remove the original entry from "# manual input" section +- Handle both header format and bullet format + +#### C. Add to Tracked Bugs + +For each triaged bug, add to "# Tracked Bugs" section: + +```markdown +### {bug_id}: {title} + +{brief_description} + +- **Severity:** {severity} +- **Complexity:** {complexity} +- **Platform:** {platform} +- **Workflow:** {workflow} +- **Related:** {story or "None"} +{if doc_impact flagged:} +- **Doc Impact:** {PRD|Architecture|UX as applicable} +{end if} + +**Notes:** {triage_notes_summary} + +--- +``` + +Create "# Tracked Bugs" section if it doesn't exist. + +#### D. Add to Tracked Feature Requests + +For features, add to "# Tracked Feature Requests" section with similar format. + +#### E. Write bugs.md + +Write updated bugs.md preserving all sections. + +### 3. Confirm Updates + +"**Files Updated:** + +**bugs.yaml:** +- Added {bug_count} new bug(s) +- Added {feature_count} new feature request(s) +- Total active bugs: {total_active} +- Statistics recalculated + +**bugs.md:** +- Removed {count} item(s) from manual input +- Added {bug_count} bug(s) to Tracked Bugs section +- Added {feature_count} feature(s) to Tracked Feature Requests section + +[C] Continue to summary +[R] Review changes - show diff +[U] Undo - restore previous state" + +## SUCCESS METRICS: + +✅ bugs.yaml updated with all triaged metadata +✅ bugs.md items moved from manual input to tracked sections +✅ Statistics accurately recalculated +✅ All existing data preserved +✅ User confirmed updates + +## FAILURE MODES: + +❌ Losing existing bugs.yaml entries +❌ Corrupting bugs.md structure +❌ Items remaining in manual input after triage +❌ Statistics not matching actual data +❌ Not preserving header comments/definitions + +❌ **CRITICAL**: Reading only partial step file +❌ **CRITICAL**: Proceeding without user confirmation + +## NEXT STEP: + +After user selects [C], load `./step-06-complete.md` to present final triage summary. + +Remember: Do NOT proceed until user explicitly selects [C] from the menu! diff --git a/src/modules/bmm/workflows/bug-tracking/steps/step-06-complete.md b/src/modules/bmm/workflows/bug-tracking/steps/step-06-complete.md new file mode 100644 index 00000000..191aee30 --- /dev/null +++ b/src/modules/bmm/workflows/bug-tracking/steps/step-06-complete.md @@ -0,0 +1,180 @@ +# Step 6: Triage Complete - Summary and Next Steps + +## MANDATORY EXECUTION RULES (READ FIRST): + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: ALWAYS read the complete step file before taking any action +- ✅ ALWAYS treat this as collaborative triage between peers +- 📋 YOU ARE A FACILITATOR, not an automatic processor +- 🎉 This is the FINAL step - present comprehensive summary +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +## EXECUTION PROTOCOLS: + +- đŸŽ¯ Present comprehensive triage summary +- 💾 All data already written in step-05 +- 📖 Guide user to next actions +- đŸšĢ FORBIDDEN to modify files in this step + +## CONTEXT BOUNDARIES: + +- All triage decisions finalized in previous steps +- bugs.yaml and bugs.md already updated +- This step is READ-ONLY presentation +- Focus on actionable next steps + +## YOUR TASK: + +Present a comprehensive summary of the triage session and guide the user to appropriate next actions based on workflow recommendations. + +## COMPLETION SEQUENCE: + +### 1. Present Triage Summary + +"**Bug Triage Complete, {user_name}!** + +--- + +## Triaged Items + +{for each triaged bug:} + +### {bug_id}: {bug_title} + +| Field | Value | +|-------|-------| +| Severity | {severity} | +| Complexity | {complexity} | +| Platform | {platform} | +| Workflow | {recommended_workflow} | +| Related | {related_story or 'None'} | + +{if doc_impact flagged:} +**Documentation Impact:** +- PRD: {yes/no} +- Architecture: {yes/no} +- UX: {yes/no} +- Notes: {doc_impact_notes} +{end if} + +**Triage Reasoning:** +{triage_notes} + +--- + +{end for} + +## Updated Files + +- **bugs.yaml** - Structured metadata for all triaged items +- **bugs.md** - Moved triaged items to Tracked sections + +--- + +## Statistics Summary + +| Metric | Count | +|--------|-------| +| Total Active Bugs | {total_active} | +| Critical | {critical_count} | +| High | {high_count} | +| Medium | {medium_count} | +| Low | {low_count} | + +{if any doc_impact flagged:} + +## Documentation Updates Required + +Items with documentation impact have been routed to `correct-course` workflow: +- PRD Impact: {prd_impact_count} item(s) +- Architecture Impact: {arch_impact_count} item(s) +- UX Impact: {ux_impact_count} item(s) +{end if} + +--- + +## Workflow Recommendations + +### Direct Fix ({direct_fix_count} items) +Quick fixes with obvious solutions. No spec needed. + +**Command:** `/implement bug-NNN` + +{list bug IDs for direct-fix} + +### Tech-Spec ({tech_spec_count} items) +Require technical specification before implementation. + +**Process:** Create tech-spec first, then `/implement` + +{list bug IDs for tech-spec} + +### Correct-Course ({correct_course_count} items) +Need impact analysis before proceeding. + +**Process:** Run correct-course workflow for impact analysis + +{list bug IDs for correct-course} + +### Backlog ({backlog_count} items) +Deferred - low priority items for future consideration. + +{list bug IDs for backlog} + +--- + +## Next Steps + +**To implement a bug fix:** +``` +/implement bug-NNN +``` + +**To verify after testing:** +``` +/verify bug-NNN +``` + +**To verify all implemented bugs:** +``` +/verify +``` + +**To list bugs by platform:** +``` +/list-bugs android +/list-bugs ios +``` + +--- + +Thank you for completing the triage session!" + +### 2. End Workflow + +The workflow is complete. No further steps. + +## SUCCESS METRICS: + +✅ Comprehensive summary presented +✅ All triaged items listed with metadata +✅ Statistics accurately displayed +✅ Workflow recommendations clear +✅ Next step commands provided +✅ User knows how to proceed + +## FAILURE MODES: + +❌ Incomplete summary missing items +❌ Statistics not matching bugs.yaml +❌ Unclear next step guidance +❌ Modifying files in this step (should be read-only) + +## WORKFLOW COMPLETE + +This is the final step. The bug tracking triage workflow is complete. + +User can now: +- Run `/implement bug-NNN` to fix bugs +- Run `/verify` to verify implemented bugs +- Add new bugs to bugs.md and run triage again diff --git a/src/modules/bmm/workflows/bug-tracking/workflow.md b/src/modules/bmm/workflows/bug-tracking/workflow.md new file mode 100644 index 00000000..cbf01d76 --- /dev/null +++ b/src/modules/bmm/workflows/bug-tracking/workflow.md @@ -0,0 +1,58 @@ +--- +name: bug-tracking +description: Triage user-reported bugs from bugs.md, generate structured metadata in bugs.yaml, and route to appropriate workflow +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: true +--- + +# Bug Tracking Workflow + +**Goal:** Transform informal bug reports into structured, actionable metadata with severity assessment, complexity estimation, and workflow routing recommendations. + +**Your Role:** You are a triage facilitator collaborating with a peer. This is a partnership, not a client-vendor relationship. You bring structured analysis and triage methodology, while the user brings domain expertise and context about their product. Work together to efficiently categorize and route bugs for resolution. + +--- + +## WORKFLOW ARCHITECTURE + +This uses **micro-file architecture** for disciplined execution: + +- Each step is a self-contained file with embedded rules +- Sequential progression with user control at each step +- State tracked via bugs.yaml metadata +- Append-only updates to bugs.md (move triaged items, never delete) +- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation. + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `output_folder`, `user_name` +- `communication_language`, `date` as system-generated current datetime +- `dev_ephemeral_location` for sprint-status.yaml location +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/bug-tracking` +- `bugs_input` = `{output_folder}/bugs.md` (user-facing bug reports) +- `bugs_output` = `{output_folder}/bugs.yaml` (agent-facing structured metadata) +- `sprint_status` = `{dev_ephemeral_location}/sprint-status.yaml` +- `epics_file` = `{output_folder}/epics.md` + +### Optional API Integration + +- `project_url` = configurable base URL for in-app bug report sync (default: `http://localhost:5173`) +- See `reference-implementation.md` for in-app bug reporting setup + +--- + +## EXECUTION + +Load and execute `steps/step-01-init.md` to begin the workflow. + +**Note:** Input file discovery and initialization protocols are handled in step-01-init.md. diff --git a/src/modules/bmm/workflows/bug-tracking/workflow.yaml b/src/modules/bmm/workflows/bug-tracking/workflow.yaml deleted file mode 100644 index 5fdaf22d..00000000 --- a/src/modules/bmm/workflows/bug-tracking/workflow.yaml +++ /dev/null @@ -1,32 +0,0 @@ -name: bug-tracking -description: "Triage user-reported bugs from bugs.md, generate structured metadata in bugs.yaml, and route to appropriate workflow" -author: "BMad" - -# Critical variables from config -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 - -# Workflow components -installed_path: "{project-root}/.bmad/bmm/workflows/bug-tracking" -instructions: "{installed_path}/instructions.md" -validation: "{installed_path}/checklist.md" -template: false # This is an action workflow, not a template workflow - -# Input and output files -variables: - bugs_input: "{output_folder}/bugs.md" # User-facing bug reports (informal) - bugs_output: "{output_folder}/bugs.yaml" # Agent-facing structured metadata - sprint_status: "{config_source}:dev_ephemeral_location/sprint-status.yaml" # For routing context - epics_file: "{output_folder}/epics.md" # For related story lookup - project_url: "http://localhost:5173" # Base URL for API calls (update for production) - -# Output configuration -default_output_file: "{bugs_output}" - -# Documentation -reference_implementation: "{installed_path}/reference-implementation.md" # Optional in-app reporting setup - -standalone: true