/quick-bugfix

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

/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

Discover the project's standards as part of analysis and planning (Steps 3–4), relevant to the bug area — not as a bulk upfront read.

• Read `.maister/docs/INDEX.md` to find which standards exist.
• **Then read the specific standard files it points to that match the bug area** (e.g. API bug → api + error-handling standards; form bug → validation + frontend standards; query bug → database + backend standards). Reading INDEX.md alone is NOT sufficient — this is mandatory.
• Apply the matched standards in the fix plan (Step 4) and during implementation (Step 6).

If `.maister/docs/INDEX.md` does not exist, note it and suggest `/maister-init` in the completion summary.

Step 3: Analyze & Assess Complexity

Investigate until you have a root-cause hypothesis backed by file/line evidence, the affected files, and the existing tests that cover them.

**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:**

## 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 Maister 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 —