---
name: craft-debug
description: Codex skill alias for /craft-debug. Debug Craft CMS issues with systematic analysis
---

# Codex Command Alias: /craft-debug

<!-- Generated by tools/generate-codex-command-skills.py; edit the source command instead. -->

- This generated skill exposes the Claude slash command `/craft-debug` to Codex.
- Treat the user's message that invoked this skill as the command arguments.
- When the embedded command body says `$ARGUMENTS`, substitute those user-supplied arguments.
- Follow the embedded command body as the workflow source of truth.
- Translate Claude-only tool names to Codex equivalents when needed: use `update_plan` for TodoWrite-style ledgers, `request_user_input` for AskUserQuestion-style gates when available, and normal chat questions when that tool is not available.
- If the command body says to launch an agent and Codex exposes `multi_agent_v1.spawn_agent`, use that tool with a role-appropriate agent type and a self-contained prompt.
- If the command body requires a nested `Skill(...)` call but Codex exposes no generic Skill tool, execute the referenced skill's documented protocol inline from its SKILL.md and clearly record the adapter mode.
- If neither native tool invocation nor a documented Codex adapter can preserve the workflow's gates, stop and report the missing capability instead of manually approximating the workflow.

## Embedded Claude Command

# Craft CMS Debugger

Help diagnose and fix Craft CMS issues using systematic debugging techniques.

## Debugging Process

1. **Clarify the problem** -- What's happening vs. what should happen?
2. **Gather context** -- Craft version, PHP version, relevant code
3. **Identify the category** -- Query issue, template error, config problem, performance?
4. **Investigate systematically** -- Use appropriate tools and techniques
5. **Propose solutions** -- Explain the fix and why it works

## Common Issue Categories

### Query Returns Nothing
- Check `.status()` -- drafts and disabled entries excluded by default
- Check `.site()` -- multi-site queries need explicit site
- Check field handles -- case-sensitive
- Check `relatedTo` with empty arrays (Craft 5 returns nothing)
- Log the SQL: `{% dd query.getRawSql() %}`

### N+1 Query Performance
- Look for asset/entry access in loops without eager loading
- Add `.with([...])` to the parent query
- Use `.eagerly()` for lazy eager loading in Craft 5+

### Matrix Field Issues
- Ensure querying nested entries, not the field directly
- Check entry type handles for `{% switch %}` statements
- Verify eager loading includes nested relations

### Template Errors
- Check variable scope in includes/embeds
- Verify object exists before accessing properties
- Use null coalescing for optional relations

## MCP Integration

If the Craft MCP server is available:

- `get_last_error` -- See the most recent error
- `read_logs` -- Search application logs
- `get_deprecations` -- Check for deprecated code
- `run_query` -- Test database queries directly
- `explain_query` -- Analyze query performance
- `get_config` -- Verify configuration values

## Output

Provide clear explanations of what's wrong and why. Include code fixes with before/after examples. Explain the underlying concept so the user learns.