radar: improve wordpress:wp-env v1.1.0

[masoudgolchin]

Opened by the Skill Analyzer — week 2026-W32. Human review is the gate; nothing merges on its own.

Action: improve wordpress:wp-env → v1.1.0 (minor)
Change: Added SSH-key preflight, apex-domain search-replace, uploads-not-pulled note, core-version guard, and a safe caddy-start rule to wp-env.

Why this decision was made: Anchored additions: ssh-add preflight (blocked), caddy-start redirect not pipe (blocked), uploads-not-pulled note, apex domain variant. Multi-session evidence incl. refact-website fork.

The problems that caused it — every quote below was checked character-for-character against the real session transcript before this decision was made:

1. [F-004] The skill is missing a step — had to be redone · wordpress:wp-env v1.1.0 — session af71b25d · credaily-website · skill.missing-instruction
   • What happened: Skill never warns that caddy start forks a daemon inheriting stdout; piping its output (as the skill's own domain-set commands are written) hangs the wrapper, and killing that hung task kills Caddy, taking the local site down.
   • Their words (verbatim, verified against the transcript): "My TaskStop killed Caddy — the pipe kept it attached to that shell. Restarting it properly detached."
   • Smallest fix the judge saw: Add a note to the domain set / Caddy steps: run caddy start with output redirected to a file, never piped through tail/grep, and verify separately with pgrep/curl.
2. [F-005] The skill is unclear — slowed down · wordpress:wp-env v1.1.0 — session af71b25d · credaily-website · skill.ambiguous
   • What happened: Phase 4's URL-variant table lists only staging and the www production URL, so the apex (non-www) domain variant was never replaced, leaving 3,815 posts and 6 options pointing at production.
   • Their words (verbatim, verified against the transcript): "but https://credaily.com (bare domain) survives in 6 options and 3,815 posts — inline editorial links"
   • Smallest fix the judge saw: Add the apex/non-www domain as an explicit variant to check in Phase 4's URL search-replace table, alongside the www production URL.
3. [F-006] The skill is missing a step — work stopped · wordpress:wp-env v1.1.0 — session af71b25d · credaily-website · skill.missing-instruction
   • What happened: The pull preflight (Step 2a) verifies the SSH config fields exist but never checks that the key is actually loaded in the agent (ssh-add -l), so a passphrase-protected key blocks the whole pull with no automated recovery.
   • Their words (verbatim, verified against the transcript): "I can't supply the passphrase — please run this in your terminal:"
   • Smallest fix the judge saw: Add an ssh-add -l check to the pull preflight (Step 2a); if the required key isn't loaded, stop early and tell the user to load it before any export/import work begins.
4. [F-035] The skill gave wrong instructions — slowed down · local:wp-env — session ffdee3ed · refact-website · skill.failed
   • What happened: Step 1h's DB-pull skip check only compares siteurl to localhost:8888/8888 defaults, so on a project with a configured local domain it would have wrongly skipped a needed DB import on a fresh install.
   • Their words (verbatim, verified against the transcript): "the checklist's skip heuristic reads refact.local:8891 only because wp-env baked my WP_HOME override into the fresh install, so a DB pull is genuinely needed"
   • Smallest fix the judge saw: Change the pull-db skip condition to compare siteurl against wp-env defaults OR the configured wpEnv.localDomain, not just localhost:8888.
5. [F-036] The skill is missing a step — slowed down · local:wp-env — session ffdee3ed · refact-website · skill.missing-instruction
   • What happened: The pull-db flow has no guard for core version mismatch between staging and the pinned local WordPress version, so wp core update-db silently downgraded db_version from 61833 to 58975.
   • Their words (verbatim, verified against the transcript): "Staging runs WordPress 7.0.2; .wp-env.json pins WordPress/WordPress#6.8. The import arrived at db_version 61833 and wp core update-db downgraded it to 58975 to match local 6.8."
   • Smallest fix the judge saw: Add a Phase 5 step that compares staging wp core version to .wp-env.json's core pin and asks the user before running wp core update-db if they diverge.
6. [F-054] A skill that fits never loaded — slowed down · wordpress:wp-env — session 997b39f0 · usc-ksom · skill.not-loaded
   • What happened: The wp-env project skill documents Caddy domain setup (/refact wp-env domain set) and its guardrails, but never fired; agent instead spent ~30 tool calls rediscovering Local-by-Flywheel port conflicts and stale cert locks by hand.
   • Their words (verbatim, verified against the transcript): "If a domain is configured but Caddy isn't running yet, also remind the user to run /refact wp-env domain set <hostname>"
   • Smallest fix the judge saw: Have the run skill's project-skill discovery also scan installed plugin skill packs (not just .claude/skills/), so an existing wp-env skill is found before falling back to generic patterns.
7. [F-055] The skill is missing a step — slowed down · wordpress:wp-env — session 997b39f0 · usc-ksom · skill.missing-instruction
   • What happened: wp-env's pull flow only covers plugins, mu-plugins, and db — no media/uploads — so the agent spent many tool calls diagnosing 500s on images before concluding it was expected behavior rather than a bug.
   • Their words (verbatim, verified against the transcript): "alias for pull plugins + mu-plugins + db (staging → local)."
   • Smallest fix the judge saw: Add a line to the wp-env skill noting uploads/media are never pulled locally and that missing-media requests will 404/500 by design.

Edits applied (anchored — nothing outside these anchors changed):

• insert_after @ "- /refact wp-env pull — alias for pull plugins + mu-plugins + db…"
• insert_after @ "If it doesn't print ok, stop. Common causes: wrong port (on WP Engin…"
• replace @ "- The staging url from .refact-os.json - The WP Engine `*.wpengine…"
• insert_after @ "wp db tables --all-tables-with-prefix returns only the tables that m…"
• replace @ " - Skip silently if npm run wp:cli -- option get siteurl returns a…"
• insert_after @ " # If already running: caddy reload --config ~/.refact/Caddyfile …"

Size: 55137 → 57913 chars

Expectation (checked automatically next run, written back into CHANGELOG.md):
wp-env pull/setup no longer blocks on unloaded SSH keys or kills the site on caddy start; missing-step findings drop.
findings.skill.missing-instruction for wordpress:wp-env: baseline 3 → target 1.

Versions bumped: skill 1.1.0 · wordpress 1.1.1 · marketplace 2.12.2.