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).