non-linear-debugging

name	non-linear-debugging
description	Triggered when the agent needs to debug complex errors, analyze obscure runtime failures, find subtle bugs, or trace system anomalies using non-linear, multidimensional hypothesis graphs, backward-forward triangulation, behavioral state inversion, and dynamic perturbation instead of slow sequential linear step-by-step debugging.

Non-Linear Debugging & Bug Discovery Engine

Enables the AI agent to systematically diagnose, analyze, and resolve complex software errors, obscure bugs, race conditions, memory/state leaks, and system anomalies using non-linear, graph-based cognitive methodologies instead of sequential, line-by-line debugging.

---

When to Use This Skill

• Trigger keywords: "non-linear debug", "debug error", "analyze error", "find bug", "cari bug", "investigasi error", "non linear bug finding", "root cause triangulation", "complex failure analysis".
• When a bug involves asynchronous event loops, multi-service communication (e.g. t-line ↔ SuperAgent bridge), race conditions, state synchronization mismatches, or multi-component failure cascades.
• When traditional step-by-step linear tracing fails or is too slow due to missing or noisy error logs.
• When facing ambiguous symptoms where multiple independent factors might be interacting.

---

Core Non-Linear Debugging Paradigms

               ┌───────────────────────────────────────┐
               │    Forward Tracing (Source ──►)      │
               └───────────────────┬───────────────────┘
                                   │
                                   ▼
┌──────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
│ Hypothesis H₁    │───►│   COLLISION NODE    │◄───│ Hypothesis H₃    │
│ (State / Timing) │    │   (Root Cause Δ)    │    │ (Config / IPC)   │
└──────────────────┘    └─────────────────────┘    └──────────────────┘
                                   ▲
                                   │
               ┌───────────────────┴───────────────────┐
               │    Backward Tracing (◄── Sink/Crash) │
               └───────────────────────────────────────┘

1. Bidirectional Cause-Effect Triangulation (Backward-Forward Tracing)

• Backward Tracing ($\leftarrow \text{Crash Sink}$): Trace upstream from where the exception is thrown, state is mutated, or process crashes.
• Forward Tracing ($\text{Input Source} \rightarrow$): Trace downstream from initial request, user trigger, or state payload entry.
• Collision Node Identification ($\otimes$): Identify the exact intersection node where valid forward state violates backward invariants.

2. Multi-Hypothesis Superposition ($H_{1..N}$)

Simultaneously evaluate multiple orthogonal root-cause hypotheses in parallel rather than sequentially testing one by one:

• $H_{\text{Lifecycle}}$: Process startup, race conditions, port binding, auto-restart loops.
• $H_{\text{State/Contract}}$: Unhandled promise rejections, type mismatch, null dereference, stale cache.
• $H_{\text{Transport/IPC}}$: Socket disconnect, HTTP proxy timeout, payload serialization, stream buffering.
• $H_{\text{Environment/Config}}$: Missing env vars, malformed JSON config, path resolution errors.

3. Differential State Inversion (Negative Space Analysis)

• Analyze execution paths that succeed vs paths that fail.
• Isolate the Minimal Differential Delta ($\Delta$): What exact invariant changes between the working scenario and the breaking scenario?

4. Maximum-Information-Gain Probing (Non-Linear Bisection)

Design diagnostic probes (log extraction, targeted grep, type checks, state inspection) that eliminate multiple hypotheses in a single pass:

• Rule: Never run a diagnostic step that tests only 1 narrow hypothesis if a broader probe can rule out half of $H_{1..N}$ at once.

5. Entropy & Multi-Symptom Cascade Compression

Compress complex error chains (e.g., ECONNREFUSED $\to$ WebSocket closed $\to$ React Unhandled Rejection $\to$ UI freeze) into a Single Root-Cause Singularity. Do not treat downstream symptoms as separate bugs.

---

5-Pass Non-Linear Debugging Protocol

Pass 1: Vectorized Symptom Intake & Graph Assembly

Construct a symbolic dependency graph of the failure rather than reading code top-to-bottom:

[Source: UI Click / WS Message] ──► [Bridge: superAgentBridge.ts] ──► [HTTP Port 7888] ──► [Crash / Error Sink]

Identify all active error signatures, logs, exit codes, and broken expectations.

Pass 2: Hypotheses Superposition Matrix

Formulate 3–5 parallel hypotheses ($H_1, H_2, H_3, H_4$) spanning different subsystem dimensions. Assign an initial confidence score and high-gain verification test for each.

| Hypothesis | Subsystem | Failure Mechanism | High-Gain Verification Probe |
|---|---|---|---|
| **H₁: Lifecycle Race** | Backend Bridge | Process spawned before port 7888 is ready | Check startup timing & ping response logs |
| **H₂: Session Key Mismatch** | REST / WS | `x-workspace-path` missing in headers | Grep `resolveSession` call parameters |
| **H₃: Transport Timeout** | HTTP Proxy | Proxy timeout reached during long LLM pass | Verify `timeoutMs` settings in bridge request |

Pass 3: High-Information-Gain Bisecting Probes

Execute targeted diagnostic commands or code inspections to test $H_{1..N}$ concurrently.

• Inspect exact log traces, stack traces, and status endpoints.
• Narrow down the hypothesis space in $O(\log N)$ steps.

Pass 4: Root-Cause Collision Node Pinpointing

Identify the exact file, line range, or async timing window where the invariant breaks. Validate with empirical evidence (exact error line, type violation, or execution trace).

Pass 5: Minimalist Fix & Invariant Guarding

Apply the fix following pragmatic-minimalism:

1. Fix the root cause at the collision node.
2. Add a defensive guard or fallback mechanism to prevent regression.
3. Validate by compiling, building, or testing.

---

Execution Checklist & Core Invariants

• No Blind Guesses: Diagnosis must be justified by empirical log lines, stack traces, or verified code inspection.
• Symptom Masking Forbidden: Never wrap errors in empty try/catch or return dummy fallbacks to hide failures.
• Multi-Symptom Collapse: Treat failure cascades as 1 bug with 1 root cause.
• Empirical Verification: Run build/test commands to confirm the fix before declaring completion.