Orchestrates a 4-phase debugging workflow using Codex for root cause investigation before any fixes. Only activate when user invokes the Codex debugging process.
How this skill is triggered — by the user, by Claude, or both
Slash command
/superpowers-cc-to-codex:systematic-debugging-codexThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!--
Keep Claude in the main thread for user interaction and fix decisions.
Call codex_debug for bounded root cause investigation (Phases 1-3).
Call codex_implement / codex_resume for applying fixes (Phase 4).
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
Do NOT propose or attempt ANY fix until codex_debug has returned root cause evidence.
No exceptions — no matter how obvious the bug seems. If you catch yourself about to
fix something without Codex investigation output, STOP.
You MUST complete these steps in order:
Gather context — collect error messages, stack traces, reproduction steps, recent changes from the user or logs. This is Claude's job.
Dispatch investigator — call the codex_debug MCP tool.
Pass a full prompt body with the reproduction steps, current evidence, recent changes, and the exact question Codex should answer.
{
"tool": "codex_debug",
"arguments": {
"prompt": "Investigate why Codex-backed agents are still doing repository work locally instead of forwarding through the adapter. Include the current failure mode, relevant files, and the strongest root-cause hypothesis supported by code evidence.",
"workspaceRoot": "/absolute/path/to/your/repo"
}
}
Handle the response:
result populated): the investigation conforms to schemas/debug-investigation.schema.json (root_cause, evidence, working_examples, hypothesis, suggested_fix). Proceed to validate (Step 4).codex_debug with a sharper prompt naming the missing pieces (or surface a blocker to the user when needed).result): inspect stderrTail and the resume hint in the error message; resume with codex_resume(taskId="…") once the cause is resolved.Review investigation — Claude validates root_cause and hypothesis are supported by evidence. If evidence is weak, re-dispatch with a more focused prompt.
Decide fix approach:
codex_implement with the root cause and suggested fixImplement single fix — ONE change addressing the root cause. No "while I'm here" improvements. No bundled refactoring.
Handle implementer status (when Step 5 dispatched codex_implement):
Status (from result.status) | Action |
|---|---|
| DONE | Proceed to verify (Step 8) |
| DONE_WITH_CONCERNS | Read concerns; verify regardless, then triage the concerns (resume via codex_resume if blocking) |
| NEEDS_CONTEXT | Provide the requested context and resume the same task with codex_resume(taskId="…") — do NOT re-dispatch as a new implement call |
| BLOCKED | Surface the blocker to the user; if it invalidates the root cause, return to Step 2 |
On error (no result), inspect stderrTail and use the resume hint in the error message to continue via codex_resume.
Verify fix — run tests, confirm resolution, check no regressions.
If fix fails:
Pattern indicating architectural problem:
STOP and question fundamentals — discuss with your human partner before attempting more fixes. This is NOT a failed hypothesis; this is a wrong architecture.
If you catch yourself thinking any of these, return to Step 2:
Available in this directory:
root-cause-tracing.md — Trace bugs backward through call stackdefense-in-depth.md — Add validation at multiple layers after finding root causecondition-based-waiting.md — Replace arbitrary timeouts with condition pollingGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub mzored/superpowers-cc-to-codex --plugin superpowers-cc-to-codex