enterprise-debug

Files (2)

• SKILL.md
• evals.json · evals/

SKILL.md (first lines)

### LEARNED BEHAVIORS (auto-loaded)

Before starting, load domain-specific lessons:
1. Call `cortex_lessons(tag='feedback:DEBUG')` to retrieve corrections specific to this skill
2. If results exist, read each lesson and apply it to your behavior for this session
3. During execution, if the user corrects your approach, write a domain-tagged annotation:
   ```json
   {"target":"skill:enterprise-debug","note":"<correction>","author":"enterprise-debug","tags":["feedback","feedback:DEBUG","lesson"],"timestamp":"<ISO>"}
   ```
   Append to `.cortex/knowledge.jsonl`

# Enterprise Debug — 4-Phase Systematic Debugging

## Philosophy

Bugs are never unique. If it is a bug here, it is a bug elsewhere. The blast radius scan is what separates enterprise debugging from guessing.

Three rules:
1. **Find the root cause, not the symptom.** A symptom fix creates two future bugs.
2. **Scan the blast radius.** The same class of bug exists in sibling functions, sibling files, and validation code.
3. **Prove the fix with TDD.** A fix without a failing test is a guess.

```
/enterprise-debug order duplication — processOrder called twice in orderHandler.js
/enterprise-debug test failure: userService.test.js "rejects empty email" now fails
/enterprise-debug users report wrong totals on dashboard page
```

---

## STACK RESOLUTION

Read `.claude/enterprise-state/stack-profile.json` at skill start. Extract:
- `$TEST_CMD` = `commands.test_all`
- `$TEST_SINGLE` = `commands.test_single`
- `$SOURCE_DIR` = `structure.source_dirs.backend`
- `$TENANT_FIELD` = `multi_tenancy.field`
- `$FILE_EXTENSIONS` = `conventions.file_extensions`

If no profile exists: BLOCKED — run /enterprise-discover first.

---

## Phase 1: INVESTIGATE (5-15 minutes)

Goal: reproduce the bug, trace the execution path, form a hypothesis.

### Step 1: Reproduce

Get the exact error. Not a description of the error — the actual error.

```
REPRODUCTION
════════════
Trigger:     [exact steps to reproduce — API call, user action, cron job]
Error:       [exact error message, stack trace, or wrong behavior]
Expected:    [what should happen instead]
Frequency:   [always / intermittent / only under specific conditions]
Environment: [dev / prod / both]
```

If you cannot reproduce, you cannot fix. Spend time here.

**For test failures**: run the failing test and paste the full output.
```bash
$TEST_SINGLE --testPathPattern="<pattern>" --no-coverage 2>&1
```

**For runtime errors**: find the error in logs or reproduce via API call.
```bash
curl -s http://localhost:3000/api/<endpoint> | jq .
```

**For "wrong data" reports**: query the database directly to confirm the data is wrong (not just the display).
```sql
SELECT relevant_columns FROM table WHERE conditions;
```

### Step 2: Trace the Execution Path

Follow the data end-to-end. Every layer. No shortcuts.

```
EXECUTION TRACE
═══════════════
Entry point:  [route/job/webhook that triggers the code]
  → Middleware: [auth, validation — file:line]
  → Route:     [handler function — file:line]
  → Service:   [business logic function — file:line]
  → Query:     [SQL or ORM call — file:line]
  → DB:        [table(s) affected, actual data state]
  → Response:  [what gets returned — file:line]
  → Consumer:  [frontend hook/component — file:line]
  → Render:    [what the user sees — file:line]
```

Read every file in the trace. Do not skip layers. The bug is often NOT where you think it is.

### Step 3: Form a Hypothesis

```
HYPOTHESIS
══════════
I think: [specific root cause]
Because: [evidence from the trace — cite file:line]
This predicts: [if I'm right, then X should also be true]
Verification: [how to test the hypothesis — a query, a log check, a test]
```

Run the verification. If the hypothesis is wrong, form a new one. Do not proceed to Phase 2 until the hypothesis is verified.

### Step 3b: Challenge the Hypothesis (But-Why)

Before accepting your hypothesis, drill into it:

```
HYPOTHESIS CHALLENGE
════════════════════

From anotherben/agentic-governance, MIT.

More from anotherben/agentic-governance