wp-abilities-audit

WP Abilities Audit

Produce a standardized audit document for a WordPress plugin's REST surface, proposing a set of Abilities API registrations grouped by semantic intent. The audit doc is a planning artifact for implementers — humans, agents, or both — that captures the controller inventory, capability gates, and proposed ability shapes in a structured form. A reviewer reading the doc can scope the work without re-deriving the survey.

This skill works on any plugin that exposes a REST surface. Plugin classification (for purposes of the optional plugin_family annotation) is the user's call; the workflow itself is plugin-agnostic.

When to use

• The task is "register Abilities API abilities for a WP plugin" and no audit doc exists yet.
• Planning participation in a multi-plugin abilities rollout and need a shareable, standardized audit artifact.
• Pre-flight checking a plugin's agent-readiness before implementing abilities.
• A PM or non-implementer wants to scope the work before engineering picks it up.

Inputs required

1. Plugin checkout path — working tree of the plugin to audit.
2. Triage output — run wp-project-triage first if not already done. The audit consumes signals.usesAbilitiesApi, versions.wordpress, and project.kind from the report.
3. Auditor identity — name and team or context, recorded in the audit's auditor field.
4. Output path — where the audit doc should land. Default explicit over implicit; ask if not provided rather than writing into the plugin worktree.

Prerequisites

• wp-project-triage has run successfully and classified the plugin.
• The plugin has at least one REST controller. If enumeration finds zero controllers, the audit doesn't apply — see "Failure modes" below.

Procedure

1. Enumerate REST controllers

Read references/controller-enumeration.md now — it covers the two observed enumeration paths (glob for standard layouts, grep as the universal fallback) and when to use each.

Record every controller class + file + REST base + routes in a "Controller Inventory" table. The inventory is exhaustive even though only a subset becomes proposed abilities.

2. For each controller, extract the backing fields

For every controller found, extract the fields the audit schema requires: class, file, HTTP method, route, route-registration line number, callback name, callback line number, permission callback, whether the callback takes a WP_REST_Request argument or is zero-arg, and the return type.

Read references/audit-schema.md now for the exact field list and the shape of proposed_abilities entries. Line-number fields may be null for inherited callbacks — the schema allows this and pairs it with an optional inherited_from field.

3. Confirm capability gate(s)

Trace each controller's permission_callback to its current_user_can() call (or to the post-type capability machinery if the controller extends a post-type-backed base).

Read references/capability-gate-tracing.md now — it documents the two common mechanisms (direct check_permission() vs post-type-backed wc_rest_check_post_permissions()) and how to represent each in the schema. Note explicitly whether read and write gates differ: compound gates are represented as a {read, write} object, not a single string.

4. Propose abilities using semantic-intent grouping

Do NOT atomize one ability per HTTP method. Apply the semantic-intent grouping heuristic — it's the only grouping rule this skill uses.

Read ../wp-abilities-api/references/grouping-heuristic.md now — do NOT re-derive the rules here. Short version: one ability per real-world question or state transition, with filter parameters in input_schema collapsing N variants into 1.

Apply the use-case sanity check before populating any candidate. Per ../wp-abilities-api/references/domain-vs-projection.md's use-case-contract test: would a human or agent intentionally perform this behavior through a supported plugin workflow? If yes, the candidate is a real ability — proceed to fill in fields. If no, the route is internal transport plumbing (cache invalidation, scheduler ticks, bookkeeping endpoints, debug introspection) — keep it in the Controller Inventory section for completeness, but do NOT promote it to proposed_abilities. The route may be useful to inventory; the proposed ability must represent a real user/operator question or action.

For each proposed ability that passes the sanity check, fill in every field in the proposed_abilities schema: name, intent, backing, permission, return_type, effort (S/M/L), annotations (readonly/destructive/idempotent), notes, risks, use_case_fit, side_effects, seed_data_needs.

The last three are the implementation-readiness facts the implementer and the verify-mode tooling both need: which human/agent workflow this ability serves (use_case_fit), what the backing path emits on every call (side_effects — empty array is a fact, not a missing value), and what representative data must exist in the test environment for the ability to execute through the public boundary (seed_data_needs).

5. Surface gaps and deferred items

Three buckets:

• excluded_from_mvp — candidates intentionally deferred for risk reasons (real-money writes, irreversible state changes, or prerequisite design work). Each entry gets a one-sentence reason.
• surfaced_gaps — MVP candidates with no backing endpoint (ability with backing: null), plus high-value endpoints discovered during enumeration that aren't in the MVP list but would be easy future wins.
• Risks per ability — anything about a backing endpoint that the implementer must handle (no idempotency key, two-phase behavior, state-transition caveats, zero-arg endpoints registered with permission_callback => '__return_true' that must NOT copy that into the ability registration).

6. Write the audit doc

Write to the explicit output path collected in "Inputs required". The document structure must match references/audit-schema.md exactly:

1. Last updated: YYYY-MM-DD HH:MM header.
2. YAML block with all required top-level metadata + proposed_abilities, excluded_from_mvp, surfaced_gaps.
3. "Controller Inventory" table.
4. "Notes and Surprises" prose section.

A copy-pasteable minimal example showing the full shape lives in references/audit-schema.md under "Minimal valid example" — start there when authoring a new audit.

7. (Optional) Designate a reference implementation ability

Set reference_ability: true on the first ability an implementer should land — typically the smallest, safest, highest-leverage read. This gives downstream workflows a deterministic starting point.

Verification

• The audit conforms to references/audit-schema.md (all required top-level fields present, at least one entry in proposed_abilities, annotations complete on every ability).
• capability_gate is a string for single-cap plugins or a {read, write} object for post-type-backed plugins.
• Every ability with backing: null also appears in surfaced_gaps.
• The doc round-trips through the validator in audit-schema.md "Known limitations" without errors.

Failure modes / debugging

• Plugin has no REST controllers — audit doesn't apply. Consider hooks/filters-based abilities (out of scope for this skill's current version) or skip abilities adoption for this plugin.
• Plugin inherits controllers from another repo (common for plugins extending core post-type-backed controllers like WP_REST_Posts_Controller, or extension plugins built on a parent's REST classes) — capture with backing.inherited_from: "<parent FQCN>". Line-number fields may be null per the schema.
• Compound capability gate (distinct read/write caps) — use the structured {read, write} form documented in references/capability-gate-tracing.md. Don't smuggle a /-separated string into a field typed as a single cap.
• Ambiguous grouping — route to ../wp-abilities-api/references/grouping-heuristic.md. Do not invent alternative grouping rules in the audit doc.
• Zero-arg endpoints with permission_callback => '__return_true' — legal at the REST layer, but the ability's own permission_callback must match the plugin's merchant gate. Never promote '__return_true' into an ability registration. Note this in the ability's risks.
• Output path defaults to plugin worktree — always ask the user for an explicit output directory (e.g. their vault plans/). Writing the audit into the plugin's own git history pollutes the worktree and buries the artifact.

Escalation

• If the plugin uses an enumeration convention not covered by references/controller-enumeration.md (neither the standard glob nor the grep fallback produces a complete inventory), update that reference with the new convention and open a PR so future audits cover it deterministically.
• If capability tracing hits a mechanism not covered by references/capability-gate-tracing.md, extend that file rather than encoding the new case in the audit's "Notes and Surprises" only.