---
name: quick-bugfix
description: Quick bug fix with TDD red/green gates and complexity escalation
argument-hint: "[bug description]"
---
# Quick Bug Fix
Lightweight TDD-driven bug fix workflow with planning mode. Analyze the bug, present a fix plan for approval, then reproduce with a failing test, fix, and verify. No orchestrator state, no task directory, no subagents.
For complex bugs that grow beyond a quick fix, suggests escalating to the full development workflow (`/maister-development`).
## Usage
```bash
/maister-quick-bugfix "Login form submits twice on slow connections"
/maister-quick-bugfix "API returns 500 when email contains special characters"
/maister-quick-bugfix "Dark mode toggle doesn't persist after refresh"
```
## When to Use
**Use `/maister-quick-bugfix` when:**
- Bug is reasonably scoped and reproducible
- You have a clear description of expected vs actual behavior
- Fix likely touches a small number of files
**Use `/maister-development` instead when:**
- Bug requires architectural changes
- Multiple subsystems are involved
- You need formal specification and planning
---
## Workflow
### Step 1: Parse Input
**Get the bug description:**
- If provided as argument, use it directly
- If not provided, scan the recent conversation for bug context (error messages, reproduction steps, discussed symptoms). If found, use that as the bug description.
- Only if no argument AND no bug context in session, use ask_user:
```
"Describe the bug — what's the expected behavior vs actual behavior?"
```
### Step 2: Discover Standards
**CRITICAL: This step MUST complete before entering plan mode.**
**Check if `.maister/docs/INDEX.md` exists:**
**If exists:**
1. Read INDEX.md to discover available documentation and standards
2. Identify which standards are relevant based on:
- The categories and files listed in INDEX.md
- The area of the bug (e.g., API, frontend, database)
- Keywords in the bug description
3. **READ the applicable standard files** (see Standards Reading Enforcement below)
**If not exists:**
- Note that no standards are available
- Suggest running `/maister-init` in completion message
### Standards Reading Enforcement (MANDATORY)
**BLOCKING**: Reading INDEX.md alone is NOT sufficient. You MUST read actual standard files.
**Enforcement Process**:
1. Read INDEX.md to discover available standards
2. Identify which standards apply based on the bug area
3. **READ each applicable standard file** using Read tool (not just note it exists)
4. Apply standards during fix implementation
5. List applied standards in completion summary
**Examples of standard discovery**:
- Bug in API handler → Read API and error-handling standards
- Bug in form validation → Read validation and frontend standards
- Bug in database query → Read database and backend standards
### Step 3: Analyze & Assess Complexity
**Explore the codebase to understand the bug:**
1. Search for relevant files (Glob, Grep, Read)
2. Trace the code path where the bug occurs
3. Identify: likely root cause, affected files, existing tests
4. Form a root cause hypothesis
**Complexity Escalation Check:**
Assess whether this bug exceeds quick-fix scope. If **2 or more** of these signals are detected, suggest escalation:
| Signal | Example |
|--------|---------|
| Changes span 5+ files across multiple modules | Bug in shared utility affects API, frontend, and background jobs |
| Requires database schema or data model changes | Missing column, wrong relationship, migration needed |
| Multiple valid fix approaches with architectural trade-offs | Could fix at API layer, middleware layer, or client layer |
| Security-sensitive code | Auth, crypto, permissions, input sanitization |
| Root cause unclear after initial analysis | Symptoms don't point to a single location |
**If escalation triggered:**
Use ask_user:
- Question: "This bug appears more complex than a quick fix — [describe why]. How would you like to proceed?"
- Options:
1. "Continue with quick fix" — proceed, accepting the complexity
2. "Switch to full development workflow" — stop here and suggest running `/maister-development` with the bug description and analysis context
**If no escalation needed or user chooses to continue:** proceed to Step 4.
### Step 4: Enter Planning Mode
**Use the `EnterPlanMode` tool to present the fix plan for user approval.**
Standards context from Step 2 and analysis from Step 3 MUST inform the plan.
**Plan file content:**
```markdown
## Bug Analysis
**Root Cause**: [hypothesis with evidence — file paths, code references]
**Affected Files**: [list of files that need changes]
## Proposed Fix
[Description of the fix approach — what changes, why this approach]
## Test Strategy
[What the failing test will assert — setup conditions, expected behavior]
## Applicable Standards
[List each standard file read, with key guidelines extracted from each.
If no standards exist: "No AI SDLC standards found. Consider running `/maister-init`."]
## Standards Compliance Checklist
- [ ] [Guideline from standard file] (from `standards/[path]`)
- [ ] [Guideline from standard file] (from `standards/[path]`)
```
### ExitPlanMode Gate: Mandatory Sections
**BLOCKING: Do NOT call `ExitPlanMode` until the plan file contains:**
1. **"## Bug Analysis"** — root cause hypothesis with evidence
2. **"## Proposed Fix"** — what changes and why
3. **"## Test Strategy"** — what the TDD red test will assert
4. **"## Applicable Standards"** — standards read and key guidelines
5. **"## Standards Compliance Checklist"** — checkboxes for applicable guidelines
If any section is missing, add it before calling ExitPlanMode.
### Step 5: TDD Red Gate
**Write a failing test that reproduces the bug.**
1. Identify the appropriate test file (existing test suite or create new test file following project conventions)
2. Write a test that:
- Sets up the conditions that trigger the bug
- Asserts the **correct** (expected) behavior
- Should FAIL with current code (proving the bug exists)
3. Run the test
**The test MUST fail.** This proves the bug is real and reproducible.
**If the test passes:**
- The bug may not be what we think, or it's already fixed
- Investigate further — re-read the bug description, check if conditions are correct
- Use ask_user: "The reproduction test passes — the expected behavior already works under these conditions. Is the bug description accurate, or are there additional conditions?"
### Step 6: Fix & Verify (TDD Green)
**Implement the fix:**
1. Apply the fix based on the approved plan from Step 4
2. **Apply discovered standards** from Step 2
3. Run the failing test — it MUST now pass
4. Run the full test file and related test files to check for regressions
**If tests fail after fix:**
- Analyze the failure
- Adjust the fix
- Re-run tests
- Maximum 3 fix-and-verify iterations
**If still failing after 3 attempts:**
- Stop and present findings to the user
- Suggest escalating to `/maister-development` for a more thorough approach
### Step 7: Summary
**Provide completion summary:**
- **Root cause**: What caused the bug
- **Fix**: What was changed and why
- **Files modified**: List of changed files
- **Standards applied**: Which standards from INDEX.md were followed
- **Tests**: Which tests were run and their results (including the TDD red→green transition)
- **Commit suggestion**: Propose a commit message
**Post-implementation: verify standards compliance using the checklist from the plan file.**
---
## What This Does
1. **Parses** bug description from user input
2. **Discovers** applicable standards from `.maister/docs/INDEX.md`
3. **Analyzes** codebase to find root cause and assess complexity
4. **Escalates** to full development workflow if bug is too complex
5. **Plans** the fix and presents for user approval via planning mode
6. **Reproduces** bug with a failing test (TDD Red)
7. **Fixes** the bug and verifies test passes (TDD Green)
8. **Summarizes** root cause, fix, standards applied, and test results
## Graceful Fallback
**If `.maister/docs/` does not exist:**
Proceed with the bug fix normally, then note:
```
"No AI SDLC standards found. Consider running `/maister-init` to initialize
project documentation and coding standards for better consistency."
```