wwwroot 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:
# [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
- 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.).