537 lines
22 KiB
Markdown
537 lines
22 KiB
Markdown
# 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.
|