---
type: skill
domain: general
---

# LOGIC_LANCE
> **ROLE:** Systematic debugging and root cause analysis
> **TRIGGER:** When facing bugs, unexpected behavior, conflicting requirements, or ambiguous problems

## Core Directive
Find the root cause, not the symptom. Most "fixes" that fail are patching the wrong layer. This skill enforces a structured decomposition that traces the actual execution path before writing any code.

## Step-by-Step Protocol
1. **Reproduce first:** Before theorizing, confirm the bug exists and is reproducible. Run the exact command or code path that fails. Capture the full error output including traceback, file path, and line number. If you cannot reproduce it, state that and stop.
2. **Trace the call chain:** Starting from the error, trace backwards through the call stack. Read each file at the specific line referenced in the traceback. List the chain: `entry_point -> function_A (file:line) -> function_B (file:line) -> crash site`. The bug is usually 1-2 levels above the crash, not at the crash itself.
3. **Identify the actual vs expected state:** At the crash site, determine: What value was present? What value was expected? Where did the wrong value originate? Use print/log statements or read the data file to confirm actual runtime state.
4. **Check brain for prior encounters:** Run `python Autonomic_System/Utilities/Tools/brain_query.py --query "<error or module name>"` to see if this bug or a similar one was solved before. Check `Hippocampus/Patterns/` for known failure modes.
5. **Fix at the root, verify the fix:** Apply the fix at the origination point of the wrong value, not at the crash site. After fixing, re-run the exact reproduction command from Step 1. If it passes, check for 2 related scenarios to confirm no regression.

## Metrics & Thresholds
- Max 3 hypotheses before requiring reproduction evidence
- Every bug fix must include the reproduction command in the commit message or save
- Call chain trace must list at least 2 levels (crash site + caller)
- Zero "shotgun fixes" (changing 5 things hoping one works) -- change 1 thing, test, repeat
- Anti-pattern check mandatory before implementing any fix

## Examples

### Good
```
Bug: pulse_worker.py crashes with KeyError: 'task_id'
1. Reproduce: python pulse_worker.py  -> KeyError at line 92
2. Trace: cmd_agent() -> claim_task() -> task['task_id'] (line 92)
3. Actual state: task dict uses 'id' key, not 'task_id'
4. Brain query: "task_id vs id" -> Found: task_board uses 'task_id', old tasks use 'id'
5. Root cause: Migration left old tasks with 'id' key
   Fix: task.get('task_id', task.get('id')) at line 92
   Verified: re-ran worker, claims old and new tasks correctly
```

### Bad (Anti-Pattern)
```
Bug: pulse_worker.py crashes with KeyError: 'task_id'
Fix: wrapped line 92 in try/except pass

# This silences the error without understanding it.
# The task is never claimed, the worker appears idle,
# and the root cause (key mismatch) persists for every old task.
```
Catching exceptions without understanding them creates silent failures that compound.

## Tools to Use
- `brain_query.py --query "<error message or module>"` -- check for prior solutions
- `brain_search.py --query "<function name>"` -- find where a function is defined/used
- `Grep` -- locate exact error strings and call sites across the codebase
- `pulse_save.py --agent <you> --failures "root cause: ..."` -- record for future agents

## Verification
- [ ] Bug reproduced with exact command before any fix attempted
- [ ] Call chain traced at least 2 levels deep
- [ ] Root cause identified (not just symptom patched)
- [ ] Brain and anti-pattern registry checked for prior encounters
- [ ] Fix verified by re-running the original reproduction command
