Menu
Use when encountering any bug, test failure, blank screen of death, or unexpected behavior in ProcessWire before proposing fixes.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | pw-systematic-debugging |
| description | Use when encountering any bug, test failure, blank screen of death, or unexpected behavior in ProcessWire before proposing fixes. |
| risk | safe |
| source | processwire-boost |
| date_added | 2026-04-13 |
Random fixes waste time and mask underlying issues. ProcessWire notoriously swallows exceptions inside hooks and template renders, making "guessing the bug" a guaranteed failure.
NO FIXES OR FILE MODIFICATIONS WITHOUT ROOT CAUSE INVESTIGATION (LOG READING) FIRST. If you have not read the logs via MCP or checked ProcessWire context, you cannot propose fixes.Before running any fix, you must retrieve the actual error stack.
Read System Logs (MCP Server)
ProcessWire stores fatal errors and exceptions in textual log files (site/assets/logs/).
pw_system_get_logs to list available logs.pw_system_logs_tail_last on errors or exceptions.Verify Debug Mode
If logs are empty but the system is failing (e.g. HTTP 500 or Blank White Screen), ensure debug mode is on.
Check site/config.php for $config->debug = true;.
Hook Tracing
If an event isn't firing (e.g., Pages::saved), ensure your Hook isn't intentionally bypassing execution or failing silently. Insert explicit logging right inside the hook temporarily:
$event->wire()->log->save('debug', "Hook fired for page ID: " . $event->arguments(0)->id);
Once evidence is gathered from the logs, form a specific hypothesis.
$pages->get('template=foo') returned a NullPage, and we didn't verify $page->id before interacting with it."if($page && $page->id)).pw_execute, CLI script, or reloading the endpoint).errors.txt via MCP.@ (error suppressor) or burying problems in generic try-catch blocks without understanding why the ProcessWire API failed.NullPage Logic: pw-expert rule violation. $pages->get() returns an empty NullPage object, not null or false. if($page === null) will fail. You must check if($page->id).Once the root cause is successfully verified via minimal steps, either apply the fix immediately or invoke writing-plans if the refactor is substantial.
Use when building, structuring, or refactoring native backend modules for ProcessWire using PHP 8.4 and strict typing.
Use when designing, structuring, or rendering HTML for ProcessWire Admin interfaces, custom Process modules, or Inputfields.
Use when brainstorming or designing ProcessWire modules, templates, field schemas, or hooks to resolve ambiguity and validate architecture before implementation.
Use when creating, executing, or managing Pest tests within ProcessWire or ProcessWire modules, including Test-Driven Development (TDD) tasks.
Use when creating or updating module documentation, package READMEs, architecture guides, or CLI command references for ProcessWire projects.
Use when creating implementation plans from approved specifications to ensure ProcessWire-native architecture, safe migration structures, and strict test-driven task execution.