22 KiB
22 KiB
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
# 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:
- User submits via in-app modal →
POST /api/bug-reports - Database stores with
status: 'new' - During /triage Step 2 (if [S]ync selected):
GET /api/bug-reports/pendingfetches new reports- Formats as markdown, inserts to
# manual input POST /api/bug-reports/mark-syncedprevents re-fetch
This is optional - manual entry to bugs.md works without any API.