Merge 02f2955c09 into 28e6dded4d
This commit is contained in:
shindo107
GitHub
commit
b9da305417
|
|
@ -73,3 +73,6 @@ bmad-custom-src/
|
||||||
website/.astro/
|
website/.astro/
|
||||||
website/dist/
|
website/dist/
|
||||||
build/
|
build/
|
||||||
|
|
||||||
|
# Fork-specific documentation (not committed)
|
||||||
|
BUG-TRACKING.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.
|
||||||
|
|
@ -0,0 +1,123 @@
|
||||||
|
<task id="{bmad_folder}/core/tasks/sync-bug-tracking.xml" name="Sync Bug Tracking">
|
||||||
|
<objective>Sync bugs.yaml and bugs.md when a story is marked done, updating related bugs to "fixed" and features to "implemented"</objective>
|
||||||
|
|
||||||
|
<description>
|
||||||
|
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.
|
||||||
|
</description>
|
||||||
|
|
||||||
|
<inputs>
|
||||||
|
<input name="story_key" required="true">The story key (e.g., "3-7-checkout-from-club-detail-page")</input>
|
||||||
|
<input name="story_id" required="false">The story ID (e.g., "3.7") - used for related_story matching</input>
|
||||||
|
<input name="bugs_yaml" required="true">Path to bugs.yaml file</input>
|
||||||
|
<input name="bugs_md" required="true">Path to bugs.md file</input>
|
||||||
|
<input name="sprint_status" required="true">Path to sprint-status.yaml file</input>
|
||||||
|
<input name="date" required="true">Current date for timestamps</input>
|
||||||
|
</inputs>
|
||||||
|
|
||||||
|
<outputs>
|
||||||
|
<output name="bugs_updated">List of bug IDs marked as fixed</output>
|
||||||
|
<output name="features_updated">List of feature IDs marked as implemented</output>
|
||||||
|
<output name="features_pending">List of feature IDs with incomplete stories</output>
|
||||||
|
</outputs>
|
||||||
|
|
||||||
|
<flow>
|
||||||
|
<step n="1" goal="Load bugs.yaml and check for existence">
|
||||||
|
<action>Load {bugs_yaml} if it exists</action>
|
||||||
|
<check if="bugs.yaml does not exist">
|
||||||
|
<action>Set bugs_updated = [], features_updated = [], features_pending = []</action>
|
||||||
|
<action>Return early - no bug tracking to sync</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="2" goal="Find matching bugs and features using multiple methods">
|
||||||
|
<action>Initialize: bugs_updated = [], features_updated = [], features_pending = []</action>
|
||||||
|
|
||||||
|
<action>Search for entries matching this story using ALL THREE methods:</action>
|
||||||
|
<action>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</action>
|
||||||
|
<action>2. Check related_story field in bugs.yaml matching {story_id} or {story_key}</action>
|
||||||
|
<action>3. Check sprint_stories arrays in feature_requests for entries containing {story_key}</action>
|
||||||
|
|
||||||
|
<critical>PRIORITY: Use sprint-status comment source if present - it's explicit and unambiguous</critical>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="3" goal="Update matching bugs">
|
||||||
|
<check if="matching bugs found in bugs section">
|
||||||
|
<action>For each matching bug:</action>
|
||||||
|
<action>- Update status: "triaged" or "routed" or "in-progress" → "fixed"</action>
|
||||||
|
<action>- Set fixed_date: {date}</action>
|
||||||
|
<action>- Set assigned_to: "dev-agent" (if not already set)</action>
|
||||||
|
<action>- Append to notes: "Auto-closed via sync-bug-tracking. Story {story_key} marked done on {date}."</action>
|
||||||
|
<action>- Add bug ID to bugs_updated list</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="4" goal="Update matching features (with multi-story check)">
|
||||||
|
<check if="matching features found in feature_requests section">
|
||||||
|
<action>For each matching feature (via related_story OR sprint_stories):</action>
|
||||||
|
|
||||||
|
<critical>MULTI-STORY FEATURE CHECK: If feature has sprint_stories array with multiple entries:</critical>
|
||||||
|
<action>1. Extract all story keys from sprint_stories (format: "story-key: status")</action>
|
||||||
|
<action>2. Load sprint-status.yaml and check development_status for EACH story</action>
|
||||||
|
<action>3. Only proceed if ALL stories in sprint_stories have status "done" in sprint-status.yaml</action>
|
||||||
|
<action>4. If any story is NOT done, add feature to features_pending and log: "Feature {feature_id} has incomplete stories: {incomplete_list}"</action>
|
||||||
|
|
||||||
|
<check if="ALL sprint_stories are done (or feature has single story that matches)">
|
||||||
|
<action>- Update status: "backlog" or "triaged" or "routed" or "in-progress" → "implemented"</action>
|
||||||
|
<action>- Set implemented_date: {date}</action>
|
||||||
|
<action>- Update sprint_stories entries to reflect done status</action>
|
||||||
|
<action>- Append to notes: "Auto-closed via sync-bug-tracking. Story {story_key} marked done on {date}."</action>
|
||||||
|
<action>- Add feature ID to features_updated list</action>
|
||||||
|
</check>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="5" goal="Save bugs.yaml updates">
|
||||||
|
<check if="bugs_updated is not empty OR features_updated is not empty">
|
||||||
|
<action>Save updated bugs.yaml, preserving all structure and comments</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="6" goal="Update bugs.md to match">
|
||||||
|
<check if="bugs_updated is not empty OR features_updated is not empty">
|
||||||
|
<action>Load {bugs_md}</action>
|
||||||
|
|
||||||
|
<check if="bugs_updated is not empty">
|
||||||
|
<action>For each bug in bugs_updated:</action>
|
||||||
|
<action>- Find the bug entry in "# Tracked Bugs" section</action>
|
||||||
|
<action>- Move it to "# Fixed Bugs" section</action>
|
||||||
|
<action>- Add [IMPLEMENTED] tag prefix with date: "[IMPLEMENTED] bug-XXX: Title [Fixed: {date}, Verified: pending]"</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="features_updated is not empty">
|
||||||
|
<action>For each feature in features_updated:</action>
|
||||||
|
<action>- Find the feature entry in "# Tracked Feature Requests" section</action>
|
||||||
|
<action>- Move it to "# Implemented Features" section</action>
|
||||||
|
<action>- Add [IMPLEMENTED] tag prefix with date: "[IMPLEMENTED] feature-XXX: Title [Implemented: {date}, Verified: pending]"</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<action>Update statistics section if present</action>
|
||||||
|
<action>Save updated bugs.md</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="7" goal="Return results">
|
||||||
|
<output>
|
||||||
|
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}}
|
||||||
|
</output>
|
||||||
|
</step>
|
||||||
|
</flow>
|
||||||
|
</task>
|
||||||
|
|
@ -214,11 +214,24 @@
|
||||||
<output>ℹ️ Story status updated (no sprint tracking configured)</output>
|
<output>ℹ️ Story status updated (no sprint tracking configured)</output>
|
||||||
</check>
|
</check>
|
||||||
|
|
||||||
|
<!-- Sync bug tracking when story is marked done -->
|
||||||
|
<check if="{{new_status}} == 'done'">
|
||||||
|
<invoke-task path="{project-root}/.bmad/core/tasks/sync-bug-tracking.xml">
|
||||||
|
<param name="story_key">{{story_key}}</param>
|
||||||
|
<param name="story_id">{{story_id}}</param>
|
||||||
|
<param name="bugs_yaml">{output_folder}/bugs.yaml</param>
|
||||||
|
<param name="bugs_md">{output_folder}/bugs.md</param>
|
||||||
|
<param name="sprint_status">{sprint_status}</param>
|
||||||
|
<param name="date">{date}</param>
|
||||||
|
</invoke-task>
|
||||||
|
</check>
|
||||||
|
|
||||||
<output>**✅ Review Complete!**
|
<output>**✅ Review Complete!**
|
||||||
|
|
||||||
**Story Status:** {{new_status}}
|
**Story Status:** {{new_status}}
|
||||||
**Issues Fixed:** {{fixed_count}}
|
**Issues Fixed:** {{fixed_count}}
|
||||||
**Action Items Created:** {{action_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}}
|
{{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}}
|
||||||
</output>
|
</output>
|
||||||
|
|
|
||||||
|
|
@ -1300,7 +1300,67 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!"
|
||||||
|
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
<step n="11" goal="Save Retrospective and Update Sprint Status">
|
<step n="11" goal="Sync Epic-Linked Bugs/Features to Closed Status">
|
||||||
|
<critical>Check bugs.yaml for bugs/features linked to this epic and close them</critical>
|
||||||
|
|
||||||
|
<action>Load {bugs_yaml} if it exists</action>
|
||||||
|
|
||||||
|
<check if="bugs.yaml exists">
|
||||||
|
<action>Search for entries with related_epic matching {{epic_number}}</action>
|
||||||
|
|
||||||
|
<action>For bugs section - find bugs with related_epic == {{epic_number}} AND status in ["fixed", "triaged", "routed"]:</action>
|
||||||
|
<check if="matching bugs found">
|
||||||
|
<action>For each matching bug:</action>
|
||||||
|
<action>- Move entry from "bugs" section to "closed_bugs" section</action>
|
||||||
|
<action>- Update status: → "closed"</action>
|
||||||
|
<action>- Set verified_by: "retrospective-workflow"</action>
|
||||||
|
<action>- Set verified_date: {date}</action>
|
||||||
|
<action>- Append to notes: "Auto-closed via epic retrospective. Epic {{epic_number}} completed on {date}."</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<action>For feature_requests section - find features with related_epic == {{epic_number}} AND status in ["implemented", "backlog", "in-progress"]:</action>
|
||||||
|
<check if="matching features found">
|
||||||
|
<action>For each matching feature:</action>
|
||||||
|
<action>- Move entry from "feature_requests" section to "implemented_features" section</action>
|
||||||
|
<action>- Update status: → "complete"</action>
|
||||||
|
<action>- Set completed_by: "retrospective-workflow"</action>
|
||||||
|
<action>- Set completed_date: {date}</action>
|
||||||
|
<action>- Append to notes: "Auto-closed via epic retrospective. Epic {{epic_number}} completed on {date}."</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<action>Update statistics section with new counts</action>
|
||||||
|
<action>Save updated bugs.yaml</action>
|
||||||
|
|
||||||
|
<check if="bugs/features were moved">
|
||||||
|
<action>Also update bugs.md:</action>
|
||||||
|
<action>- Remove [IMPLEMENTED] tag from closed items</action>
|
||||||
|
<action>- Move bug entries to "# Fixed Bugs" section if not already there</action>
|
||||||
|
<action>- Move feature entries to "# Implemented Features" section if not already there</action>
|
||||||
|
<action>- Add [CLOSED] or [COMPLETE] tag to indicate final status</action>
|
||||||
|
<action>Save updated bugs.md</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
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}}
|
||||||
|
</output>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="bugs.yaml does not exist">
|
||||||
|
<action>Skip bug tracking sync - no bugs.yaml file present</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="12" goal="Save Retrospective and Update Sprint Status">
|
||||||
|
|
||||||
<action>Ensure retrospectives folder exists: {retrospectives_folder}</action>
|
<action>Ensure retrospectives folder exists: {retrospectives_folder}</action>
|
||||||
<action>Create folder if it doesn't exist</action>
|
<action>Create folder if it doesn't exist</action>
|
||||||
|
|
@ -1356,7 +1416,7 @@ Retrospective document was saved successfully, but {sprint_status_file} may need
|
||||||
|
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
<step n="12" goal="Final Summary and Handoff">
|
<step n="13" goal="Final Summary and Handoff">
|
||||||
|
|
||||||
<output>
|
<output>
|
||||||
**✅ Retrospective Complete, {user_name}!**
|
**✅ Retrospective Complete, {user_name}!**
|
||||||
|
|
|
||||||
|
|
@ -54,5 +54,9 @@ sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
|
||||||
story_directory: "{implementation_artifacts}"
|
story_directory: "{implementation_artifacts}"
|
||||||
retrospectives_folder: "{implementation_artifacts}"
|
retrospectives_folder: "{implementation_artifacts}"
|
||||||
|
|
||||||
|
# Bug tracking integration (optional)
|
||||||
|
bugs_yaml: "{planning_artifacts}/bugs.yaml"
|
||||||
|
bugs_md: "{planning_artifacts}/bugs.md"
|
||||||
|
|
||||||
standalone: true
|
standalone: true
|
||||||
web_bundle: false
|
web_bundle: false
|
||||||
|
|
|
||||||
|
|
@ -48,6 +48,26 @@
|
||||||
<note>After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy)</note>
|
<note>After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy)</note>
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
|
<step n="1.5" goal="Load bugs.yaml for bug/feature tracking (optional)">
|
||||||
|
<action>Check if {bugs_yaml} exists in {planning_artifacts}</action>
|
||||||
|
<check if="bugs_yaml exists">
|
||||||
|
<action>Read bugs.yaml using grep to find all bug-NNN and feature-NNN entries</action>
|
||||||
|
<action>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)
|
||||||
|
</action>
|
||||||
|
<action>Build bug/feature inventory for inclusion in sprint status</action>
|
||||||
|
<action>Track feature-to-story mappings (feature-001 → stories 7-1, 7-2, etc.)</action>
|
||||||
|
</check>
|
||||||
|
<check if="bugs_yaml does not exist">
|
||||||
|
<output>Note: No bugs.yaml found - bug tracking not enabled for this project.</output>
|
||||||
|
<action>Continue without bug integration</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
<step n="2" goal="Build sprint status structure">
|
<step n="2" goal="Build sprint status structure">
|
||||||
<action>For each epic found, create entries in this order:</action>
|
<action>For each epic found, create entries in this order:</action>
|
||||||
|
|
||||||
|
|
@ -65,6 +85,17 @@ development_status:
|
||||||
epic-1-retrospective: optional
|
epic-1-retrospective: optional
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<action>If bugs.yaml was loaded, add bug/feature sources header comment:</action>
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
<step n="3" goal="Apply intelligent status detection">
|
<step n="3" goal="Apply intelligent status detection">
|
||||||
|
|
|
||||||
|
|
@ -33,6 +33,10 @@ variables:
|
||||||
epics_location: "{planning_artifacts}" # Directory containing epic*.md files
|
epics_location: "{planning_artifacts}" # Directory containing epic*.md files
|
||||||
epics_pattern: "epic*.md" # Pattern to find epic 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
|
# Output configuration
|
||||||
status_file: "{implementation_artifacts}/sprint-status.yaml"
|
status_file: "{implementation_artifacts}/sprint-status.yaml"
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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"
|
- IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories"
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
|
<step n="2.5" goal="Load bug/feature tracking status (optional)">
|
||||||
|
<action>Check if {bugs_yaml} exists</action>
|
||||||
|
<check if="bugs_yaml exists">
|
||||||
|
<action>Grep for bug-NNN and feature-NNN entries with status field</action>
|
||||||
|
<action>Count items by status: triaged, fixed/implemented (pending verify), verified, closed</action>
|
||||||
|
<action>Identify items needing action:
|
||||||
|
- Items with [IMPLEMENTED] tag → need verification
|
||||||
|
- Items with status "triaged" + workflow "direct-fix" → ready for implementation
|
||||||
|
</action>
|
||||||
|
<action>Store: bugs_pending_verify, bugs_triaged, features_pending_verify, features_triaged</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
<step n="3" goal="Select next action recommendation">
|
<step n="3" goal="Select next action recommendation">
|
||||||
<action>Pick the next recommended workflow using priority:</action>
|
<action>Pick the next recommended workflow using priority:</action>
|
||||||
<note>When selecting "first" story: sort by epic number, then story number (e.g., 1-1 before 1-2 before 2-1)</note>
|
<note>When selecting "first" story: sort by epic number, then story number (e.g., 1-1 before 1-2 before 2-1)</note>
|
||||||
1. If any story status == in-progress → recommend `dev-story` for the first in-progress story
|
<note>Bug verification takes priority over new story work to close the feedback loop</note>
|
||||||
2. Else if any story status == review → recommend `code-review` for the first review story
|
1. If any bug/feature has [IMPLEMENTED] tag (pending verify) → recommend `verify` for first pending item
|
||||||
3. Else if any story status == ready-for-dev → recommend `dev-story`
|
2. If any story status == in-progress → recommend `dev-story` for the first in-progress story
|
||||||
4. Else if any story status == backlog → recommend `create-story`
|
3. Else if any story status == review → recommend `code-review` for the first review story
|
||||||
5. Else if any retrospective status == optional → recommend `retrospective`
|
4. Else if any story status == ready-for-dev → recommend `dev-story`
|
||||||
6. Else → All implementation items done; suggest `workflow-status` to plan next phase
|
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
|
||||||
<action>Store selected recommendation as: next_story_id, next_workflow_id, next_agent (SM/DEV as appropriate)</action>
|
<action>Store selected recommendation as: next_story_id, next_workflow_id, next_agent (SM/DEV as appropriate)</action>
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
|
|
@ -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}}
|
**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}})
|
**Next Recommendation:** /bmad:bmm:workflows:{{next_workflow_id}} ({{next_story_id}})
|
||||||
|
|
||||||
{{#if risks}}
|
{{#if risks}}
|
||||||
|
|
|
||||||
|
|
@ -21,6 +21,9 @@ instructions: "{installed_path}/instructions.md"
|
||||||
variables:
|
variables:
|
||||||
sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
|
sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
|
||||||
tracking_system: "file-system"
|
tracking_system: "file-system"
|
||||||
|
# Bug tracking integration (optional)
|
||||||
|
bugs_yaml: "{planning_artifacts}/bugs.yaml"
|
||||||
|
bugs_md: "{planning_artifacts}/bugs.md"
|
||||||
|
|
||||||
# Smart input file references
|
# Smart input file references
|
||||||
input_file_patterns:
|
input_file_patterns:
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,124 @@
|
||||||
|
# Story Approved Workflow Instructions (DEV Agent)
|
||||||
|
|
||||||
|
<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
|
||||||
|
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||||
|
<critical>Communicate all responses in {communication_language}</critical>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
|
||||||
|
<critical>This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete)</critical>
|
||||||
|
<critical>Workflow: Update story file status to Done</critical>
|
||||||
|
|
||||||
|
<step n="1" goal="Find reviewed story to mark done" tag="sprint-status">
|
||||||
|
|
||||||
|
<check if="{story_path} is provided">
|
||||||
|
<action>Use {story_path} directly</action>
|
||||||
|
<action>Read COMPLETE story file and parse sections</action>
|
||||||
|
<action>Extract story_key from filename or story metadata</action>
|
||||||
|
<action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to mark as done"</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="{story_path} is NOT provided">
|
||||||
|
<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
|
||||||
|
<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
|
||||||
|
<action>Read ALL lines from beginning to end - do not skip any content</action>
|
||||||
|
<action>Parse the development_status section completely</action>
|
||||||
|
|
||||||
|
<action>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"
|
||||||
|
</action>
|
||||||
|
|
||||||
|
<check if="no story with status 'review' found">
|
||||||
|
<output>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
|
||||||
|
</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<action>Use the first reviewed story found</action>
|
||||||
|
<action>Find matching story file in {story_dir} using story_key pattern</action>
|
||||||
|
<action>Read the COMPLETE story file</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<action>Extract story_id and story_title from the story file</action>
|
||||||
|
|
||||||
|
<action>Find the "Status:" line (usually at the top)</action>
|
||||||
|
<action>Update story file: Change Status to "done"</action>
|
||||||
|
|
||||||
|
<action>Add completion notes to Dev Agent Record section:</action>
|
||||||
|
<action>Find "## Dev Agent Record" section and add:
|
||||||
|
|
||||||
|
```
|
||||||
|
### Completion Notes
|
||||||
|
**Completed:** {date}
|
||||||
|
**Definition of Done:** All acceptance criteria met, code reviewed, tests passing
|
||||||
|
```
|
||||||
|
|
||||||
|
</action>
|
||||||
|
|
||||||
|
<action>Save the story file</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="2" goal="Update sprint status to done" tag="sprint-status">
|
||||||
|
<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
|
||||||
|
<action>Find development_status key matching {story_key}</action>
|
||||||
|
<action>Verify current status is "review" (expected previous state)</action>
|
||||||
|
<action>Update development_status[{story_key}] = "done"</action>
|
||||||
|
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||||
|
|
||||||
|
<check if="story key not found in file">
|
||||||
|
<output>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.
|
||||||
|
</output>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="3" goal="Sync related bugs/features in bug tracking">
|
||||||
|
<critical>Invoke shared task to sync bugs.yaml and bugs.md for this completed story</critical>
|
||||||
|
|
||||||
|
<invoke-task path="{project-root}/.bmad/core/tasks/sync-bug-tracking.xml">
|
||||||
|
<param name="story_key">{story_key}</param>
|
||||||
|
<param name="story_id">{story_id}</param>
|
||||||
|
<param name="bugs_yaml">{bugs_yaml}</param>
|
||||||
|
<param name="bugs_md">{bugs_md}</param>
|
||||||
|
<param name="sprint_status">{sprint_status}</param>
|
||||||
|
<param name="date">{date}</param>
|
||||||
|
</invoke-task>
|
||||||
|
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="4" goal="Confirm completion to user">
|
||||||
|
|
||||||
|
<output>**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
|
||||||
|
</output>
|
||||||
|
|
||||||
|
</step>
|
||||||
|
|
||||||
|
</workflow>
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
<!-- src/lib/components/BugReportModal.svelte -->
|
||||||
|
<script lang="ts">
|
||||||
|
import * as Dialog from '$lib/components/ui/dialog';
|
||||||
|
import { Button } from '$lib/components/ui/button';
|
||||||
|
import { Input } from '$lib/components/ui/input';
|
||||||
|
import { Textarea } from '$lib/components/ui/textarea';
|
||||||
|
import { toast } from 'svelte-sonner';
|
||||||
|
import { Bug } from 'lucide-svelte';
|
||||||
|
import { browser } from '$app/environment';
|
||||||
|
|
||||||
|
interface Props {
|
||||||
|
open: boolean;
|
||||||
|
onClose: () => void;
|
||||||
|
}
|
||||||
|
|
||||||
|
let { open = $bindable(), onClose }: Props = $props();
|
||||||
|
|
||||||
|
let title = $state('');
|
||||||
|
let description = $state('');
|
||||||
|
let loading = $state(false);
|
||||||
|
|
||||||
|
// Auto-detect environment
|
||||||
|
let platform = $derived(browser ? detectPlatform() : '');
|
||||||
|
let browserName = $derived(browser ? detectBrowser() : '');
|
||||||
|
let currentUrl = $derived(browser ? window.location.href : '');
|
||||||
|
|
||||||
|
function detectPlatform(): string {
|
||||||
|
const ua = navigator.userAgent.toLowerCase();
|
||||||
|
if (ua.includes('iphone') || ua.includes('ipad')) return 'iOS';
|
||||||
|
if (ua.includes('android')) return 'Android';
|
||||||
|
if (ua.includes('mac')) return 'macOS';
|
||||||
|
if (ua.includes('win')) return 'Windows';
|
||||||
|
return 'Unknown';
|
||||||
|
}
|
||||||
|
|
||||||
|
function detectBrowser(): string {
|
||||||
|
const ua = navigator.userAgent;
|
||||||
|
if (ua.includes('Chrome') && !ua.includes('Edg')) return 'Chrome';
|
||||||
|
if (ua.includes('Safari') && !ua.includes('Chrome')) return 'Safari';
|
||||||
|
if (ua.includes('Firefox')) return 'Firefox';
|
||||||
|
if (ua.includes('Edg')) return 'Edge';
|
||||||
|
return 'Unknown';
|
||||||
|
}
|
||||||
|
|
||||||
|
async function handleSubmit() {
|
||||||
|
loading = true;
|
||||||
|
try {
|
||||||
|
const response = await fetch('/api/bug-reports', {
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: JSON.stringify({
|
||||||
|
title,
|
||||||
|
description,
|
||||||
|
pageUrl: currentUrl,
|
||||||
|
userAgent: navigator.userAgent,
|
||||||
|
platform,
|
||||||
|
browser: browserName
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
if (!response.ok) {
|
||||||
|
const data = await response.json();
|
||||||
|
toast.error(data.error?.message || 'Failed to submit');
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
toast.success('Bug report submitted');
|
||||||
|
onClose();
|
||||||
|
} finally {
|
||||||
|
loading = false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<Dialog.Root bind:open onOpenChange={(o) => !o && onClose()}>
|
||||||
|
<Dialog.Content class="sm:max-w-[500px]">
|
||||||
|
<Dialog.Header>
|
||||||
|
<Dialog.Title class="flex items-center gap-2">
|
||||||
|
<Bug class="h-5 w-5" />
|
||||||
|
Report a Bug
|
||||||
|
</Dialog.Title>
|
||||||
|
</Dialog.Header>
|
||||||
|
|
||||||
|
<form onsubmit={(e) => { e.preventDefault(); handleSubmit(); }} class="space-y-4">
|
||||||
|
<div>
|
||||||
|
<Input bind:value={title} placeholder="Brief summary" maxlength={200} />
|
||||||
|
</div>
|
||||||
|
<div>
|
||||||
|
<Textarea bind:value={description} placeholder="What happened?" rows={4} />
|
||||||
|
</div>
|
||||||
|
<div class="rounded-md bg-muted p-3 text-sm text-muted-foreground">
|
||||||
|
{platform} / {browserName}
|
||||||
|
</div>
|
||||||
|
<Dialog.Footer>
|
||||||
|
<Button variant="outline" onclick={onClose} disabled={loading}>Cancel</Button>
|
||||||
|
<Button type="submit" disabled={loading}>Submit</Button>
|
||||||
|
</Dialog.Footer>
|
||||||
|
</form>
|
||||||
|
</Dialog.Content>
|
||||||
|
</Dialog.Root>
|
||||||
|
```
|
||||||
|
|
||||||
|
### React (with shadcn/ui)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// src/components/BugReportModal.tsx
|
||||||
|
|
||||||
|
import { useState } from 'react';
|
||||||
|
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter } from '@/components/ui/dialog';
|
||||||
|
import { Button } from '@/components/ui/button';
|
||||||
|
import { Input } from '@/components/ui/input';
|
||||||
|
import { Textarea } from '@/components/ui/textarea';
|
||||||
|
import { Bug } from 'lucide-react';
|
||||||
|
import { toast } from 'sonner';
|
||||||
|
|
||||||
|
interface Props {
|
||||||
|
open: boolean;
|
||||||
|
onClose: () => void;
|
||||||
|
}
|
||||||
|
|
||||||
|
export function BugReportModal({ open, onClose }: Props) {
|
||||||
|
const [title, setTitle] = useState('');
|
||||||
|
const [description, setDescription] = useState('');
|
||||||
|
const [loading, setLoading] = useState(false);
|
||||||
|
|
||||||
|
const detectPlatform = () => {
|
||||||
|
const ua = navigator.userAgent.toLowerCase();
|
||||||
|
if (ua.includes('iphone') || ua.includes('ipad')) return 'iOS';
|
||||||
|
if (ua.includes('android')) return 'Android';
|
||||||
|
if (ua.includes('mac')) return 'macOS';
|
||||||
|
if (ua.includes('win')) return 'Windows';
|
||||||
|
return 'Unknown';
|
||||||
|
};
|
||||||
|
|
||||||
|
const handleSubmit = async (e: React.FormEvent) => {
|
||||||
|
e.preventDefault();
|
||||||
|
setLoading(true);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await fetch('/api/bug-reports', {
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: JSON.stringify({
|
||||||
|
title,
|
||||||
|
description,
|
||||||
|
pageUrl: window.location.href,
|
||||||
|
userAgent: navigator.userAgent,
|
||||||
|
platform: detectPlatform()
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
if (!response.ok) throw new Error('Failed to submit');
|
||||||
|
toast.success('Bug report submitted');
|
||||||
|
onClose();
|
||||||
|
} catch {
|
||||||
|
toast.error('Failed to submit bug report');
|
||||||
|
} finally {
|
||||||
|
setLoading(false);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Dialog open={open} onOpenChange={(o) => !o && onClose()}>
|
||||||
|
<DialogContent>
|
||||||
|
<DialogHeader>
|
||||||
|
<DialogTitle className="flex items-center gap-2">
|
||||||
|
<Bug className="h-5 w-5" />
|
||||||
|
Report a Bug
|
||||||
|
</DialogTitle>
|
||||||
|
</DialogHeader>
|
||||||
|
<form onSubmit={handleSubmit} className="space-y-4">
|
||||||
|
<Input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Brief summary" />
|
||||||
|
<Textarea value={description} onChange={(e) => setDescription(e.target.value)} placeholder="What happened?" />
|
||||||
|
<DialogFooter>
|
||||||
|
<Button variant="outline" onClick={onClose} disabled={loading}>Cancel</Button>
|
||||||
|
<Button type="submit" disabled={loading}>Submit</Button>
|
||||||
|
</DialogFooter>
|
||||||
|
</form>
|
||||||
|
</DialogContent>
|
||||||
|
</Dialog>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. Workflow Configuration
|
||||||
|
|
||||||
|
Update your project's `.bmad/bmm/config.yaml` to set the `project_url`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# .bmad/bmm/config.yaml
|
||||||
|
|
||||||
|
project_url: "http://localhost:5173" # Dev
|
||||||
|
# project_url: "https://your-app.com" # Prod
|
||||||
|
```
|
||||||
|
|
||||||
|
The triage workflow will use this to call your API endpoints.
|
||||||
|
|
||||||
|
## 6. API Response Format
|
||||||
|
|
||||||
|
The workflow expects these response formats:
|
||||||
|
|
||||||
|
### GET /api/bug-reports/pending
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"reports": [
|
||||||
|
{
|
||||||
|
"id": "uuid",
|
||||||
|
"title": "Bug title",
|
||||||
|
"description": "Bug description",
|
||||||
|
"reporterType": "staff",
|
||||||
|
"reporterName": "John Doe",
|
||||||
|
"platform": "macOS",
|
||||||
|
"browser": "Chrome",
|
||||||
|
"pageUrl": "https://...",
|
||||||
|
"screenshotUrl": "https://...",
|
||||||
|
"createdAt": "2025-01-01T00:00:00Z"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"count": 1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### POST /api/bug-reports/mark-synced
|
||||||
|
|
||||||
|
Request:
|
||||||
|
```json
|
||||||
|
{ "ids": ["uuid1", "uuid2"] }
|
||||||
|
```
|
||||||
|
|
||||||
|
Response:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": {
|
||||||
|
"updatedCount": 2,
|
||||||
|
"updatedIds": ["uuid1", "uuid2"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 7. Optional: Screenshot Storage
|
||||||
|
|
||||||
|
For screenshot uploads, you'll need cloud storage (R2, S3, etc.):
|
||||||
|
|
||||||
|
1. Create an upload endpoint: `POST /api/bug-reports/[id]/upload-screenshot`
|
||||||
|
2. Upload to cloud storage
|
||||||
|
3. Update `screenshotUrl` on the bug report record
|
||||||
|
|
||||||
|
## 8. Security Considerations
|
||||||
|
|
||||||
|
- **Authentication**: Create endpoint should require auth
|
||||||
|
- **API Key**: Consider adding API key auth for pending/mark-synced endpoints in production
|
||||||
|
- **Rate Limiting**: Add rate limits to prevent spam
|
||||||
|
- **Input Sanitization**: Validate all user input (handled by Zod schemas)
|
||||||
|
|
||||||
|
## Without In-App Reporting
|
||||||
|
|
||||||
|
If you don't implement in-app reporting, the workflow still works:
|
||||||
|
|
||||||
|
1. Users manually add bugs to `docs/bugs.md` under `# manual input`
|
||||||
|
2. Run `/triage` to process them
|
||||||
|
3. Workflow skips Step 0 (API sync) when no API is available
|
||||||
|
|
||||||
|
The workflows are designed to be flexible and work with or without the in-app feature.
|
||||||
|
|
@ -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!
|
||||||
|
|
@ -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!
|
||||||
|
|
@ -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!
|
||||||
|
|
@ -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!
|
||||||
|
|
@ -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!
|
||||||
|
|
@ -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!
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -0,0 +1,523 @@
|
||||||
|
# Implement Workflow (Bug Fix or Feature)
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<critical>This workflow loads bug/feature context, implements the code, and updates tracking in both bugs.yaml and bugs.md</critical>
|
||||||
|
<critical>Communicate in {communication_language} with {user_name}</critical>
|
||||||
|
<critical>Auto-detects type from ID format: bug-NNN = bug fix, feature-NNN = feature implementation</critical>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
|
||||||
|
<step n="1" goal="Get item ID from user">
|
||||||
|
<check if="item_id not provided in user input">
|
||||||
|
<ask>Which bug or feature should I implement? (e.g., bug-026 or feature-021)</ask>
|
||||||
|
</check>
|
||||||
|
<action>Extract item ID from user input</action>
|
||||||
|
<action>Detect type from ID format:</action>
|
||||||
|
<action>- "bug-NNN" -> type = "bug", action_verb = "fix", past_verb = "Fixed"</action>
|
||||||
|
<action>- "feature-NNN" -> type = "feature", action_verb = "implement", past_verb = "Implemented"</action>
|
||||||
|
<check if="ID doesn't match either format">
|
||||||
|
<output>Invalid ID format. Use bug-NNN (e.g., bug-026) or feature-NNN (e.g., feature-021)</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="2" goal="Load context from bugs.yaml">
|
||||||
|
<action>Search for {item_id} in {bugs_yaml} using grep with 50+ lines of context after the match (do NOT read entire file - it exceeds token limits)</action>
|
||||||
|
<check if="type == bug">
|
||||||
|
<action>Entry will be in bugs section, grep will capture all fields</action>
|
||||||
|
</check>
|
||||||
|
<check if="type == feature">
|
||||||
|
<action>Entry will be in feature_requests section, grep will capture all fields</action>
|
||||||
|
</check>
|
||||||
|
<check if="item not found in bugs.yaml">
|
||||||
|
<output>{item_id} not found in bugs.yaml. Please verify the ID or run bug-tracking workflow first.</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
<action>Extract and store metadata:</action>
|
||||||
|
<action>- title: Title/summary</action>
|
||||||
|
<action>- description: Full description</action>
|
||||||
|
<action>- severity/priority: Importance level</action>
|
||||||
|
<action>- complexity: trivial | small | medium | complex</action>
|
||||||
|
<action>- effort_estimate: Estimated hours</action>
|
||||||
|
<action>- affected_platform: all | ios | android (bugs only)</action>
|
||||||
|
<action>- related_story/related_epic: Related items if applicable</action>
|
||||||
|
<action>- doc_impact: Documentation impact flags (prd, architecture, ux) and notes</action>
|
||||||
|
<action>- notes: Triage notes including planned approach, files to check, implementation strategy</action>
|
||||||
|
|
||||||
|
<check if="recommended_workflow == 'backlog'">
|
||||||
|
<output>**BACKLOG ITEM - NOT READY FOR IMPLEMENTATION**
|
||||||
|
|
||||||
|
**{item_id}: {title}**
|
||||||
|
|
||||||
|
This item has `recommended_workflow: backlog` which means it's deferred and not scheduled for implementation.
|
||||||
|
|
||||||
|
**To implement this item, first promote it to the sprint:**
|
||||||
|
1. Run `*sprint-planning` and select this item for promotion
|
||||||
|
2. Or manually update bugs.yaml: change `recommended_workflow` to `direct-fix`, `tech-spec`, or `correct-course`
|
||||||
|
|
||||||
|
**Current Status:** {status}
|
||||||
|
**Priority:** {priority}
|
||||||
|
**Complexity:** {complexity}
|
||||||
|
</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="status == 'deferred'">
|
||||||
|
<output>**DEFERRED ITEM - NOT READY FOR IMPLEMENTATION**
|
||||||
|
|
||||||
|
**{item_id}: {title}**
|
||||||
|
|
||||||
|
This item is deferred (marked for future release, not current MVP).
|
||||||
|
|
||||||
|
**To implement this item:**
|
||||||
|
1. Update bugs.yaml: change `status` from `deferred` to `backlog`
|
||||||
|
2. Run `*sprint-planning` to promote to current sprint
|
||||||
|
|
||||||
|
**Notes:** {notes}
|
||||||
|
</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="status == 'blocked'">
|
||||||
|
<output>**BLOCKED ITEM - CANNOT IMPLEMENT**
|
||||||
|
|
||||||
|
**{item_id}: {title}**
|
||||||
|
|
||||||
|
This item is blocked and requires clarification before implementation.
|
||||||
|
|
||||||
|
**Blocking reason:** {notes}
|
||||||
|
|
||||||
|
**To unblock:**
|
||||||
|
1. Resolve the blocking issue
|
||||||
|
2. Update bugs.yaml: change `status` from `blocked` to `backlog`
|
||||||
|
3. Run `/triage {item_id}` to re-evaluate
|
||||||
|
</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="2.5" goal="Check for documentation impact and route to appropriate agents">
|
||||||
|
<action>Check doc_impact fields from bugs.yaml entry</action>
|
||||||
|
<check if="doc_impact.prd OR doc_impact.architecture OR doc_impact.ux is TRUE">
|
||||||
|
<output>**DOCUMENTATION IMPACT DETECTED**
|
||||||
|
|
||||||
|
**{item_id}: {title}**
|
||||||
|
|
||||||
|
This {type} requires documentation updates BEFORE implementation:
|
||||||
|
|
||||||
|
{if doc_impact.prd:}
|
||||||
|
- **PRD Impact:** Updates needed to product requirements
|
||||||
|
-> Route to PM Agent for PRD updates
|
||||||
|
{end if}
|
||||||
|
|
||||||
|
{if doc_impact.architecture:}
|
||||||
|
- **Architecture Impact:** Updates needed to architecture docs
|
||||||
|
-> Route to Architect Agent for architecture updates
|
||||||
|
{end if}
|
||||||
|
|
||||||
|
{if doc_impact.ux:}
|
||||||
|
- **UX Impact:** Updates needed to UX specifications
|
||||||
|
-> Route to UX Designer Agent for UX spec updates
|
||||||
|
{end if}
|
||||||
|
|
||||||
|
**Details:** {doc_impact.notes}
|
||||||
|
|
||||||
|
**Options:**
|
||||||
|
1. **update-docs-first** - Route to agents for documentation updates before implementation (recommended)
|
||||||
|
2. **proceed-anyway** - Skip documentation updates and implement directly (not recommended)
|
||||||
|
3. **cancel** - Return to review</output>
|
||||||
|
<ask>How should we proceed?</ask>
|
||||||
|
|
||||||
|
<check if="user chooses update-docs-first">
|
||||||
|
<output>Routing to documentation update workflow...
|
||||||
|
|
||||||
|
**Documentation Update Sequence:**</output>
|
||||||
|
|
||||||
|
<check if="doc_impact.prd">
|
||||||
|
<output>1. **PRD Update** - Invoking PM Agent...</output>
|
||||||
|
<action>Prepare PRD update context:</action>
|
||||||
|
<action>- Source item: {item_id}</action>
|
||||||
|
<action>- Change description: {description}</action>
|
||||||
|
<action>- Specific PRD sections: {doc_impact.notes PRD sections}</action>
|
||||||
|
<invoke-agent agent="pm">
|
||||||
|
<task>Review and update PRD for {item_id}: {title}
|
||||||
|
|
||||||
|
Change context: {description}
|
||||||
|
|
||||||
|
Documentation notes: {doc_impact.notes}
|
||||||
|
|
||||||
|
Please update the relevant PRD sections to reflect this change.
|
||||||
|
|
||||||
|
After updates:
|
||||||
|
1. Summarize what was changed
|
||||||
|
2. Return to the implement workflow by running: /implement {item_id}
|
||||||
|
|
||||||
|
IMPORTANT: You MUST return to /implement {item_id} after completing the PRD updates so the actual code implementation can proceed.</task>
|
||||||
|
</invoke-agent>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="doc_impact.architecture">
|
||||||
|
<output>2. **Architecture Update** - Invoking Architect Agent...</output>
|
||||||
|
<action>Prepare architecture update context:</action>
|
||||||
|
<action>- Source item: {item_id}</action>
|
||||||
|
<action>- Change description: {description}</action>
|
||||||
|
<action>- Specific architecture sections: {doc_impact.notes architecture sections}</action>
|
||||||
|
<invoke-agent agent="architect">
|
||||||
|
<task>Review and update Architecture documentation for {item_id}: {title}
|
||||||
|
|
||||||
|
Change context: {description}
|
||||||
|
|
||||||
|
Documentation notes: {doc_impact.notes}
|
||||||
|
|
||||||
|
Please update the relevant architecture sections (data model, APIs, security, etc.) to reflect this change.
|
||||||
|
|
||||||
|
After updates:
|
||||||
|
1. Summarize what was changed
|
||||||
|
2. Return to the implement workflow by running: /implement {item_id}
|
||||||
|
|
||||||
|
IMPORTANT: You MUST return to /implement {item_id} after completing the architecture updates so the actual code implementation can proceed.</task>
|
||||||
|
</invoke-agent>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="doc_impact.ux">
|
||||||
|
<output>3. **UX Spec Update** - Invoking UX Designer Agent...</output>
|
||||||
|
<action>Prepare UX update context:</action>
|
||||||
|
<action>- Source item: {item_id}</action>
|
||||||
|
<action>- Change description: {description}</action>
|
||||||
|
<action>- Specific UX sections: {doc_impact.notes UX sections}</action>
|
||||||
|
<invoke-agent agent="ux-designer">
|
||||||
|
<task>Review and update UX specification for {item_id}: {title}
|
||||||
|
|
||||||
|
Change context: {description}
|
||||||
|
|
||||||
|
Documentation notes: {doc_impact.notes}
|
||||||
|
|
||||||
|
Please update the relevant UX spec sections (screens, flows, components, etc.) to reflect this change.
|
||||||
|
|
||||||
|
After updates:
|
||||||
|
1. Summarize what was changed
|
||||||
|
2. Return to the implement workflow by running: /implement {item_id}
|
||||||
|
|
||||||
|
IMPORTANT: You MUST return to /implement {item_id} after completing the UX updates so the actual code implementation can proceed.</task>
|
||||||
|
</invoke-agent>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<output>**Documentation updates complete.**
|
||||||
|
|
||||||
|
Proceeding with implementation...</output>
|
||||||
|
<action>Continue to step 3</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="user chooses cancel">
|
||||||
|
<output>Cancelled. {item_id} remains in current state.</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<action if="user chooses proceed-anyway">
|
||||||
|
<output>Proceeding without documentation updates. Remember to update docs after implementation.</output>
|
||||||
|
<action>Continue to step 3</action>
|
||||||
|
</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="3" goal="Evaluate routing and auto-route to correct-course if needed">
|
||||||
|
<action>Check recommended_workflow field from bugs.yaml</action>
|
||||||
|
|
||||||
|
<check if="recommended_workflow == 'correct-course'">
|
||||||
|
<output>**AUTO-ROUTING TO CORRECT-COURSE**
|
||||||
|
|
||||||
|
**{item_id}: {title}**
|
||||||
|
**Priority:** {severity_or_priority} | **Complexity:** {complexity}
|
||||||
|
|
||||||
|
This {type} has `recommended_workflow: correct-course` which requires impact analysis and story creation before implementation.
|
||||||
|
|
||||||
|
Invoking correct-course workflow via SM agent...</output>
|
||||||
|
|
||||||
|
<action>Invoke the correct-course workflow skill with item context</action>
|
||||||
|
<invoke-skill skill="bmad:bmm:workflows:correct-course">
|
||||||
|
<args>{item_id}: {title} - {description}
|
||||||
|
|
||||||
|
Priority: {severity_or_priority}
|
||||||
|
Complexity: {complexity}
|
||||||
|
Doc Impact: {doc_impact summary}
|
||||||
|
Notes: {notes}</args>
|
||||||
|
</invoke-skill>
|
||||||
|
<action>HALT - Correct Course workflow will handle story/epic creation</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="recommended_workflow == 'tech-spec'">
|
||||||
|
<output>**AUTO-ROUTING TO TECH-SPEC**
|
||||||
|
|
||||||
|
**{item_id}: {title}**
|
||||||
|
|
||||||
|
This {type} has `recommended_workflow: tech-spec`. Invoking tech-spec workflow...</output>
|
||||||
|
|
||||||
|
<invoke-skill skill="bmad:bmm:workflows:tech-spec">
|
||||||
|
<args>{item_id}: {title} - {description}</args>
|
||||||
|
</invoke-skill>
|
||||||
|
<action>HALT - Tech-spec workflow will create implementation spec</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="recommended_workflow == 'direct-fix'">
|
||||||
|
<output>**DIRECT IMPLEMENTATION**
|
||||||
|
|
||||||
|
This {type} is routed for direct implementation. Proceeding...</output>
|
||||||
|
<action>Continue to step 4</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="recommended_workflow is not set OR recommended_workflow is ambiguous">
|
||||||
|
<action>Evaluate the workflow routing matrix based on severity and complexity:</action>
|
||||||
|
<action>**Routing Matrix:**</action>
|
||||||
|
<action>- critical + any -> correct-course</action>
|
||||||
|
<action>- high/medium + medium/complex -> correct-course</action>
|
||||||
|
<action>- high + trivial -> direct-fix</action>
|
||||||
|
<action>- high/medium + small -> tech-spec</action>
|
||||||
|
<action>- medium + trivial -> direct-fix</action>
|
||||||
|
<action>- low + trivial -> direct-fix</action>
|
||||||
|
<action>- low + small+ -> backlog</action>
|
||||||
|
|
||||||
|
<action>Apply matrix to determine routing and continue accordingly</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="4" goal="Present context and confirm approach">
|
||||||
|
<output>**{item_id}: {title}**
|
||||||
|
|
||||||
|
**Type:** {type} | **Severity/Priority:** {severity_or_priority} | **Complexity:** {complexity} | **Effort:** ~{effort_estimate}h
|
||||||
|
|
||||||
|
**Description:**
|
||||||
|
{description}
|
||||||
|
|
||||||
|
**Planned Approach (from triage notes):**
|
||||||
|
{notes}
|
||||||
|
|
||||||
|
**Related:** {related_story} / {related_epic}
|
||||||
|
</output>
|
||||||
|
<ask>Ready to {action_verb} this {type}? (yes/no/clarify)</ask>
|
||||||
|
<check if="user says clarify">
|
||||||
|
<ask>What additional context do you need?</ask>
|
||||||
|
<action>Gather clarification, update mental model</action>
|
||||||
|
</check>
|
||||||
|
<check if="user says no">
|
||||||
|
<output>Cancelled. {item_id} remains in current state.</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="5" goal="Implement the fix/feature">
|
||||||
|
<action>Based on the notes/planned approach, identify files to modify or create</action>
|
||||||
|
<action>Read each affected file to understand current implementation</action>
|
||||||
|
<action>Implement following the planned approach:</action>
|
||||||
|
<action>- Make minimal, targeted changes</action>
|
||||||
|
<action>- Follow existing code patterns and style</action>
|
||||||
|
<action>- Add comments only where logic is non-obvious</action>
|
||||||
|
<action>- Do not over-engineer or add unrelated improvements</action>
|
||||||
|
<action>- Do not add extra features or "nice to haves"</action>
|
||||||
|
|
||||||
|
<action>For each file modified/created, track:</action>
|
||||||
|
<action>- File path</action>
|
||||||
|
<action>- What was changed/added</action>
|
||||||
|
<action>- How it addresses the bug/feature</action>
|
||||||
|
|
||||||
|
<check if="requires new files">
|
||||||
|
<action>Create new files following project conventions</action>
|
||||||
|
<action>Add appropriate imports/exports</action>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<check if="planned approach is unclear or insufficient">
|
||||||
|
<ask>The triage notes don't provide a clear approach.
|
||||||
|
|
||||||
|
Based on my analysis, I suggest: {proposed_approach}
|
||||||
|
|
||||||
|
Should I proceed with this approach?</ask>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="6" goal="Verify implementation compiles">
|
||||||
|
<action>Run TypeScript compilation check: npm run check</action>
|
||||||
|
<check if="compilation errors in modified files">
|
||||||
|
<action>Fix compilation errors</action>
|
||||||
|
<action>Re-run compilation check</action>
|
||||||
|
</check>
|
||||||
|
<output>Compilation check passed.</output>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="6.5" goal="Pre-update sync check">
|
||||||
|
<action>Search for {item_id} in both bugs.yaml and bugs.md using grep to check current status</action>
|
||||||
|
<check if="status differs between files OR item missing from one file">
|
||||||
|
<output>SYNC WARNING: {item_id} status mismatch detected
|
||||||
|
- bugs.yaml: {yaml_status}
|
||||||
|
- bugs.md: {md_status}
|
||||||
|
Proceeding will update both files to "{new_status}".</output>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="7" goal="Update bugs.yaml">
|
||||||
|
<action>Update entry in bugs.yaml:</action>
|
||||||
|
<check if="type == bug">
|
||||||
|
<action>- status: "fixed"</action>
|
||||||
|
<action>- fixed_date: {date} (YYYY-MM-DD format)</action>
|
||||||
|
</check>
|
||||||
|
<check if="type == feature">
|
||||||
|
<action>- status: "implemented"</action>
|
||||||
|
<action>- implemented_date: {date} (YYYY-MM-DD format)</action>
|
||||||
|
</check>
|
||||||
|
<action>- assigned_to: "dev-agent"</action>
|
||||||
|
<action>- files_modified: {list of files changed/created during implementation}</action>
|
||||||
|
<action>- Append to notes: "{past_verb} ({date}): {summary of changes made}"</action>
|
||||||
|
<action>Write updated bugs.yaml</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="8" goal="Update bugs.md">
|
||||||
|
<action>Search for {item_id} in {bugs_md} using grep with surrounding context to locate the entry</action>
|
||||||
|
|
||||||
|
<action>**8a. Remove from tracked section (if present)**</action>
|
||||||
|
<check if="type == bug">
|
||||||
|
<action>Search for "{item_id}:" in "# Tracked Bugs" section</action>
|
||||||
|
</check>
|
||||||
|
<check if="type == feature">
|
||||||
|
<action>Search for "{item_id}:" in "# Tracked Feature Requests" section</action>
|
||||||
|
</check>
|
||||||
|
<action>If found, remove the entire entry (including any indented sub-items)</action>
|
||||||
|
|
||||||
|
<action>**8b. Add to completed section (INSERT AT TOP - newest first)**</action>
|
||||||
|
<check if="type == bug">
|
||||||
|
<action>Locate "# Fixed Bugs" section in bugs.md</action>
|
||||||
|
<action>If section not found, create it</action>
|
||||||
|
<action>INSERT AT TOP of section (immediately after "# Fixed Bugs" header):</action>
|
||||||
|
<action>[IMPLEMENTED] {item_id}: {title} - {brief_description}. [Severity: {severity}, Platform: {platform}, Fixed: {date}, Verified: pending]</action>
|
||||||
|
<action> - Fix: {description of what was fixed}</action>
|
||||||
|
<action> - File(s): {list of modified files}</action>
|
||||||
|
</check>
|
||||||
|
<check if="type == feature">
|
||||||
|
<action>Locate "# Implemented Features" section in bugs.md</action>
|
||||||
|
<action>If section not found, create it before "# Fixed Bugs"</action>
|
||||||
|
<action>INSERT AT TOP of section (immediately after "# Implemented Features" header):</action>
|
||||||
|
<action>[IMPLEMENTED] {item_id}: {title} - {brief_description}. [Implemented: {date}, Platform: {platform}, Verified: pending]</action>
|
||||||
|
<action> - Files: {list of modified/created files}</action>
|
||||||
|
<action> - Features: {bullet list of what was implemented}</action>
|
||||||
|
</check>
|
||||||
|
<action>Write updated bugs.md</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="9" goal="Post-update validation">
|
||||||
|
<action>Search for {item_id} in both bugs.yaml and bugs.md using grep to validate updates</action>
|
||||||
|
<action>Confirm {item_id} shows status "fixed"/"implemented" in bugs.yaml</action>
|
||||||
|
<action>Confirm {item_id} has [IMPLEMENTED] tag in bugs.md</action>
|
||||||
|
<check if="validation fails">
|
||||||
|
<output>SYNC ERROR: Files may be out of sync. Please verify manually:
|
||||||
|
- bugs.yaml: Expected status "fixed"/"implemented"
|
||||||
|
- bugs.md: Expected [IMPLEMENTED] tag in appropriate section</output>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="10" goal="Present completion summary">
|
||||||
|
<output>**{item_id} {past_verb.upper()}**
|
||||||
|
|
||||||
|
**Changes Made:**
|
||||||
|
{for each modified file:}
|
||||||
|
- {file_path}: {what was changed}
|
||||||
|
{end for}
|
||||||
|
|
||||||
|
**Updated Tracking:**
|
||||||
|
- bugs.yaml: status -> "{status}", {date_field} -> {date}, files_modified updated
|
||||||
|
- bugs.md: Moved to "{target_section}" with [IMPLEMENTED] tag
|
||||||
|
|
||||||
|
**Verification Status:** pending
|
||||||
|
|
||||||
|
**Next Steps:**
|
||||||
|
1. Test manually
|
||||||
|
2. Run `/verify {item_id}` after verification to close
|
||||||
|
</output>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
</workflow>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
/implement bug-026
|
||||||
|
/implement feature-021
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Principles
|
||||||
|
|
||||||
|
1. **Auto-detect Type** - ID format determines bug vs feature handling
|
||||||
|
2. **Context First** - Always read and present details before implementing
|
||||||
|
3. **Confirm Approach** - Validate planned approach with user before coding
|
||||||
|
4. **Minimal Changes** - Only implement what's needed, no scope creep
|
||||||
|
5. **Dual Tracking** - ALWAYS update both bugs.yaml AND bugs.md
|
||||||
|
6. **[IMPLEMENTED] Tag** - Indicates complete but awaiting verification
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reference: Bug Tracking Definitions
|
||||||
|
|
||||||
|
### Severity Levels
|
||||||
|
|
||||||
|
| Level | Description | Action |
|
||||||
|
|-------|-------------|--------|
|
||||||
|
| **critical** | Blocks core functionality, prevents app use, or causes data loss (crashes, auth broken, data corruption) | Fix immediately, may require hotfix |
|
||||||
|
| **high** | Major feature broken, significant UX degradation, workaround exists but painful (platform-specific failure, 5+ sec delays, accessibility blocker) | Fix in current/next sprint |
|
||||||
|
| **medium** | Feature partially broken, UX degraded but usable (minor feature broken, unclear errors, 1-3 sec delays) | Fix when capacity allows |
|
||||||
|
| **low** | Minor issue, cosmetic, edge case (typos, spacing, visual glitches) | Fix opportunistically or defer |
|
||||||
|
|
||||||
|
### Complexity Levels
|
||||||
|
|
||||||
|
| Level | Description | Effort |
|
||||||
|
|-------|-------------|--------|
|
||||||
|
| **trivial** | Obvious fix, single line change, no investigation needed (typo, missing semicolon, wrong color) | < 30 minutes |
|
||||||
|
| **small** | Single file/component, clear root cause, solution known (missing validation, incorrect prop, logic error) | 30 min - 2 hours |
|
||||||
|
| **medium** | Multiple files affected OR investigation required (spans 2-3 components, debugging needed, integration issue) | 2-8 hours |
|
||||||
|
| **complex** | Architectural issue, affects multiple stories, requires design changes (race conditions, refactoring, profiling) | 8+ hours (1-2 days) |
|
||||||
|
|
||||||
|
### Workflow Routing Matrix
|
||||||
|
|
||||||
|
| Severity | Complexity | Workflow | Rationale |
|
||||||
|
|----------|------------|----------|-----------|
|
||||||
|
| critical | any | correct-course -> urgent | Need impact analysis even if small fix |
|
||||||
|
| high | trivial | direct-fix (urgent) | Fast path for obvious important fix |
|
||||||
|
| high | small | tech-spec (urgent) | Fast path with minimal overhead |
|
||||||
|
| high | medium+ | correct-course -> story | Need proper analysis + testing |
|
||||||
|
| medium | trivial | direct-fix | Too small for workflow overhead |
|
||||||
|
| medium | small | tech-spec | Isolated fix needs spec |
|
||||||
|
| medium | medium+ | correct-course -> story | Multi-file change needs story |
|
||||||
|
| low | trivial | direct-fix (defer) | Fix opportunistically |
|
||||||
|
| low | small+ | backlog (defer) | Document but don't schedule yet |
|
||||||
|
|
||||||
|
### Status Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
reported -> triaged -> routed -> in-progress -> fixed -> verified -> closed
|
||||||
|
```
|
||||||
|
|
||||||
|
| Status | Description |
|
||||||
|
|--------|-------------|
|
||||||
|
| **reported** | Bug logged in bugs.md, not yet analyzed |
|
||||||
|
| **triaged** | PM analyzed, assigned severity/complexity/workflow |
|
||||||
|
| **routed** | Workflow determined, story/tech-spec created |
|
||||||
|
| **in-progress** | Developer actively working on fix |
|
||||||
|
| **fixed** | Code changed, tests passing, ready for verification |
|
||||||
|
| **verified** | Bug confirmed fixed by reporter or QA |
|
||||||
|
| **closed** | Bug resolved and verified, no further action |
|
||||||
|
|
||||||
|
### Metadata Fields
|
||||||
|
|
||||||
|
| Field | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| id | Unique identifier (bug-NNN or feature-NNN) |
|
||||||
|
| title | Short description (< 80 chars) |
|
||||||
|
| description | Detailed explanation |
|
||||||
|
| severity | critical \| high \| medium \| low |
|
||||||
|
| complexity | trivial \| small \| medium \| complex |
|
||||||
|
| status | Current workflow state |
|
||||||
|
| recommended_workflow | direct-fix \| tech-spec \| correct-course \| backlog |
|
||||||
|
| effort_estimate | Hours (based on complexity) |
|
||||||
|
| reported_by / reported_date | Who found it and when |
|
||||||
|
| triaged_by / triaged_date | Who triaged and when |
|
||||||
|
| fixed_date / verified_date | Implementation and verification dates |
|
||||||
|
| related_story / related_epic | Context links |
|
||||||
|
| affected_platform | all \| ios \| android |
|
||||||
|
| doc_impact | Documentation impact: prd, architecture, ux flags + notes |
|
||||||
|
| notes | Investigation notes, decisions, implementation details |
|
||||||
|
|
@ -0,0 +1,22 @@
|
||||||
|
name: implement
|
||||||
|
description: "Implement a bug fix or feature - loads context from bugs.yaml, implements the code, updates both bugs.yaml and bugs.md with [IMPLEMENTED] tag"
|
||||||
|
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/implement"
|
||||||
|
instructions: "{installed_path}/instructions.md"
|
||||||
|
template: false
|
||||||
|
|
||||||
|
# Input and output files
|
||||||
|
variables:
|
||||||
|
bugs_md: "{output_folder}/bugs.md"
|
||||||
|
bugs_yaml: "{output_folder}/bugs.yaml"
|
||||||
|
|
||||||
|
standalone: true
|
||||||
|
|
@ -0,0 +1,219 @@
|
||||||
|
# Verify Workflow (Close Implemented Bugs/Features)
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<critical>This workflow verifies implemented items and closes them in both bugs.yaml and bugs.md</critical>
|
||||||
|
<critical>Communicate in {communication_language} with {user_name}</critical>
|
||||||
|
<critical>Removes [IMPLEMENTED] tag and updates status to CLOSED (bugs) or COMPLETE (features)</critical>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
|
||||||
|
<step n="1" goal="Get item ID or list pending items">
|
||||||
|
<check if="item_id provided in user input">
|
||||||
|
<action>Extract item ID from user input</action>
|
||||||
|
<action>Detect type from ID format:</action>
|
||||||
|
<action>- "bug-NNN" -> type = "bug", final_status = "CLOSED"</action>
|
||||||
|
<action>- "feature-NNN" -> type = "feature", final_status = "COMPLETE"</action>
|
||||||
|
<action>Proceed to Step 2</action>
|
||||||
|
</check>
|
||||||
|
<check if="no item_id provided OR user says 'list'">
|
||||||
|
<action>Search {bugs_yaml} for 'status: "fixed"' or 'status: "implemented"' using grep (do NOT read entire file)</action>
|
||||||
|
<action>Search {bugs_md} for '[IMPLEMENTED]' entries using grep</action>
|
||||||
|
<action>Find all items with:</action>
|
||||||
|
<action>- status == "fixed" or "implemented" in bugs.yaml</action>
|
||||||
|
<action>- [IMPLEMENTED] tag in bugs.md</action>
|
||||||
|
<output>**Pending Verification:**
|
||||||
|
|
||||||
|
{for each pending item:}
|
||||||
|
- **{item_id}**: {title} [{type}, {fixed_date or implemented_date}]
|
||||||
|
{end for}
|
||||||
|
|
||||||
|
**Total:** {count} item(s) awaiting verification
|
||||||
|
|
||||||
|
To verify an item: `/verify bug-026`
|
||||||
|
To verify all: Type "verify all"
|
||||||
|
</output>
|
||||||
|
<ask>Which item would you like to verify?</ask>
|
||||||
|
</check>
|
||||||
|
<check if="user says 'verify all' or 'all'">
|
||||||
|
<action>Set batch_mode = true</action>
|
||||||
|
<action>Collect all pending items</action>
|
||||||
|
<action>Proceed to Step 2 with batch processing</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="2" goal="Load item context and check sync">
|
||||||
|
<action>Search for {item_id} in {bugs_yaml} using grep with 50+ lines of context after the match (do NOT read entire file - it exceeds token limits)</action>
|
||||||
|
<check if="type == bug">
|
||||||
|
<action>Entry will be in bugs section, verify status == "fixed"</action>
|
||||||
|
</check>
|
||||||
|
<check if="type == feature">
|
||||||
|
<action>Entry will be in feature_requests section, verify status == "implemented"</action>
|
||||||
|
</check>
|
||||||
|
<check if="item not found OR status not fixed/implemented">
|
||||||
|
<output>{item_id} is not in an implemented state. Current status: {status}
|
||||||
|
|
||||||
|
Only items with status "fixed" (bugs) or "implemented" (features) can be verified.</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
<action>Extract metadata: title, description, fixed_date/implemented_date, notes</action>
|
||||||
|
|
||||||
|
<action>**Sync Check:** Also read {bugs_md} to verify sync status</action>
|
||||||
|
<check if="bugs.yaml says fixed/implemented but bugs.md missing [IMPLEMENTED] tag">
|
||||||
|
<output>SYNC WARNING: {item_id} status mismatch detected
|
||||||
|
- bugs.yaml: {yaml_status}
|
||||||
|
- bugs.md: Missing [IMPLEMENTED] tag (may have been implemented outside workflow)
|
||||||
|
|
||||||
|
Proceeding will update both files to CLOSED/COMPLETE.</output>
|
||||||
|
<ask>Continue with verification? (yes/no)</ask>
|
||||||
|
<check if="user says no">
|
||||||
|
<output>Cancelled. Please run /implement {item_id} first to sync files.</output>
|
||||||
|
<action>HALT</action>
|
||||||
|
</check>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="3" goal="Confirm verification">
|
||||||
|
<output>**Verify {item_id}: {title}**
|
||||||
|
|
||||||
|
**Type:** {type}
|
||||||
|
**{past_verb}:** {fixed_date or implemented_date}
|
||||||
|
|
||||||
|
**Implementation Notes:**
|
||||||
|
{notes - show the FIXED/IMPLEMENTED section}
|
||||||
|
|
||||||
|
**Files Changed:**
|
||||||
|
{extract file list from notes}
|
||||||
|
</output>
|
||||||
|
<ask>Has this been tested and verified working? (yes/no/skip)</ask>
|
||||||
|
<check if="user says no">
|
||||||
|
<ask>What issue did you find? (I'll add it to the notes)</ask>
|
||||||
|
<action>Append verification failure note to bugs.yaml notes field</action>
|
||||||
|
<output>Noted. {item_id} remains in implemented state for rework.</output>
|
||||||
|
<action>HALT or continue to next item in batch</action>
|
||||||
|
</check>
|
||||||
|
<check if="user says skip">
|
||||||
|
<output>Skipped. {item_id} remains in implemented state.</output>
|
||||||
|
<action>Continue to next item in batch or HALT</action>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="4" goal="Update bugs.yaml">
|
||||||
|
<action>Update entry in bugs.yaml:</action>
|
||||||
|
<action>- status: "closed"</action>
|
||||||
|
<action>- verified_by: {user_name}</action>
|
||||||
|
<action>- verified_date: {date} (YYYY-MM-DD format)</action>
|
||||||
|
<action>- Append to notes: "Verified ({date}) by {user_name}"</action>
|
||||||
|
<action>Write updated bugs.yaml</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="5" goal="Update bugs.md">
|
||||||
|
<action>Search for {item_id} in {bugs_md} using grep with surrounding context to locate the entry</action>
|
||||||
|
|
||||||
|
<action>**5a. Find the entry**</action>
|
||||||
|
<check if="type == bug">
|
||||||
|
<action>Search for "[IMPLEMENTED] {item_id}:" in "# Fixed Bugs" section</action>
|
||||||
|
<check if="not found">
|
||||||
|
<action>Search for "{item_id}:" in "# Tracked Bugs" section (implemented outside workflow)</action>
|
||||||
|
</check>
|
||||||
|
</check>
|
||||||
|
<check if="type == feature">
|
||||||
|
<action>Search for "[IMPLEMENTED] {item_id}:" in "# Implemented Features" section</action>
|
||||||
|
<check if="not found">
|
||||||
|
<action>Search for "{item_id}:" in "# Tracked Feature Requests" section (implemented outside workflow)</action>
|
||||||
|
</check>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<action>**5b. Move entry if in wrong section**</action>
|
||||||
|
<check if="entry found in Tracked section (implemented outside workflow)">
|
||||||
|
<action>DELETE the entry from "# Tracked Bugs" or "# Tracked Feature Requests"</action>
|
||||||
|
<action>ADD entry to correct section:</action>
|
||||||
|
<check if="type == bug">
|
||||||
|
<action>Add to "# Fixed Bugs" section</action>
|
||||||
|
</check>
|
||||||
|
<check if="type == feature">
|
||||||
|
<action>Add to "# Implemented Features" section (at top, before other entries)</action>
|
||||||
|
</check>
|
||||||
|
</check>
|
||||||
|
|
||||||
|
<action>**5c. Update the entry format**</action>
|
||||||
|
<action>Remove "[IMPLEMENTED] " prefix if present</action>
|
||||||
|
<action>Update the status tag in brackets:</action>
|
||||||
|
<check if="type == bug">
|
||||||
|
<action>Change from "[Severity: X, Fixed: DATE, Verified: pending]" or "[Severity: X, Complexity: Y, Workflow: Z]"</action>
|
||||||
|
<action>To "[Severity: X, Platform: Y, Fixed: {date}, Verified: {date}, CLOSED]"</action>
|
||||||
|
</check>
|
||||||
|
<check if="type == feature">
|
||||||
|
<action>Change from "[Implemented: DATE, Verified: pending]" or "[Priority: X, Complexity: Y, Workflow: Z]"</action>
|
||||||
|
<action>To "[Implemented: {date}, Platform: Y, Verified: {date}, COMPLETE]"</action>
|
||||||
|
</check>
|
||||||
|
<action>Add implementation notes if available from bugs.yaml</action>
|
||||||
|
|
||||||
|
<action>Write updated bugs.md</action>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="5.5" goal="Post-update validation">
|
||||||
|
<action>Search for {item_id} in both bugs.yaml and bugs.md using grep to validate updates</action>
|
||||||
|
<action>Confirm bugs.yaml: status="closed", verified_by set, verified_date set</action>
|
||||||
|
<action>Confirm bugs.md: No [IMPLEMENTED] tag, has CLOSED/COMPLETE in status tag</action>
|
||||||
|
<check if="validation fails">
|
||||||
|
<output>SYNC ERROR: Verification may be incomplete. Please check both files:
|
||||||
|
- bugs.yaml: Expected status "closed", verified_by/verified_date set
|
||||||
|
- bugs.md: Expected CLOSED/COMPLETE tag, no [IMPLEMENTED] prefix</output>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step n="6" goal="Present completion summary">
|
||||||
|
<check if="batch_mode">
|
||||||
|
<output>**Verification Complete**
|
||||||
|
|
||||||
|
**Verified {verified_count} item(s):**
|
||||||
|
{for each verified item:}
|
||||||
|
- {item_id}: {title} -> {final_status}
|
||||||
|
{end for}
|
||||||
|
|
||||||
|
**Skipped:** {skipped_count}
|
||||||
|
**Failed verification:** {failed_count}
|
||||||
|
|
||||||
|
**Updated Files:**
|
||||||
|
- bugs.yaml: status -> "closed", verified_by/verified_date set
|
||||||
|
- bugs.md: [IMPLEMENTED] tag removed, status -> {final_status}
|
||||||
|
</output>
|
||||||
|
</check>
|
||||||
|
<check if="not batch_mode">
|
||||||
|
<output>**{item_id} VERIFIED and {final_status}**
|
||||||
|
|
||||||
|
**Updated:**
|
||||||
|
- bugs.yaml: status -> "closed", verified_by -> {user_name}, verified_date -> {date}
|
||||||
|
- bugs.md: Removed [IMPLEMENTED] tag, added "Verified: {date}, {final_status}"
|
||||||
|
|
||||||
|
This item is now fully closed.
|
||||||
|
</output>
|
||||||
|
</check>
|
||||||
|
</step>
|
||||||
|
|
||||||
|
</workflow>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
/verify # List all pending verification
|
||||||
|
/verify bug-026 # Verify specific bug
|
||||||
|
/verify feature-021 # Verify specific feature
|
||||||
|
/verify all # Verify all pending items
|
||||||
|
```
|
||||||
|
|
||||||
|
## Status Transitions
|
||||||
|
|
||||||
|
| Type | Before | After |
|
||||||
|
|------|--------|-------|
|
||||||
|
| Bug | status: "fixed", [IMPLEMENTED] | status: "closed", CLOSED |
|
||||||
|
| Feature | status: "implemented", [IMPLEMENTED] | status: "closed", COMPLETE |
|
||||||
|
|
||||||
|
## Key Principles
|
||||||
|
|
||||||
|
1. **Verification Gate** - User must confirm item was tested and works
|
||||||
|
2. **Failure Handling** - If verification fails, add note and keep in implemented state
|
||||||
|
3. **Batch Support** - Can verify multiple items at once
|
||||||
|
4. **Dual Tracking** - ALWAYS update both bugs.yaml AND bugs.md
|
||||||
|
5. **Proper Closure** - Removes [IMPLEMENTED] tag, adds final CLOSED/COMPLETE status
|
||||||
|
|
@ -0,0 +1,22 @@
|
||||||
|
name: verify
|
||||||
|
description: "Verify and close implemented bugs/features - removes [IMPLEMENTED] tag, updates status to CLOSED/COMPLETE in both bugs.yaml and bugs.md"
|
||||||
|
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/verify"
|
||||||
|
instructions: "{installed_path}/instructions.md"
|
||||||
|
template: false
|
||||||
|
|
||||||
|
# Input and output files
|
||||||
|
variables:
|
||||||
|
bugs_md: "{output_folder}/bugs.md"
|
||||||
|
bugs_yaml: "{output_folder}/bugs.yaml"
|
||||||
|
|
||||||
|
standalone: true
|
||||||
Loading…
Reference in New Issue