From wordpress-expert
Structures WordPress diagnostic findings for technical and non-technical audiences with severity ratings, plain-language summaries, technical details, fixes, and action logs. Use for reports, communicating issues, or logging actions.
npx claudepluginhub dr-robert-li/cowork-wordpress-expertThis skill uses the workspace's default tool permissions.
Every finding should be communicated in a way that is **understandable to both technical and non-technical users** who are familiar with WordPress as a platform.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
Every finding should be communicated in a way that is understandable to both technical and non-technical users who are familiar with WordPress as a platform.
For every finding, provide:
Use analogies and plain language:
Bad Example:
"There's a missing nonce verification in the AJAX handler registered on wp_ajax_save_settings, allowing CSRF attacks."
Good Example:
"Your settings page has a security gap. Right now, a malicious website could trick your browser into changing your site's settings without you knowing. Think of it like a door without a lock — anyone who knows where it is can walk in. We need to add verification so WordPress confirms it's really you making the change. Severity: High."
Then provide the technical detail separately for developers.
Be precise and reference-heavy:
"Missing CSRF protection in
save_settings_handler()atincludes/admin/class-settings.php:142. The handler processes$_POST['settings']without callingcheck_ajax_referer()orwp_verify_nonce(). The corresponding form attemplates/admin/settings.php:28does includewp_nonce_field('save_settings', 'settings_nonce'), but the handler never validates it.Fix: Add
check_ajax_referer('save_settings', 'settings_nonce');as the first line ofsave_settings_handler().Test: See
tests/security/Nonce/SaveSettingsNonceTest.php— verifies that requests without valid nonce return 403."
| Severity | Criteria | Response Time |
|---|---|---|
| Critical | Active exploitation possible, data loss imminent, site down | Immediate |
| High | Exploitable vulnerability, significant performance impact, data integrity risk | Within 24 hours |
| Medium | Potential vulnerability requiring specific conditions, moderate performance impact | Within 1 week |
| Low | Minor code quality issue, best practice deviation, cosmetic | Next release cycle |
| Informational | Observation, recommendation, future consideration | No deadline |
Every action you take must be logged. Maintain a running log in this format:
## Action Log — Session [YYYY-MM-DD-HHMMSS]
### Entry [sequential number]
- **Timestamp:** [ISO 8601]
- **Phase:** Discovery | Diagnosis | Remediation | Testing | Documentation
- **Action:** [What you did]
- **Input:** [What you examined — file, screenshot, log entry, etc.]
- **Finding:** [What you found — or "N/A" if action was preparatory]
- **Severity:** Critical | High | Medium | Low | Informational | N/A
- **Evidence:** [File:line, log entry, screenshot reference, query output]
- **Recommendation:** [What should be done — or "N/A" if informational]
- **Status:** Open | In Progress | Resolved | Won't Fix | Deferred
### Entry 003
- **Timestamp:** 2026-02-16T14:32:00Z
- **Phase:** Diagnosis
- **Action:** Analyzed AJAX handler security
- **Input:** includes/admin/class-settings.php
- **Finding:** Missing nonce verification in save_settings_handler()
- **Severity:** High
- **Evidence:** includes/admin/class-settings.php:142 — function processes $_POST without check_ajax_referer()
- **Recommendation:** Add nonce verification as first line of handler function
- **Status:** Open
At the completion of each phase, generate a structured report:
Structure:
Example:
# Discovery Report — 2026-02-16
## Environment
- WordPress: 6.4.3
- PHP: 8.2.10
- Theme: Custom child theme (based on Twenty Twenty-Four)
- Active Plugins: 18 (see full list below)
- Hosting: Managed WordPress (WP Engine)
## Symptom
Admin users report intermittent timeout errors when saving posts with large featured images.
Started approximately 2 weeks ago after a plugin update.
## Scope
- Review image upload and processing flow
- Analyze server-side timeouts
- Check plugin conflicts
- Review recent updates
## Assumptions
- Issue reproducible in production environment
- No server-level changes made during symptom onset
- User reports accurate (not browser-specific)
## Estimated Complexity
Medium — likely plugin conflict or configuration issue, not core WordPress bug.
Structure:
Example:
# Diagnosis Report — 2026-02-16
## Executive Summary
The timeout issue is caused by a recently updated image optimization plugin attempting to process images larger than the server's PHP execution time limit. This affects all users uploading images over 2MB. The plugin's default settings are incompatible with the current server configuration, and there's no error handling to gracefully degrade when timeouts occur.
## Findings
| ID | Severity | Finding | File/Location |
|----|----------|---------|---------------|
| F-001 | High | Image optimization plugin exceeds max_execution_time | wp-content/plugins/image-optimizer/process.php:87 |
| F-002 | Medium | No timeout error handling in upload flow | wp-content/plugins/image-optimizer/upload-handler.php:34 |
| F-003 | Low | PHP max_execution_time set to 30s (recommended 60s for media handling) | php.ini |
## Root Cause
Plugin version 2.3.0 (released 2 weeks ago) changed image processing from asynchronous background job to synchronous inline processing. For images >2MB, processing exceeds 30s PHP timeout.
## Dependency Map
- F-001 causes the timeout
- F-002 prevents graceful fallback
- F-003 compounds the problem but is not the root cause
## Risk Assessment
**Current Risk:** High — large images cannot be uploaded by any user
**Fix Risk:** Low — configuration change + plugin update available
**Workaround Available:** Yes — disable plugin temporarily or set lower quality threshold
Structure:
Example:
# Remediation Report — 2026-02-16
## Changes Made
### 1. Increased PHP max_execution_time
**File:** php.ini
**Change:** `max_execution_time = 30` → `max_execution_time = 60`
**Commit:** abc123f
### 2. Updated Image Optimizer Plugin
**From:** v2.3.0
**To:** v2.3.1 (includes async processing option)
**Commit:** def456a
### 3. Configured Plugin for Async Processing
**File:** wp-content/plugins/image-optimizer/config.php
**Change:** Enabled background processing for images >1MB
**Commit:** ghi789b
## Tests Added
- tests/integration/Media/LargeImageUploadTest.php — verifies uploads up to 5MB complete successfully
## Before/After Metrics
- **Before:** 3MB image upload: timeout after 30s
- **After:** 3MB image upload: completes in 8s (async processing queued)
## Rollback Instructions
```bash
# Restore previous php.ini
cp /backup/php.ini.backup /etc/php/8.2/php.ini
service php-fpm restart
# Downgrade plugin (if needed)
wp plugin install image-optimizer --version=2.2.9 --activate --force
### Testing Report
**Structure:**
- Test suite results (pass/fail counts)
- Coverage metrics (line, branch, function)
- New tests added this session
- Previously passing tests that now fail (regressions)
- Coverage gaps identified
**Example:**
```markdown
# Testing Report — 2026-02-16
## Test Results
PHPUnit 10.5.10 by Sebastian Bergmann and contributors.
Runtime: PHP 8.2.10 Configuration: phpunit.xml.dist
............................................................... 63 / 145 ( 43%) ............................................................... 126 / 145 ( 86%) ................... 145 / 145 (100%)
Time: 00:03.892, Memory: 38.50 MB
OK (145 tests, 423 assertions)
## Coverage Metrics
- **Line Coverage:** 87.3% (target: 85%+) ✓
- **Branch Coverage:** 78.9% (target: 75%+) ✓
- **Function Coverage:** 91.2% (target: 90%+) ✓
## New Tests Added
1. `tests/integration/Media/LargeImageUploadTest.php` — 3 tests
2. `tests/performance/Media/ImageProcessingTimeTest.php` — 2 tests
## Regressions
None — all previously passing tests still pass.
## Coverage Gaps
- Error handling in `includes/media/fallback-processor.php` — only 45% covered
- Recommend adding tests for timeout scenarios
Structure:
Example:
# Documentation Report — 2026-02-16
## Files Updated
1. CHANGELOG.md — Added v1.2.1 entry
2. README.md — Updated "Known Issues" section (removed image upload timeout)
3. docs/configuration.md — Added php.ini recommendations
4. docs/troubleshooting.md — Added image upload timeout troubleshooting steps
## Changelog Entry
```markdown
## [1.2.1] - 2026-02-16
### Fixed
- Fixed timeout errors when uploading large images (>2MB)
- Added async processing option for image optimization
### Changed
- Increased recommended max_execution_time to 60s
- Updated Image Optimizer plugin to v2.3.1
### Added
- Tests for large image upload scenarios
- Troubleshooting documentation for media upload issues
None — no breaking changes, no new endpoints.
Updated WordPress admin help text for media upload page to reference async processing setting.
## Input Materials
You can and should work with **any material the user provides** to support your diagnosis:
| Material Type | What You Extract |
|---|---|
| **Screenshots** | Visual errors, console errors, network waterfall issues, layout breaks, admin error notices |
| **Access logs** | Request patterns, 404s, 500s, slow requests, suspicious IPs, bot traffic |
| **Error logs** | PHP fatals, warnings, notices, deprecated function usage, stack traces |
| **Code files** | Full codebase analysis as detailed in diagnostic domains |
| **Database exports** | Schema review, data integrity, index analysis, option bloat |
| **wp-config.php** | Configuration review (security, debugging, performance constants) |
| **.htaccess / nginx.conf** | Rewrite rules, security headers, caching directives |
| **php.ini / wp-cli.yml** | PHP configuration, CLI configuration |
| **Composer / package.json** | Dependency analysis, version conflicts |
| **Git history** | Recent changes correlated with symptom onset |
| **Performance reports** | GTmetrix, PageSpeed Insights, WebPageTest results |
| **Plugin/theme list** | Version checks against vulnerability databases |
## Self-Generated Validation
You are encouraged to **generate your own diagnostic materials** to validate your approach:
- **Write test scripts** to reproduce reported issues
- **Create database queries** to identify data problems
- **Build proof-of-concept fixes** to validate solutions before recommending them
- **Generate load test scenarios** to confirm performance improvements
- **Create comparison documents** showing before/after states
- **Use browser automation** (when browser use is available) to verify frontend behavior, test user flows, capture screenshots, and validate fixes visually
## File Organization for Deliverables
wp-diagnostics-session-[YYYY-MM-DD]/ ├── README.md # Session overview ├── CHANGELOG.md # Version history ├── reports/ │ ├── 01-discovery-report.md │ ├── 02-diagnosis-report.md │ ├── 03-remediation-report.md │ ├── 04-testing-report.md │ └── 05-documentation-report.md ├── logs/ │ └── action-log.md # Complete action trail ├── findings/ │ ├── security-findings.md │ ├── performance-findings.md │ ├── code-quality-findings.md │ └── architecture-findings.md ├── fixes/ │ ├── [fix-description].patch # Or inline code blocks in reports │ └── ... ├── tests/ │ ├── [test files created during session] │ └── coverage/ │ └── summary.md └── evidence/ ├── screenshots/ ├── logs/ └── queries/
## Versioning & Changelog
### Semantic Versioning
All deliverables follow [Semantic Versioning 2.0.0](https://semver.org/):
- **MAJOR** — Breaking changes to theme/plugin behavior, database schema changes requiring migration, removed functionality
- **MINOR** — New features, new hooks, new admin pages, new REST endpoints (backward-compatible)
- **PATCH** — Bug fixes, security patches, performance improvements, documentation updates (backward-compatible)
### Changelog Format
Maintain a `CHANGELOG.md` in Keep a Changelog format:
```markdown
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Added
- [description of new feature]
### Changed
- [description of change to existing functionality]
### Deprecated
- [description of soon-to-be-removed feature]
### Removed
- [description of removed feature]
### Fixed
- [description of bug fix]
### Security
- [description of security fix — include CVE if applicable]
## [1.0.0] - YYYY-MM-DD
### Added
- Initial release
Update the changelog with every change, no matter how small. Batch related changes under a single version bump.
Every finding should answer: