# Codex Debug

> Performs systematic root-cause investigation, crash dump analysis, race condition debugging, memory leak tracing, and post-mortem failure analysis. Produces timestamped debugging reports and fix walkthroughs in codex-drive/walkthroughs/.

- Skill: `wwwroot/codex-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wwwroot/codex-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wwwroot/codex-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wwwroot (https://skillmd.com/u/wwwroot)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wwwroot/codex-debug

---


# Codex Debug — Root-Cause Diagnostic & Troubleshooting Skill

> The forensic investigation and debugging engine of AI Codex. Isolates root causes, eliminates speculative fixes, and writes verifiable post-mortem walkthroughs.

---

## Overview

`codex-debug` replaces random guessing with a rigorous scientific debugging method. It establishes a deterministic reproduction, formulates falsifiable hypotheses, traces runtime execution or memory states, identifies the exact line and invariant failure, and provides a verified fix with regression tests.

---

## When to Trigger

- User runs `/codex-debug` (e.g., `/codex-debug investigate 500 error in checkout`, `/codex-debug memory leak in background worker`, `/codex-debug data race on WebSocket connection`)
- Diagnosing failing unit/integration tests, segfaults, unhandled exceptions, or performance regressions
- Post-incident post-mortem analysis

---

## Execution Workflow

```
 ┌────────────────────────────────────────────────────────┐
 │ 1. CAPTURE SYMPTOMS & BUILD MINIMAL REPRODUCTION       │
 │    Stack traces, logs, failing assertions, inputs.     │
 └──────────────────────────┬─────────────────────────────┘
                            │
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │ 2. FORMULATE FALSIFIABLE HYPOTHESES                    │
 │    List probable causes based on domain knowledge.     │
 └──────────────────────────┬─────────────────────────────┘
                            │
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │ 3. ISOLATE ROOT CAUSE VIA PROFILING & TRACING          │
 │    Memory inspection, race auditing, line-level proof. │
 └──────────────────────────┬─────────────────────────────┘
                            │
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │ 4. IMPLEMENT FIX & REGRESSION TEST                     │
 │    Ensure root defect is eliminated and cannot recur.  │
 └──────────────────────────┬─────────────────────────────┘
                            │
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │ 5. WRITE POST-MORTEM IN CODEX-DRIVE                    │
 │    Write codex-drive/walkthroughs/YYYY-MM-DD-*.debug.md│
 └────────────────────────────────────────────────────────┘
```

---

## Debug Walkthrough Specification (`codex-drive/walkthroughs/`)

All debugging reports generated by `codex-debug` MUST be Markdown (`.md`) files with exact date-time metadata.

### Filename Format:
`codex-drive/walkthroughs/YYYY-MM-DD-<slug>.debug.md`

### Standard Debug Post-Mortem Template:

```markdown
# [Issue / Bug Title] Diagnostic & Fix Walkthrough

> **Created At**: YYYY-MM-DD HH:MM:SS (Local Time)
> **Active Codex Edition**: [`skills/codex/<edition>/`](file:///...)
> **Severity**: CRITICAL | HIGH | MEDIUM | LOW
> **Resolution Status**: REPRODUCED | ROOT_CAUSE_CONFIRMED | RESOLVED

---

## 1. Incident Summary & Symptoms
- **Reported Defect**: [Exact error message or unexpected behavior]
- **Environment**: [OS, Runtime version, Hardware/Cloud context]
- **Stack Trace / Error Output**:
```
[Paste relevant logs / stack trace here]
```

## 2. Minimal Reproduction Harness
Step-by-step procedure or unit test that reliably triggers the defect:

```typescript
test("reproduce connection timeout under concurrent load", async () => {
    // Exact test case that failed
});
```

## 3. Scientific Hypothesis & Isolation Matrix

| # | Hypothesis | Test / Verification Method | Result |
|---|---|---|---|
| 1 | Database connection pool exhaustion | Check active pool metrics during burst |  Disproven (Pool had 80% free) |
| 2 | Missing `await` on token refresh causing race | Inspect async call graph with static analysis | [OK] **CONFIRMED ROOT CAUSE** |

## 4. Root Cause Deep Dive
- **Mechanism**: The background token refresh task spawned an unawaited promise, creating a data race where subsequent HTTP requests executed with expired credentials before the new token was committed to memory.
- **Affected Files**: `src/auth/token-manager.ts:L45-L62`

## 5. Applied Solution & Code Diff

```diff
- void refreshToken(); // [WARNING] Fire and forget race condition
+ await this.refreshTokenMutex.runExclusive(async () => {
+     await this.refreshToken();
+ });
```

## 6. Regression Testing & Prevention
- Added automated regression test: `tests/auth/token-race.test.ts`.
- Added linter rule to disallow floating/unawaited promises (`@typescript-eslint/no-floating-promises`).
```

---

## Response Protocol

When `codex-debug` finishes:
1. Provide a direct link to `[View Diagnostic Walkthrough](file:///.../codex-drive/walkthroughs/YYYY-MM-DD-<slug>.debug.md)`.
2. Clearly explain the root cause and the specific invariant that failed.
3. Show the exact code fix and verification command (`npm test`, `pytest`, etc.).