/vt-c-investigate-bug¶

Bug investigation using the bugfix-orchestrator. Accepts BUG-NNN (tracked bug) or free-text description.

Plugin: core-standards
Usage: /vt-c-investigate-bug BUG-NNN | "<bug description>" [--severity critical|high|medium|low]

Investigate Bug Command¶

Systematically investigate, reproduce, and analyze bugs using the bugfix-orchestrator.

Accepts either a tracked BUG-NNN identifier (from the BugChen pipeline) or a free-text description.

Usage¶

# Tracked bug from BugChen pipeline
/vt-c-investigate-bug BUG-007

# Free-text description (original behavior — unchanged)
/vt-c-investigate-bug "Users can't login after password reset"
/vt-c-investigate-bug "Checkout fails intermittently" --severity high
/vt-c-investigate-bug "Data not syncing between tabs"

BUG-NNN Mode¶

When the argument exactly matches BUG-NNN (digits only, e.g. BUG-007):

Glob bugs/NNN-*/report.md to find the bug directory

If not found → error:

BUG-NNN not found in bugs/.
Run /vt-c-triage-bugs to promote it from intake first.

If found → read the full text of bugs/NNN-slug/report.md
Update bugs/NNN-slug/state.yaml: set status: investigating (before calling orchestrator, so status reflects work-in-progress if the session ends unexpectedly)
Pass the full report.md content verbatim as the initial bug description to the bugfix-orchestrator (do NOT pass a file path — pass the actual text content)
After orchestrator returns, write its output to bugs/NNN-slug/investigation.md
Update bugs/NNN-slug/state.yaml: set status: fix-ready

Display:

✓ Investigation complete: bugs/NNN-slug/investigation.md
Status: investigating → fix-ready

Next: /vt-c-activate BUG-NNN  to create a fix branch

What This Command Does¶

Invokes the bugfix-orchestrator to coordinate the investigation
Attempts to reproduce the bug via bug-reproduction-validator
Analyzes git history to find when the bug was introduced
Checks for patterns to identify if this is a systemic issue
Produces investigation report with root cause and fix guidance

Orchestration Flow¶

/vt-c-investigate-bug "description"
      │
      ▼
┌─────────────────────────────┐
│     bugfix-orchestrator      │
└─────────────────────────────┘
      │
      ├──▶ bug-reproduction-validator
      │         │
      │         ▼
      │    Reproduction confirmed?
      │         │
      ├─────────┴─────────────────────▶ git-history-analyzer
      │                                       │
      │                                       ▼
      │                               When did this break?
      │                                       │
      └──▶ pattern-recognition-specialist ◀───┘
                    │
                    ▼
            Is this a pattern?
                    │
                    ▼
         Investigation Report

Prerequisites¶

Provide as much context as possible: - Steps to reproduce - Expected vs actual behavior - Error messages or logs - Environment details - Affected users/accounts

Output Format¶

## Bug Investigation Report

### Summary
- **Bug**: [brief description]
- **Severity**: [critical/high/medium/low]
- **Status**: [reproduced/not reproduced/intermittent]

### Reproduction
**Steps**:
1. [Step 1]
2. [Step 2]

**Expected**: [what should happen]
**Actual**: [what actually happens]
**Reproducible**: [yes/no/intermittent]

### Root Cause
[Technical explanation of why this is happening]

### Historical Context
- **Introduced**: [commit/date]
- **Related changes**: [relevant commits]

### Pattern Analysis
[Is this a one-off or systemic issue?]

### Recommended Fix
[Guidance for fixing the issue]

### Prevention
[How to prevent similar bugs]

Arguments¶

Argument	Description
`BUG-NNN`	Tracked bug ID (e.g. `BUG-007`) — loads from `bugs/NNN-*/report.md`
`<description>`	Free-text bug description (original behavior)
`--severity`	Urgency level (critical, high, medium, low) — free-text mode only

Severity Guidelines¶

Severity	Use When
Critical	Production down, data loss, security breach
High	Major feature broken, significant user impact
Medium	Feature degraded, workaround exists
Low	Minor issue, cosmetic

What Happens Next¶

After investigation completes:

If fix is straightforward:
Implement the fix
Run /vt-c-4-review for code quality
Run /vt-c-5-finalize before deployment
If needs more context:
Gather additional information requested
Re-run /vt-c-investigate-bug with more details
If it's a pattern:
Address all instances of the pattern
Consider adding linting rules or tests

Tips for Effective Bug Reports¶

Good bug description:

"Users get 500 error when clicking 'Export PDF' on the reports page.
Error in logs: 'Cannot read property length of undefined'.
Happens for users with > 100 records."

Poor bug description:

"Export doesn't work"

Include: - Specific error messages - Steps to reproduce - Environmental context - Affected scope