wp-introspect

name	wp-introspect
description	Read-only runtime snapshot of WordPress internals via the companion's `/introspect` endpoint — hooks, transients, options, request_state, hook callbacks. Phase = Debug.
when_to_use	user is debugging a hook firing order / transient stuck / option value mystery / "who is listening to this filter", OR wants to inspect runtime state without writing
tier	1
phase	debug

WP Introspect

Read-only runtime visibility into WordPress. Covers four scopes via the companion /introspect endpoint plus hook_state for callback enumeration. Pure read — never writes, never evaluates code (that is wp-execute-php).

Iron Rule

1. NEVER set `include_values: true` on production-matched siteurl — option/transient values may contain API keys, third-party tokens, or PII; the production guard fires server-side but client should self-gate first. 2. NEVER call `introspect` repeatedly in a tight loop — every call is a full PHP request; for repeated polling use `request-observer` instead (see `references/introspect-scopes.md`). 3. ALWAYS pair the right scope to the question — `hooks` answers "who is listening", `options_full` answers "what is stored", `transients` answers "what is cached", `request_state` answers "what's the current request"; using `options_full` for a hook question wastes context.

When to use

• "Why is filter X not firing?" → hooks scope + hook_state on that hook.
• "Why is the transient cache cold?" → transients scope.
• "What option does plugin X store?" → options_full (names only, then targeted lookup).
• "What's the current request lifecycle state?" → request_state.

Skip when:

• The question needs PHP-level mutation (run a function, set a variable) → wp-execute-php.
• The question is a multi-probe diagnostic (slow queries + plugin conflicts + PHP errors) → wp-diagnose.
• The question is post/page content → core REST via wp-content.

Boundary

Owns:

• rolepod_wp_introspect (all 4 scopes).
• rolepod_wp_hook_state (specific hook → callbacks listed).
• Read-only access to the companion /introspect endpoint.

Does not own:

• Mutation of any runtime state → wp-execute-php (with safety chain).
• Analysis / ranking / report (turning raw introspect data into ranked findings) → wp-diagnose.
• File-level reads → file_read.

Return / hand off:

• Question requires writing → wp-execute-php.
• Question requires CPU-deep probe (slow queries, php_errors) → wp-diagnose.

Inputs to gather

• target_id.
• scope (hooks / transients / options_full / request_state).
• include_values: true ONLY on non-production targets, and only with explicit user OK.
• For hook_state: the hook name (e.g. wp_head, save_post, woocommerce_checkout_order_processed).

Workflow

1. Pick the scope

See references/introspect-scopes.md for the per-scope decision tree.

2. Call

Single rolepod_wp_introspect { target_id, scope, include_values? } OR rolepod_wp_hook_state { target_id, hook }.

3. Surface

Print the result raw. Do not summarize. The user is debugging — they need verbatim.

4. Hand off if needed

If the introspect reveals a problem worth diagnosing in depth → wp-diagnose. If it reveals a fix that needs runtime PHP → wp-execute-php.

If a matching Rolepod agent is available

• rolepod:debug-issue (Rolepod parent skill) for the broader debug workflow this introspect feeds into.
• rolepod:backend-developer for hook-callback investigation.

If no matching agent is available

1. Pick the scope.
2. Call.
3. Surface verbatim.
4. Suggest the next phase if the result requires action.

Output

No durable artifact. The introspect response is the value — surface it directly.

Examples

No examples file. The four scopes are documented in references with concrete inputs/outputs.

References

Load when picking a scope or when an introspect result is unfamiliar:

• references/introspect-scopes.md — per-scope decision tree, sample output shape, common pitfalls (transients with sub-resources, options_full size, hook priority sort, request_state during REST vs admin-ajax).

Hard stops

• include_values: true AND target is production-matched → STOP, refuse client-side, do not pass to server (server would refuse too but the request leaks intent).
• Companion not installed → STOP, hand off to user with companion install URL.
• Scope mistyped (not in {hooks, transients, options_full, request_state}) → STOP, surface the schema error.

Full Rolepod enhancement

Full Rolepod adds historical introspect diffing (compare today's hook map to yesterday's) using per-site ~/.config/rolepod-wplab/memory/. Standalone, each call is point-in-time.

Next phase

• Result + intent to fix → wp-execute-php (PHP eval) OR wp-content (REST write) OR wp-edit-plugin (plugin config).
• Result is concerning → wp-diagnose for the full multi-probe view.
• Result is benign → done.