diff --git a/.gitignore b/.gitignore index 06938371..a93df5dc 100644 --- a/.gitignore +++ b/.gitignore @@ -72,3 +72,6 @@ bmad-custom-src/ website/.astro/ website/dist/ build/ + +# Fork-specific documentation (not committed) +BUG-TRACKING.md diff --git a/docs/bug-tracking/bug-tracking-workflow-README.md b/docs/bug-tracking/bug-tracking-workflow-README.md new file mode 100644 index 00000000..bab00f47 --- /dev/null +++ b/docs/bug-tracking/bug-tracking-workflow-README.md @@ -0,0 +1,536 @@ +# Bug Tracking Workflow Wireframe + +## Quick Reference + +``` +COMMANDS: + /triage - Triage new bugs from bugs.md + /implement bug-NNN - Implement a bug fix + /implement feature-N - Implement a feature + /verify - List pending verification + /verify bug-NNN - Verify and close specific bug + /verify all - Batch verify all + +FILES: + docs/bugs.md - Human-readable bug tracking + docs/bugs.yaml - Agent-readable metadata + +SEVERITY → COMPLEXITY → WORKFLOW ROUTING: + ┌──────────┬─────────┬─────────┬─────────┬─────────┐ + │ │ TRIVIAL │ SMALL │ MEDIUM │ COMPLEX │ + ├──────────┼─────────┼─────────┼─────────┼─────────┤ + │ CRITICAL │ correct-course (any complexity) │ + ├──────────┼─────────┼─────────┼─────────┼─────────┤ + │ HIGH │direct-fx│tech-spec│corr-crs │corr-crs │ + ├──────────┼─────────┼─────────┼─────────┼─────────┤ + │ MEDIUM │direct-fx│tech-spec│corr-crs │corr-crs │ + ├──────────┼─────────┼─────────┼─────────┼─────────┤ + │ LOW │direct-fx│ backlog │ backlog │ backlog │ + └──────────┴─────────┴─────────┴─────────┴─────────┘ + +SEVERITY: + critical - Core broken, crashes, data loss + high - Major feature blocked, workaround exists + medium - Partial breakage, minor impact + low - Cosmetic, edge case + +COMPLEXITY: + trivial - One-liner, minimal change + small - Single file change + medium - Multi-file change + complex - Architectural change + +STATUS FLOW: + reported → triaged → [routed] → in-progress → fixed/implemented → verified → closed + +STATUS VALUES: + triaged - Analyzed, routed, awaiting implementation + routed - Sent to tech-spec or correct-course workflow + in-progress - Developer actively working + fixed - Code complete, awaiting verification (bugs) + implemented - Code complete, awaiting verification (features) + closed - Verified and closed + backlog - Deferred to future sprint + blocked - Cannot proceed until issue resolved +``` + +--- + +## Part 1: System Architecture + +### System Overview + +``` + INPUT SOURCES + +-------------------+ +-------------------+ +-------------------+ + | IN-APP MODAL | | MANUAL ENTRY | | EXTERNAL ISSUE | + | (Optional API) | | (bugs.md) | | TRACKER IMPORT | + +--------+----------+ +--------+----------+ +--------+----------+ + | | | + +------------+------------+-------------------------+ + | + v + +============================+ + | /triage (WORKFLOW) | + +============================+ + | + +---------------+---------------+---------------+ + | | | | + v v v v + direct-fix tech-spec correct-course backlog + | | | | + v v v v + /implement /tech-spec /correct-course (deferred) + | | | + +---------------+---------------+ + | + v + /verify → CLOSED +``` + +### File Architecture + +``` +{project-root}/ + docs/ + bugs.md <-- User-facing: informal bug reports & tracking + bugs.yaml <-- Agent-facing: structured metadata database + epics.md <-- Context: for mapping bugs to stories + _bmad/bmm/ + config.yaml <-- Project configuration + workflows/ + bug-tracking/ <-- Triage workflow files + implement/ <-- Implementation workflow + verify/ <-- Verification workflow +``` + +### bugs.md Structure + +```markdown +# Bug Tracking - {project_name} + +# manual input +## Bug: Login fails on iOS Safari +Description of the bug... +Reported by: User Name +Date: 2025-01-15 + +- **Crash on startup (Android)**: App crashes immediately. CRITICAL. + +1. Form validation missing - No validation on email field + +--- + +# Tracked Bugs +### bug-001: Login fails on iOS Safari +Brief description... +- **Severity:** high +- **Complexity:** small +- **Workflow:** tech-spec +- **Related:** story-2-3 +**Notes:** Triage reasoning... + +--- + +# Tracked Feature Requests +### feature-001: Dark mode toggle +Brief description... +- **Priority:** medium +- **Complexity:** medium +- **Workflow:** tech-spec + +--- + +# Fixed Bugs +[IMPLEMENTED] bug-003: Header alignment [Sev: low, Fixed: 2025-01-18, Verified: pending] + - Fix: Adjusted flexbox styling + - File(s): src/components/Header.tsx + +bug-002: Form submission error [Sev: medium, Fixed: 2025-01-15, Verified: 2025-01-16, CLOSED] + - Fix: Added error boundary + +--- + +# Implemented Features +[IMPLEMENTED] feature-002: Export to CSV [Impl: 2025-01-20, Verified: pending] + - Files: src/export.ts, src/utils/csv.ts +``` + +--- + +## Part 2: Workflow Operations + +### Slash Command Reference + +| Command | Description | When to Use | +|---------|-------------|-------------| +| `/triage` | Main workflow - triage user-reported bugs | When new bugs are in bugs.md | +| `/implement bug-NNN` | Implement a specific bug fix | After triage, routed for direct-fix | +| `/implement feature-NNN` | Implement a feature request | After feature is triaged | +| `/verify` | List all pending verification | After implementation, before closing | +| `/verify bug-NNN` | Verify and close specific bug | After testing confirms fix works | +| `/verify all` | Batch verify all pending items | Bulk close multiple fixes | + +### /triage Workflow + +``` +USER INVOKES: /triage + | + v ++---------------------------+ +| STEP 1: INITIALIZATION | ++---------------------------+ +| - Load config.yaml | +| - Check for bugs.yaml | +| - Detect existing session | ++------------+--------------+ + | + +--------+--------+ + | | + v v ++-------------+ +-------------+ +| Has pending | | Fresh start | +| triaged work| +------+------+ ++------+------+ | + | v + v +-------------+ ++-------------+ | Scan manual | +| Show status | | input section| +| [T/I/V/L/Q] | +------+------+ ++-------------+ | + v + +-------------+ + | [S/C/Q] | + | Sync/Cont/Q | + +------+------+ + | + +---------------+---------------+ + v v v + [S] API Sync [C] Continue [Q] Quit + ++---------------------------+ +| STEP 2: API SYNC | (Optional - if [S] selected) ++---------------------------+ +| GET /api/bug-reports/pending +| - Fetch, format, insert to bugs.md +| - POST /mark-synced ++---------------------------+ + ++---------------------------+ +| STEP 3: PARSE | ++---------------------------+ +| Read "# manual input" only +| - Parse headers, bullets, numbered lists +| - Extract: title, desc, reporter, platform +| - Compare with bugs.yaml (NEW vs EXISTING) ++------------+--------------+ + | + +--------+--------+ + v v +No new bugs {N} new bugs + [HALT] [C] Continue + | + v ++---------------------------+ +| STEP 4: TRIAGE (per bug) | ++---------------------------+ +| FOR EACH NEW BUG: +| 1. Generate bug-NNN ID +| 2. Assess SEVERITY (critical|high|med|low) +| 3. Assess COMPLEXITY (trivial|small|med|complex) +| 4. Apply ROUTING MATRIX → workflow +| 5. Map to story/epic if applicable +| 6. Assess DOC IMPACT (prd|architecture|ux) +| 7. Add triage notes +| 8. Present: [A]ccept/[M]odify/[S]kip/[N]ext ++---------------------------+ + | + v (after all bugs) ++---------------------------+ +| STEP 5: UPDATE FILES | ++---------------------------+ +| bugs.yaml: Add entries, update stats +| bugs.md: Remove from manual input, +| Add to Tracked Bugs/Features ++---------------------------+ + | + v ++---------------------------+ +| STEP 6: COMPLETE | ++---------------------------+ +| Show summary + next steps: +| /implement bug-NNN +| /verify bug-NNN ++---------------------------+ +``` + +### /implement Workflow + +``` +USER INVOKES: /implement bug-NNN + | + v + +-------------------------------+ + | STEP 1-2: Load Context | + +-------------------------------+ + | - Parse ID (bug-NNN/feature-NNN) + | - Load from bugs.yaml + | - Check status (halt if backlog/blocked/deferred) + +---------------+---------------+ + | + v + +-------------------------------+ + | STEP 3: Check Workflow Route | + +-------------------------------+ + | + +-----------+-----------+-----------+ + v v v v + correct- tech-spec direct-fix ambiguous + course | + | | | Apply Matrix + v v | + [ROUTES TO [ROUTES TO | + /correct- /tech-spec | + course] workflow] | + | | | + v v v + Creates Creates +--------+ + story spec | STEP 4:| + | Confirm| + +---+----+ + | + v + +---------------+ + | STEP 5: | + | IMPLEMENT | + +---------------+ + | Dev Agent: | + | - Read files | + | - Make changes| + | - Minimal fix | + +-------+-------+ + | + v + +---------------+ + | STEP 6: Check | + | npm run check | + +-------+-------+ + | + v + +---------------+ + | STEP 7-8: | + | Update Files | + +---------------+ + | bugs.yaml: | + | status: fixed| + | bugs.md: | + | [IMPLEMENTED]| + +-------+-------+ + | + v + +---------------+ + | STEP 9: | + | "Run /verify" | + +---------------+ +``` + +### /verify Workflow + +``` +USER INVOKES: /verify [bug-NNN] + | + +-----------+-----------+ + v v ++---------------+ +---------------+ +| No ID given | | ID provided | ++-------+-------+ +-------+-------+ + | | + v | ++---------------+ | +| List pending | | +| [IMPLEMENTED] | | +| items | | ++-------+-------+ | + | | + +-------+---------------+ + | + v ++-------------------------------+ +| STEP 2: Load & Validate | ++-------------------------------+ +| - Verify status: fixed/implemented +| - Check file sync ++---------------+---------------+ + | + v ++-------------------------------+ +| STEP 3: Confirm Verification | ++-------------------------------+ +| Show: Title, type, date, files +| "Has this been tested?" +| [yes | no | skip] ++---------------+---------------+ + | + +-----------+-----------+ + v v v ++-------+ +-------+ +-------+ +| YES | | NO | | SKIP | ++---+---+ +---+---+ +---+---+ + | | | + v v v +Step 4 Add note Next item + "rework" + ++-------------------------------+ +| STEP 4-5: Update Files | ++-------------------------------+ +| bugs.yaml: status: closed, +| verified_date +| bugs.md: Remove [IMPLEMENTED], +| Add CLOSED tag ++-------------------------------+ + | + v ++-------------------------------+ +| STEP 6: Summary | +| "bug-NNN VERIFIED and CLOSED" | ++-------------------------------+ +``` + +--- + +## Part 3: Routing & Agent Delegation + +### Workflow Routing by Type + +| Workflow | Trigger Conditions | Pre-Implement Phase | Implementation Phase | +|----------|-------------------|---------------------|---------------------| +| **direct-fix** | high/med + trivial | None | Dev Agent in /implement Step 5 | +| **tech-spec** | high/med + small | Architect creates spec | /dev-story per spec | +| **correct-course** | critical (any) OR med/complex+ OR doc_impact | PM→Architect→SM create story | /dev-story per story | +| **backlog** | low + small+ | None (deferred) | Awaits sprint promotion | + +### Agent Responsibilities + +``` + /triage + | + v + +------------------------+ + | SM AGENT (Scrum | + | Master Facilitator) | + +------------------------+ + | - Runs triage workflow | + | - Assesses severity | + | - Routes to workflows | + +-----------+------------+ + | + +-------------------+-------------------+ + v v v ++------------+ +------------+ +------------+ +| Direct-Fix | | Tech-Spec | | Correct- | ++-----+------+ +-----+------+ | Course | + | | +-----+------+ + v v | ++------------+ +------------+ v +| DEV AGENT | | ARCHITECT | +------------+ +| /implement | | /tech-spec | | PM AGENT | +| Step 5 | +-----+------+ | + ARCHITECT| ++------------+ | | + SM | + v +-----+------+ + +------------+ | + | DEV AGENT | v + | /dev-story | +------------+ + +------------+ | DEV AGENT | + | /dev-story | + +------------+ +``` + +### Doc Impact Routing + +When `doc_impact` flags are detected during /implement: + +| Flag | Agent | Action | +|------|-------|--------| +| PRD | PM Agent | Update PRD.md | +| Architecture | Architect Agent | Update architecture.md | +| UX | UX Designer Agent | Update UX specs | + +User is prompted: `[update-docs-first | proceed-anyway | cancel]` + +--- + +## Part 4: State & Lifecycle + +### File State Transitions + +``` +═══════════════════════════════════════════════════════════════════════════════ + DIRECT-FIX TECH-SPEC CORRECT-COURSE BACKLOG +═══════════════════════════════════════════════════════════════════════════════ + +ENTRY # manual input # manual input # manual input # manual input + (informal text) (informal text) (informal text) (informal text) + │ │ │ │ + ▼ ▼ ▼ ▼ +───────────────────────────────────────────────────────────────────────────────── +TRIAGE # Tracked Bugs # Tracked Bugs # Tracked Bugs # Tracked Bugs + bug-NNN bug-NNN bug-NNN bug-NNN + wf: direct-fix wf: tech-spec wf: correct-crs wf: backlog + │ │ │ │ + ▼ ▼ ▼ │ +───────────────────────────────────────────────────────────────────────────────── +ROUTE (skip) /tech-spec /correct-course (waiting) + creates spec creates story │ + │ │ │ │ + ▼ ▼ ▼ │ +───────────────────────────────────────────────────────────────────────────────── +CODE /implement /dev-story /dev-story (waiting) + Step 5 per spec per story │ + │ │ │ │ + ▼ ▼ ▼ │ +───────────────────────────────────────────────────────────────────────────────── +IMPL # Fixed Bugs # Fixed Bugs # Fixed Bugs (unchanged) + [IMPLEMENTED] [IMPLEMENTED] [IMPLEMENTED] │ + bug-NNN bug-NNN bug-NNN │ + │ │ │ │ + ▼ ▼ ▼ │ +───────────────────────────────────────────────────────────────────────────────── +VERIFY /verify /verify /verify (waiting) + bug-NNN bug-NNN bug-NNN │ + │ │ │ │ + ▼ ▼ ▼ ▼ +───────────────────────────────────────────────────────────────────────────────── +DONE CLOSED ✓ CLOSED ✓ CLOSED ✓ WAITING ◷ +═══════════════════════════════════════════════════════════════════════════════ + +FILE STATE SUMMARY: +┌──────────┬─────────────────────────────┬──────────────────────────────────┐ +│ STAGE │ bugs.md │ bugs.yaml │ +├──────────┼─────────────────────────────┼──────────────────────────────────┤ +│ Entry │ # manual input │ (no entry) │ +├──────────┼─────────────────────────────┼──────────────────────────────────┤ +│ Triage │ → # Tracked Bugs/Features │ status: triaged + metadata │ +├──────────┼─────────────────────────────┼──────────────────────────────────┤ +│ Implement│ → # Fixed [IMPLEMENTED] │ status: fixed/implemented │ +├──────────┼─────────────────────────────┼──────────────────────────────────┤ +│ Verify │ [IMPLEMENTED] → CLOSED │ status: closed + verified_date │ +└──────────┴─────────────────────────────┴──────────────────────────────────┘ +``` + +--- + +## Appendix: Optional Extensions + +### In-App Bug Reporting API + +Optional integration for apps with built-in bug reporting UI: + +1. **User submits** via in-app modal → `POST /api/bug-reports` +2. **Database stores** with `status: 'new'` +3. **During /triage Step 2** (if [S]ync selected): + - `GET /api/bug-reports/pending` fetches new reports + - Formats as markdown, inserts to `# manual input` + - `POST /api/bug-reports/mark-synced` prevents re-fetch + +This is optional - manual entry to bugs.md works without any API. 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 e5649559..23561327 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml @@ -214,11 +214,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/retrospective/instructions.md b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md index 01750312..103c55d3 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md @@ -1300,7 +1300,67 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!" - + +Check bugs.yaml for bugs/features linked to this epic and close them + +Load {bugs_yaml} if it exists + + + Search for entries with related_epic matching {{epic_number}} + + For bugs section - find bugs with related_epic == {{epic_number}} AND status in ["fixed", "triaged", "routed"]: + + For each matching bug: + - Move entry from "bugs" section to "closed_bugs" section + - Update status: → "closed" + - Set verified_by: "retrospective-workflow" + - Set verified_date: {date} + - Append to notes: "Auto-closed via epic retrospective. Epic {{epic_number}} completed on {date}." + + + For feature_requests section - find features with related_epic == {{epic_number}} AND status in ["implemented", "backlog", "in-progress"]: + + For each matching feature: + - Move entry from "feature_requests" section to "implemented_features" section + - Update status: → "complete" + - Set completed_by: "retrospective-workflow" + - Set completed_date: {date} + - Append to notes: "Auto-closed via epic retrospective. Epic {{epic_number}} completed on {date}." + + + Update statistics section with new counts + Save updated bugs.yaml + + + Also update bugs.md: + - Remove [IMPLEMENTED] tag from closed items + - Move bug entries to "# Fixed Bugs" section if not already there + - Move feature entries to "# Implemented Features" section if not already there + - Add [CLOSED] or [COMPLETE] tag to indicate final status + Save updated bugs.md + + + +Bug/Feature Closure: +{{#if bugs_closed}} +- Bugs closed for Epic {{epic_number}}: {{bugs_closed_list}} +{{/if}} +{{#if features_completed}} +- Features completed for Epic {{epic_number}}: {{features_completed_list}} +{{/if}} +{{#if no_matches}} +- No outstanding bugs/features linked to Epic {{epic_number}} +{{/if}} + + + + + Skip bug tracking sync - no bugs.yaml file present + + + + + Ensure retrospectives folder exists: {retrospectives_folder} Create folder if it doesn't exist @@ -1356,7 +1416,7 @@ Retrospective document was saved successfully, but {sprint_status_file} may need - + **✅ Retrospective Complete, {user_name}!** diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml index 80d934b2..68c8dd59 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml @@ -54,5 +54,9 @@ sprint_status_file: "{implementation_artifacts}/sprint-status.yaml" story_directory: "{implementation_artifacts}" retrospectives_folder: "{implementation_artifacts}" +# Bug tracking integration (optional) +bugs_yaml: "{planning_artifacts}/bugs.yaml" +bugs_md: "{planning_artifacts}/bugs.md" + standalone: true web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md index c4f4bd42..0ebe9e9c 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md @@ -48,6 +48,26 @@ After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy) + +Check if {bugs_yaml} exists in {planning_artifacts} + + Read bugs.yaml using grep to find all bug-NNN and feature-NNN entries + For each bug/feature, extract: + - ID (e.g., bug-001, feature-003) + - Title + - Status (triaged, routed, in-progress, fixed/implemented, verified, closed) + - Recommended workflow (direct-fix, tech-spec, correct-course, backlog) + - Related stories (sprint_stories field for features) + + Build bug/feature inventory for inclusion in sprint status + Track feature-to-story mappings (feature-001 → stories 7-1, 7-2, etc.) + + + Note: No bugs.yaml found - bug tracking not enabled for this project. + Continue without bug integration + + + For each epic found, create entries in this order: @@ -65,6 +85,17 @@ development_status: epic-1-retrospective: optional ``` +If bugs.yaml was loaded, add bug/feature sources header comment: + +```yaml +# STORY SOURCES: +# ============== +# - epics.md: Primary source ({story_count} stories) +# - bugs.yaml: Feature-driven stories ({feature_story_count} stories from sprint_stories) +# - feature-001: 7-1, 7-2, 7-3 (from sprint_stories field) +# - feature-002: 3-7 +``` + diff --git a/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml b/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml index 50998f0a..196040fc 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml @@ -33,6 +33,10 @@ variables: epics_location: "{planning_artifacts}" # Directory containing epic*.md files epics_pattern: "epic*.md" # Pattern to find epic files + # Bug tracking integration (optional) + bugs_yaml: "{planning_artifacts}/bugs.yaml" # Structured bug/feature metadata + bugs_md: "{planning_artifacts}/bugs.md" # Human-readable bug tracking + # Output configuration status_file: "{implementation_artifacts}/sprint-status.yaml" diff --git a/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md b/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md index 978b9229..ab6c4279 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md @@ -88,15 +88,31 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho - IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories" + + Check if {bugs_yaml} exists + + Grep for bug-NNN and feature-NNN entries with status field + Count items by status: triaged, fixed/implemented (pending verify), verified, closed + Identify items needing action: + - Items with [IMPLEMENTED] tag → need verification + - Items with status "triaged" + workflow "direct-fix" → ready for implementation + + Store: bugs_pending_verify, bugs_triaged, features_pending_verify, features_triaged + + + Pick the next recommended workflow using priority: When selecting "first" story: sort by epic number, then story number (e.g., 1-1 before 1-2 before 2-1) - 1. If any story status == in-progress → recommend `dev-story` for the first in-progress story - 2. Else if any story status == review → recommend `code-review` for the first review story - 3. Else if any story status == ready-for-dev → recommend `dev-story` - 4. Else if any story status == backlog → recommend `create-story` - 5. Else if any retrospective status == optional → recommend `retrospective` - 6. Else → All implementation items done; suggest `workflow-status` to plan next phase + Bug verification takes priority over new story work to close the feedback loop + 1. If any bug/feature has [IMPLEMENTED] tag (pending verify) → recommend `verify` for first pending item + 2. If any story status == in-progress → recommend `dev-story` for the first in-progress story + 3. Else if any story status == review → recommend `code-review` for the first review story + 4. Else if any story status == ready-for-dev → recommend `dev-story` + 5. Else if any bug status == triaged with workflow == direct-fix → recommend `implement` for first triaged bug + 6. Else if any story status == backlog → recommend `create-story` + 7. Else if any retrospective status == optional → recommend `retrospective` + 8. Else → All implementation items done; suggest `workflow-status` to plan next phase Store selected recommendation as: next_story_id, next_workflow_id, next_agent (SM/DEV as appropriate) @@ -112,6 +128,11 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho **Epics:** backlog {{epic_backlog}}, in-progress {{epic_in_progress}}, done {{epic_done}} +{{#if bugs_yaml_exists}} +**Bugs:** triaged {{bugs_triaged}}, pending-verify {{bugs_pending_verify}}, closed {{bugs_closed}} +**Features:** triaged {{features_triaged}}, pending-verify {{features_pending_verify}}, complete {{features_complete}} +{{/if}} + **Next Recommendation:** /bmad:bmm:workflows:{{next_workflow_id}} ({{next_story_id}}) {{#if risks}} diff --git a/src/modules/bmm/workflows/4-implementation/sprint-status/workflow.yaml b/src/modules/bmm/workflows/4-implementation/sprint-status/workflow.yaml index 6f10a9a6..16f40838 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-status/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/sprint-status/workflow.yaml @@ -21,6 +21,9 @@ instructions: "{installed_path}/instructions.md" variables: sprint_status_file: "{implementation_artifacts}/sprint-status.yaml" tracking_system: "file-system" + # Bug tracking integration (optional) + bugs_yaml: "{planning_artifacts}/bugs.yaml" + bugs_md: "{planning_artifacts}/bugs.md" # Smart input file references input_file_patterns: diff --git a/src/modules/bmm/workflows/4-implementation/story-done/instructions.md b/src/modules/bmm/workflows/4-implementation/story-done/instructions.md new file mode 100644 index 00000000..b73ae12c --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/story-done/instructions.md @@ -0,0 +1,124 @@ +# Story Approved Workflow Instructions (DEV Agent) + +The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} + + + +This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete) +Workflow: Update story file status to Done + + + + + Use {story_path} directly + Read COMPLETE story file and parse sections + Extract story_key from filename or story metadata + Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to mark as done" + + + + MUST read COMPLETE sprint-status.yaml file from start to end to preserve order + Load the FULL file: {output_folder}/sprint-status.yaml + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely + +Find FIRST story (reading in order from top to bottom) where: - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - Status value equals "review" + + + + No stories with status "review" found + +All stories are either still in development or already done. + +**Next Steps:** + +1. Run `dev-story` to implement stories +2. Run `code-review` if stories need review first +3. Check sprint-status.yaml for current story states + + HALT + + +Use the first reviewed story found +Find matching story file in {story_dir} using story_key pattern +Read the COMPLETE story file + + +Extract story_id and story_title from the story file + +Find the "Status:" line (usually at the top) +Update story file: Change Status to "done" + +Add completion notes to Dev Agent Record section: +Find "## Dev Agent Record" section and add: + +``` +### Completion Notes +**Completed:** {date} +**Definition of Done:** All acceptance criteria met, code reviewed, tests passing +``` + + + +Save the story file + + + +Load the FULL file: {output_folder}/sprint-status.yaml +Find development_status key matching {story_key} +Verify current status is "review" (expected previous state) +Update development_status[{story_key}] = "done" +Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + Story file updated, but could not update sprint-status: {story_key} not found + +Story is marked Done in file, but sprint-status.yaml may be out of sync. + + + + + + +Invoke shared task to sync bugs.yaml and bugs.md for this completed story + + + {story_key} + {story_id} + {bugs_yaml} + {bugs_md} + {sprint_status} + {date} + + + + + + +**Story Approved and Marked Done, {user_name}!** + +Story file updated - Status: done +Sprint status updated: review → done + +**Completed Story:** + +- **ID:** {story_id} +- **Key:** {story_key} +- **Title:** {story_title} +- **Completed:** {date} + +**Next Steps:** + +1. Continue with next story in your backlog + - Run `create-story` for next backlog story + - Or run `dev-story` if ready stories exist +2. Check epic completion status + - Run `retrospective` workflow to check if epic is complete + - Epic retrospective will verify all stories are done + + + + + diff --git a/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml new file mode 100644 index 00000000..d7001c95 --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml @@ -0,0 +1,27 @@ +# Story Done Workflow (DEV Agent) +name: story-done +description: 'Marks a story as done (DoD complete), updates sprint-status → DONE, and syncs related bugs/features in bugs.yaml/bugs.md to [IMPLEMENTED] status.' +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 +sprint_status: '{output_folder}/sprint-status.yaml' + +# Workflow components +installed_path: '{project-root}/.bmad/bmm/workflows/4-implementation/story-done' +instructions: '{installed_path}/instructions.md' + +# Variables and inputs +variables: + story_dir: '{config_source}:dev_ephemeral_location/stories' # Directory where stories are stored + bugs_yaml: '{output_folder}/bugs.yaml' # Bug/feature tracking structured data + bugs_md: '{output_folder}/bugs.md' # Bug/feature tracking human-readable log + +# Output configuration - no output file, just status updates +default_output_file: '' + +standalone: true diff --git a/src/modules/bmm/workflows/bug-tracking/reference-implementation.md b/src/modules/bmm/workflows/bug-tracking/reference-implementation.md new file mode 100644 index 00000000..2fa43700 --- /dev/null +++ b/src/modules/bmm/workflows/bug-tracking/reference-implementation.md @@ -0,0 +1,542 @@ +# In-App Bug Reporting - Reference Implementation + +This document provides a reference implementation for adding **in-app bug reporting** to your project. The BMAD bug-tracking workflow works without this feature (using manual `bugs.md` input), but in-app reporting provides a better user experience. + +## Overview + +The in-app bug reporting feature allows users to submit bug reports directly from your application. Reports are stored in your database and then synced to `bugs.md` by the triage workflow. + +``` +User -> UI Modal -> API -> Database -> Triage Workflow -> bugs.md/bugs.yaml +``` + +## Components Required + +| Component | Purpose | Stack-Specific | +|-----------|---------|----------------| +| Database table | Store pending bug reports | Yes | +| API: Create report | Accept user submissions | Yes | +| API: Get pending | Fetch unsynced reports | Yes | +| API: Mark synced | Update status after sync | Yes | +| UI Modal | Bug report form | Yes | +| Validation schemas | Input validation | Partially | + +## 1. Database Schema + +### Drizzle ORM (PostgreSQL) + +```typescript +// src/lib/server/db/schema.ts + +import { pgTable, uuid, text, timestamp, index } from 'drizzle-orm/pg-core'; + +export const bugReports = pgTable( + 'bug_reports', + { + id: uuid('id').primaryKey().defaultRandom(), + organizationId: uuid('organization_id').notNull(), // For multi-tenant apps + reporterType: text('reporter_type').notNull(), // 'staff' | 'member' | 'user' + reporterId: uuid('reporter_id').notNull(), + title: text('title').notNull(), + description: text('description').notNull(), + userAgent: text('user_agent'), + pageUrl: text('page_url'), + platform: text('platform'), // 'Windows', 'macOS', 'iOS', etc. + browser: text('browser'), // 'Chrome', 'Safari', 'Firefox' + screenshotUrl: text('screenshot_url'), // Optional: cloud storage URL + status: text('status').notNull().default('new'), // 'new' | 'synced' | 'dismissed' + createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(), + syncedAt: timestamp('synced_at', { withTimezone: true }) + }, + (table) => [ + index('bug_reports_organization_id_idx').on(table.organizationId), + index('bug_reports_status_idx').on(table.status), + index('bug_reports_created_at_idx').on(table.createdAt) + ] +); + +export const BUG_REPORT_STATUS = { + NEW: 'new', + SYNCED: 'synced', + DISMISSED: 'dismissed' +} as const; + +export const REPORTER_TYPE = { + STAFF: 'staff', + MEMBER: 'member', + USER: 'user' +} as const; +``` + +### Prisma Schema + +```prisma +model BugReport { + id String @id @default(uuid()) + organizationId String @map("organization_id") + reporterType String @map("reporter_type") + reporterId String @map("reporter_id") + title String + description String + userAgent String? @map("user_agent") + pageUrl String? @map("page_url") + platform String? + browser String? + screenshotUrl String? @map("screenshot_url") + status String @default("new") + createdAt DateTime @default(now()) @map("created_at") + syncedAt DateTime? @map("synced_at") + + @@index([organizationId]) + @@index([status]) + @@index([createdAt]) + @@map("bug_reports") +} +``` + +## 2. Validation Schemas + +### Zod (TypeScript) + +```typescript +// src/lib/schemas/bug-report.ts + +import { z } from 'zod'; + +export const createBugReportSchema = z.object({ + title: z + .string() + .trim() + .min(5, 'Title must be at least 5 characters') + .max(200, 'Title must be 200 characters or less'), + description: z + .string() + .trim() + .min(10, 'Description must be at least 10 characters') + .max(5000, 'Description must be 5000 characters or less'), + pageUrl: z.string().url().optional(), + userAgent: z.string().max(1000).optional(), + platform: z.string().max(50).optional(), + browser: z.string().max(50).optional() +}); + +export const markSyncedSchema = z.object({ + ids: z.array(z.string().uuid()).min(1, 'At least one ID is required') +}); + +export const SCREENSHOT_CONFIG = { + maxSizeBytes: 5 * 1024 * 1024, // 5MB + maxSizeMB: 5, + allowedTypes: ['image/jpeg', 'image/png', 'image/webp'] as const +} as const; +``` + +## 3. API Endpoints + +### POST /api/bug-reports - Create Report + +```typescript +// SvelteKit: src/routes/api/bug-reports/+server.ts + +import { json } from '@sveltejs/kit'; +import type { RequestHandler } from './$types'; +import { db } from '$lib/server/db'; +import { bugReports } from '$lib/server/db/schema'; +import { createBugReportSchema } from '$lib/schemas/bug-report'; + +export const POST: RequestHandler = async ({ request, locals }) => { + // Determine reporter from auth context + if (!locals.user) { + return json({ error: { code: 'UNAUTHORIZED' } }, { status: 401 }); + } + + const body = await request.json(); + const result = createBugReportSchema.safeParse(body); + + if (!result.success) { + return json({ + error: { code: 'VALIDATION_ERROR', message: result.error.issues[0]?.message } + }, { status: 400 }); + } + + const { title, description, pageUrl, userAgent, platform, browser } = result.data; + + const [newReport] = await db + .insert(bugReports) + .values({ + organizationId: locals.user.organizationId, + reporterType: 'staff', + reporterId: locals.user.id, + title, + description, + pageUrl, + userAgent, + platform, + browser + }) + .returning(); + + return json({ + data: { + bugReport: { + id: newReport.id, + title: newReport.title, + createdAt: newReport.createdAt.toISOString() + } + } + }, { status: 201 }); +}; +``` + +### GET /api/bug-reports/pending - Fetch for Triage + +```typescript +// SvelteKit: src/routes/api/bug-reports/pending/+server.ts + +import { json } from '@sveltejs/kit'; +import type { RequestHandler } from './$types'; +import { db } from '$lib/server/db'; +import { bugReports, BUG_REPORT_STATUS } from '$lib/server/db/schema'; +import { eq } from 'drizzle-orm'; + +export const GET: RequestHandler = async () => { + const reports = await db + .select() + .from(bugReports) + .where(eq(bugReports.status, BUG_REPORT_STATUS.NEW)) + .orderBy(bugReports.createdAt); + + // Map to workflow-expected format + const formatted = reports.map((r) => ({ + id: r.id, + title: r.title, + description: r.description, + reporterType: r.reporterType, + reporterName: 'Unknown', // Join with users table for real name + platform: r.platform, + browser: r.browser, + pageUrl: r.pageUrl, + screenshotUrl: r.screenshotUrl, + createdAt: r.createdAt.toISOString() + })); + + return json({ + data: { + reports: formatted, + count: formatted.length + } + }); +}; +``` + +### POST /api/bug-reports/mark-synced - Update After Sync + +```typescript +// SvelteKit: src/routes/api/bug-reports/mark-synced/+server.ts + +import { json } from '@sveltejs/kit'; +import type { RequestHandler } from './$types'; +import { db } from '$lib/server/db'; +import { bugReports, BUG_REPORT_STATUS } from '$lib/server/db/schema'; +import { inArray } from 'drizzle-orm'; +import { markSyncedSchema } from '$lib/schemas/bug-report'; + +export const POST: RequestHandler = async ({ request }) => { + const body = await request.json(); + const result = markSyncedSchema.safeParse(body); + + if (!result.success) { + return json({ + error: { code: 'VALIDATION_ERROR', message: result.error.issues[0]?.message } + }, { status: 400 }); + } + + const updated = await db + .update(bugReports) + .set({ + status: BUG_REPORT_STATUS.SYNCED, + syncedAt: new Date() + }) + .where(inArray(bugReports.id, result.data.ids)) + .returning({ id: bugReports.id }); + + return json({ + data: { + updatedCount: updated.length, + updatedIds: updated.map((r) => r.id) + } + }); +}; +``` + +## 4. UI Component + +### Svelte 5 (with shadcn-svelte) + +```svelte + + + + !o && onClose()}> + + + + + Report a Bug + + + +
{ e.preventDefault(); handleSubmit(); }} class="space-y-4"> +
+ +
+
+