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.

1. Auditor identity — name and team or context, recorded in the audit's

auditor field.

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

1. "Controller Inventory" table.
2. "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.