z-bugfix

What it does and when to use it

Gated 4-phase diagnosis workflow for hard bugs, concurrency issues, and performance regressions. Use when something throws, fails, deadlocks, freezes, or behaves unexpectedly.

How it works

1. Phase 1: Sensory Sweep (Observable Reality)
2. Phase 2: Socratic Inquiry & Hypotheses
3. Phase 3: Deterministic Reproduction Test (Red Gate)
4. Phase 4: Targeted Fix & Zero-Regression Verification (Green Gate)

---
name: z-bugfix
description: Gated 4-phase diagnosis workflow for hard bugs, concurrency issues, and performance regressions. Use when something throws, fails, deadlocks, freezes, or behaves unexpectedly.
---

# Z-Bugfix Investigation Protocol

Enforces a rigorous 4-phase investigative gate. Never jump directly to guessing fixes in production code.

## Phase 1: Sensory Sweep (Observable Reality)
1. Read exact error messages, stack traces, and failure exit codes verbatim.
2. Locate the precise file and line numbers of the failure point.
3. Identify recent code diffs or environmental triggers that exposed the issue.

## Phase 2: Socratic Inquiry & Hypotheses
1. Formulate 2–3 competing hypotheses explaining the failure:
   - $H_1$: Logic/boundary condition error.
   - $H_2$: Concurrency / race condition / state mutation timing.
   - $H_3$: Environmental / configuration / type mismatch.
2. For each hypothesis, identify a testable distinction.

## Phase 3: Deterministic Reproduction Test (Red Gate)
1. Write a minimal automated reproduction test reproducing the exact failure.
2. Execute the test and verify it FAILS with the expected signature (Red).
3. If the test cannot reproduce the issue, do NOT touch production code; return to Phase 1.

## Phase 4: Targeted Fix & Zero-Regression Verification (Green Gate)
1. Apply the minimal necessary correction to eliminate the root cause.
2. Re-run the reproduction test and confirm it PASSES (Green).
3. Re-run the entire project test suite to verify zero regression across existing features.
4. Document the lesson in 3 parts: `<Problem> | <Root Cause> | <Fix>` for episodic memory harvesting.

Versions

The database has no other skills named z-bugfix.

Database snapshot: 13.11.2026 · package version a367d99b4a1f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

• 100diagnosing-bugs
  Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
• 95diagnosing-bugs
  Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
• 90diagnosing-bugs
  Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
• 90diagnosing-bugs
  Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
• 90diagnosing-bugs
  Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
• 90diagnosing-bugs
  Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.