WordPress Debug Mode

Enable and disable WordPress debug mode safely from inside a theme or plugin directory.

Path Resolution

Before any debug operation, resolve the WordPress root paths. The working directory is assumed to be inside wp-content/themes/<theme>/ or wp-content/plugins/<plugin>/.

Check if ../../../wp-config.php exists (standard depth from theme/plugin root).
If not, check ../../../../wp-config.php (nested projects like plugin/src/).

If still not found, run:

find / -maxdepth 5 -name wp-config.php -not -path '*/vendor/*' 2>/dev/null | head -5

and ask the user to confirm the correct path.

Store the resolved path as WP_CONFIG.
Derive WP_CONTENT — the wp-content/ directory (parent of themes/ or plugins/).
Derive DEBUG_LOG as $WP_CONTENT/debug.log.

Start Debugging

When the user says "start debugging", "debug WordPress", or "enable debug mode":

Step 1 — Check for existing session

If ${WP_CONFIG}.pre-debug-backup already exists, warn the user that a debug session may already be active and ask whether to continue or restore first.

Step 2 — Backup

cp "$WP_CONFIG" "${WP_CONFIG}.pre-debug-backup"

Step 3 — Comment out existing debug constants

In $WP_CONFIG, find and comment out (prefix with // ) any existing define() lines for:

WP_DEBUG
WP_DEBUG_LOG
WP_DEBUG_DISPLAY
SCRIPT_DEBUG
SAVEQUERIES

Use sed or in-place editing. Never duplicate a define() for the same constant.

Step 4 — Insert debug block

Add the following block above the line /* That's all, stop editing! */ in $WP_CONFIG:

// >>> WP DEBUG MODE — added by wp-debug skill
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );
@ini_set( 'display_errors', 0 );
// <<< END WP DEBUG MODE

If the /* That's all, stop editing! */ marker is not found, insert the block after the last existing define() statement instead.

Step 5 — Prepare log

truncate -s 0 "$WP_CONTENT/debug.log" 2>/dev/null || touch "$WP_CONTENT/debug.log"

Step 6 — Tail log

tail -f "$WP_CONTENT/debug.log"

Step 7 — Confirm

Tell the user:

✅ Debug mode is ON. Reproduce the issue in your browser — errors will appear here in real time. Say "stop debugging" when you're done.

Stop Debugging

When the user says "stop debugging", "turn off debug", or "disable debug mode":

Step 1 — Check for backup

If ${WP_CONFIG}.pre-debug-backup does NOT exist:

Check $WP_CONFIG for the // >>> WP DEBUG MODE marker.
If found, warn the user there's no backup but debug mode appears active. Offer to manually remove the debug block.
If not found, inform the user that debug mode does not appear to be active.

Step 2 — Restore

cp "${WP_CONFIG}.pre-debug-backup" "$WP_CONFIG"

Step 3 — Remove backup

rm "${WP_CONFIG}.pre-debug-backup"

Step 4 — Verify

Read $WP_CONFIG and confirm:

The // >>> WP DEBUG MODE block is gone.
No 'WP_DEBUG', true exists.

Step 5 — Confirm

Tell the user:

✅ Debug mode is OFF. Original wp-config.php has been restored. The debug.log file is preserved at wp-content/debug.log in case you still need it.

Analyzing the Log

When the user asks to "analyze the log", "check errors", or "what went wrong":

Read the last 100 lines of $WP_CONTENT/debug.log.
Group errors by type (PHP Fatal, Warning, Notice, Deprecated).
Highlight errors originating from the current theme/plugin directory.
Suggest specific fixes for each error.

Safeguards

Always use wp-config.php.pre-debug-backup as the backup filename, stored next to the original wp-config.php.
Before enabling, always check if a backup already exists.
Never commit a debug-enabled wp-config.php to version control.
Do NOT delete debug.log when stopping — the user may still need it.
WP_DEBUG_DISPLAY is set to false so errors are never shown in the browser (safe for staging/live sites).

What the Debug Block Does

Constant	Effect
`WP_DEBUG = true`	Enables WordPress error reporting
`WP_DEBUG_LOG = true`	Writes errors to `wp-content/debug.log`
`WP_DEBUG_DISPLAY = false`	Hides errors from the browser (safe for live/staging)
`SCRIPT_DEBUG = true`	Uses unminified core CSS/JS files for easier debugging
`SAVEQUERIES = true`	Stores DB queries in `$wpdb->queries` for analysis