ql-debug

name	ql-debug
description	Two-phase diagnostic system combining rapid root-cause identification with residual sweep verification. Prevents cascading AI debugging damage by enforcing four mandatory analysis layers before any code change.
user-invocable	true
allowed-tools	Read, Glob, Grep, Edit, Write, Bash

/ql-debug - Diagnostic Fixer

/ql-debug IMPLEMENT / SUBSTANTIATE / GATE Fixer ql-fixer — Rapid root-cause (4-layer analysis on reported symptoms) ql-fixer — Residual sweep (4-layer analysis on fixed state) Two-phase diagnosis: root-cause fix + residual sweep report

Purpose

Bring surgical precision to debugging. AI coding agents typically pull a thread and watch the codebase unravel — guessing at fixes, introducing regressions, chasing cascading failures. The Fixer enforces a formal methodology: prove the root cause first, then propose the minimal fix. No code changes until the cause-effect chain is established with evidence.

When to Use

• Runtime errors with unclear origin or misleading stack traces
• Non-deterministic failures (works sometimes, fails others)
• Cascading failures after refactoring
• Proactive verification after significant logic changes
• Test failures requiring formal root-cause analysis
• Structural defects blocking phase transitions

Execution Protocol

Step 1: Describe the Problem

Provide the Fixer with:

• Symptom: What is failing? Error message, unexpected behavior, test output.
• Context: What changed recently? Which files are involved?
• Reproduction: How to trigger the failure (if known).

If invoking proactively (no specific failure), state which files or logic paths were changed.

Step 2: Two-Phase Agent Dispatch

Phase 1 — Rapid Root-Cause (ql-fixer)

Launch the ql-fixer agent (use subagent_type: "ql-fixer") with the problem description. The fixer runs all four layers (Dijkstra, Hamming/Shannon, Turing/Hopper, Zeller) focused on the REPORTED symptoms. It identifies root causes and proposes fixes.

Apply the proposed fixes.

Phase 2 — Residual Sweep (ql-fixer, resumed)

After Phase 1 fixes are applied, launch the ql-fixer agent again to:

• Verify the fixes are complete and correct
• Sweep for residual issues introduced or exposed by the fixes
• Check for similar patterns elsewhere in the codebase
• Validate build artifacts match source (dist/out staleness check)

Phase 2 uses the same four-layer methodology but scoped to the FIXED state, not the original symptoms.

Step 3: Diagnosis & Handoff

The Fixer produces a final diagnosis with:

• Root cause location and explanation
• Cause-effect chain
• Recommended fix with regression risk assessment
• Related issues discovered during analysis

Handoff rules:

• Straightforward fix: Fixer proposes exact code changes
• Architectural changes needed: hand off to /ql-plan for Governor review
• Implementation ready: hand off to /ql-implement for the Specialist
• Test validation needed: hand off to /ql-substantiate for the Judge

Constraints

• NEVER apply a fix without completing at least Layers 1-3
• NEVER propose a fix that only addresses the symptom
• ALWAYS distinguish symptom from root cause
• ALWAYS check for similar patterns elsewhere in the codebase
• ALWAYS document findings with line numbers and evidence
• ALWAYS use subagent_type: "ql-fixer" (not ultimate-debugger)

Integration with QoreLogic

This skill implements:

• S.H.I.E.L.D. Diagnostic Service: On-demand across IMPLEMENT, SUBSTANTIATE, and GATE phases
• Two-Phase Architecture: Root-cause first, then residual sweep
• Four-Layer Methodology: Dijkstra, Hamming/Shannon, Turing/Hopper, Zeller
• Evidence-Based Fixes: Every conclusion backed by code evidence
• Cross-Agent Handoff: Routes results to appropriate next agent/skill