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

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:

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 — 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 standards check (mandatory): after the test is green, go through the ## Standards Compliance Checklist from the plan file and verify each item — mark pass/fail and report it in the summary. Address any failure before marking the task complete.

Graceful Fallback

If .maister/docs/ does not exist:

Proceed with the bug fix normally, then note:

"No Maister standards found. Consider running `/maister-init` to initialize
project documentation and coding standards for better consistency."