From superpowers-sage
Diagnoses PHP errors, Blade rendering failures, Livewire mount errors, and more in Sage/Acorn/Lando projects using lando logs, Query Monitor, Xdebug, and WP_DEBUG.
How this skill is triggered — by the user, by Claude, or both
Slash command
/superpowers-sage:debugging [error description or symptom][error description or symptom]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Diagnose and fix issues in Sage/Acorn/Lando projects with domain-specific knowledge of common pitfalls.
Diagnose and fix issues in Sage/Acorn/Lando projects with domain-specific knowledge of common pitfalls.
Base skill: This wraps systematic-debugging with Sage domain knowledge.
$ARGUMENTS
| Category | Symptoms | First Check |
|---|---|---|
| Blade/View Cache | Template not updating, old content showing | lando flush |
| OPcache | PHP changes not reflected despite cache clear | lando restart |
| Vite/HMR | Styles missing, HMR not connecting | Check dev server, vite.config.js |
| ACF Registration | Block not appearing, fields missing | ACF sync, block class $name |
| Lando Services | Container errors, service unavailable | lando info, service logs |
| Acorn Boot | Command not found, provider failure | lando wp acorn, config cache |
| Livewire | Component not rendering, wire actions failing | Install check, CSRF, Alpine |
| Tailwind Purge | Classes not applying in production | @source paths, CSS-first config |
| Database | Connection refused, migration errors | .env DB config, Lando service |
| Autoload | Class not found | lando theme-composer dump-autoload |
Based on category, investigate:
lando flush # Clear all caches
ls content/cache/acorn/framework/views/ # Check for stale compiled views
lando flush doesn't help, check for stale files directlylando restart for FPMlando vite # Start dev server
vite.config.js: server.host must be '0.0.0.0'.lando.yml proxy includes Vite port@vite() directive in layout bladelando acorn acf:sync # Sync field groups
$name must be kebab-casefields() must call setLocation()with() must return arraylando theme-composer dump-autoload
App\Blocks\ → app/Blocks/| Problem | Root Cause | Fix |
|---|---|---|
| Blade cache not clearing | Stale compiled views | lando flush (uses custom Lando tooling) |
| OPcache stale after edit | PHP-FPM OPcache != CLI OPcache | lando restart |
| Grid classes not rendering | Dynamic classes purged by Tailwind v4 | Use inline styles for dynamic grids |
lando acorn broken | Path misconfiguration | Use lando wp acorn instead |
| Material Symbols not rendering | Wrong icon name (not in symbol set) | Check Material Symbols catalog |
| Block content wrong after edit | Stale Blade cache + OPcache | Delete specific cache file + lando flush |
## Diagnosis: {issue summary}
### Root Cause
{What's causing the issue — with evidence}
### Fix
{Step-by-step commands and/or code changes}
### Prevention
{How to avoid this in the future}
Run verification after applying fix. If issue persists, dig deeper or escalate to adjacent category.
| Symptom | Quick Fix |
|---|---|
| Blade not updating | lando flush |
| Class not found | lando theme-composer dump-autoload |
| ACF fields missing | lando acorn acf:sync |
| Vite HMR broken | Check server.host in vite.config.js is '0.0.0.0' |
acorn command not found | lando wp acorn or check --path in .lando.yml |
| Styles not in editor | Add editor.css to Vite entry points |
lando flush first — clears Blade cache, OPcache, Acorn cache in one commandsystematic-debugging as the base approachsage-debugger agent for automated investigationnpx claudepluginhub hekivo/superpowers-sageSets up and modifies Roots Sage + Acorn WordPress themes in Lando environments: ACF blocks, Blade components, Vite/Tailwind frontend, service providers, and CPTs.
Develops WordPress themes using Sage framework: create from scratch, set up Blade templates/components, configure Vite/Bud builds, handle template hierarchy, integrate ACF fields, manage assets.
Guides phased root cause investigation for Laravel issues including test failures, Eloquent queries, bugs, queues, migrations, and performance before fixes.